単子葉類プログラマーのメモ

プログラミング関連の自分用メモだけど他の人の役に立つかもしれないので公開しておく感じのブログ

MarkdownをブラウザでWebページっぽく表示するツールを作った

MDWikiを使っていたが、不満があったので似たようなものを自作した。

https://github.com/shining-corn/markdown-viewer-html

使い方

MarkdownファイルとWebサーバは事前に用意しておく。

  1. 上記リポジトリのdistフォルダにあるindex.htmlmdvh.jsを任意のWebサーバに置く
  2. MarkdownファイルもWebサーバに置く
  3. ブラウザでindex.html?mdpath={Markdownファイル}を開く

クエリーパラメータmdpathを指定しなかった場合はデフォルトで、同じディレクトリにあるindex.mdを表示する。

動作例

https://shining-corn.github.io/markdown-viewer-html/?mdpath=./index.md

なぜ作ったか

MDWikiの以下の点に不満があったから。

  • Markdownの解釈が普段使っているほかのツールと少し違う
    • 例えばVSCodeのプレビューと細かいところでずれがある
  • gimmicksの書式が独特なので、mermaidで書いたUML図をVSCodeでプレビューできない

作り方

ほぼnpmで公開されているライブラリを利用するだけで済んだ。

MarkdownからHTMLへの変換はmarkdown-itがすべてやってくれる。

markdown-itのプラグインgithubに公開されているので、Markdownの拡張書式も追加できる。以下のプラグインを取り込んだ。

機能 プラグイン
UML GitHub - iamcco/md-it-mermaid: markdown-it plugin for mermaid
注釈 GitHub - markdown-it/markdown-it-footnote: Footnotes plugin for markdown-it markdown parser
目次 markdown-it-table-of-contents - npm
BootstrapのAlerts GitHub - nunof07/markdown-it-alerts: Markdown-it plugin to create Bootstrap alerts
(readmeには明記されていないが、BootstrapのAlertsのうちsuccessinfowarningdangerしか使えないようである。)
数式 GitHub - runarberg/markdown-it-math: Markdown-it plugin to include math in your document
動画埋め込み markdown-it-block-embed - npm

スタイルシートは、githubと同じものがMITライセンスで公開されていたので利用させてもらった。

以下の部分は自分で作る必要があった。

  • 他ファイルへのリンクの書き換え
    • クエリーパラメータでMarkdownファイルのパスを指定するという仕組みにしているので、subdir/another.mdのようなURLをindex.html?mdpath=subdir/another.mdのように書き換える必要がある。
    • Markdown以外のファイルやディレクトリへのリンクも適宜書き換える必要がある。
  • クエリーパラメータで指定されたMarkdownファイルの読み込み
    • ちなみに最初はmdpathではなくpという名前にしていたが、一部のWebサーバは独自にクエリーパラメータをサポートしている場合があり、それとパラメータ名が重複してしまった結果、ファイル読み込みが常に404 Not Foundエラーになってしまった。
  • ハッシュつきURLで開かれた場合の画面スクロール
    • htmlがブラウザにロードされた後でMarkdownファイルを読み込んで変換とレンダリングをしているので、タイミングの関係上、ハッシュへの移動はブラウザ任せにできない。レンダリングが終わったあとでwindow.scroll()する必要がある。
  • その他細かい処理