🖊️

Markdownの方言とMarkdown プレビュアー Glance Vimの紹介

2022/02/05に公開約3,600字2件のコメント

Markdownの方言

世の中には沢山のMarkdownの方言があります。

GitHub Flavored Markdown, Pandoc Markdown, Stack Overflow Markdown,
Qiita Markdown, Zenn Markdown, dev.to Markodown, GitLab Markdown,
Hatena Markdown, BitBucket Markdown, Common Mark ...

Markdownをサービスに組み込もうとすると各々が拡張構文を加えてしまうため
そのサービスに応じて独自方言が生れます。
ところでMarkdown ItというMarkdown to HTMLなライブラリをご存知でしょうか?
これはVisual Studio CodeのMarkdownのレンダリングにも使われている有名な
JavaScriptのライブラリです。Markdown Itにはプラグイン機構があり、
ユーザーが独自でMarkdownの処理を拡張できるようになっています。

2022年2月現在、npmjs.comにアップロードされているMarkdown Itの拡張機能は
686個ありました。機能的に重複しているものも沢山ありますが、
この拡張機能の組み合わせの数は2^{686}に登ります。
人の数だけMarkdownの方言があるのもうなずけますね。

さて、このように沢山のMarkdownの方言があるとプレビュアーを使うのも大変です。
自分の書いたMarkdownを適切に表示してくれるのを探すのは困難です。
とくに数式の処理や図の処理、テーブル記法は方言によって違いが大きく、
相性が悪いと表示が大きく崩れます。

Glance Vimの紹介

https://github.com/tani/glance-vim

Glance Vimは、この問題を解決するために開発したプラグインです。
これは数あるMarkdownのプレビュアーと同じように基本的な機能はもちろん供えています。

  • 自動スクロール: 現在編集している行に同期してプレビュー画面をスクロールします
  • 自動更新: 現在編集中の内容をプレビュー画面に即時反映します
  • プレアンブル: 出力HTMLに適当な文字列を注入します
  • オフライン: レンダリングに使用したライブラリはDenoがローカルにキャッシュします

ちなみにglanceとは"一瞥する,チラりと見る"という意味だそうです.

もっとも簡単な使い方は以下の通りです。

  1. Markdownファイルを開く
  2. :Glance と入力しプレビュー用のサーバーを立ち上げる
  3. http://localhost:8765 にブラウザでアクセスする。

以下では3つの段階に応じてレシピ形式で使い方を説明します。

簡易的な使い方

このプラグインはdenopsに依存しています.
そのためインストールする方法は以下のようになります.

Plug 'vim-denops/denops.vim'
Plug 'tani/glance-vim'

なお単にMarkdownの表示を見るだけならば殆ど設定する必要はありません。
方言ごとの多少の差異は以下の設定で対応できます。

レシピ: 改行を許す

GitHubのIssuesなどでは改行を自動で<br/>に変換する機能があります。
この機能を有効にするのであれば以下のように設定してください。

let g:glance#markdown_breaks = v:true

レシピ: HTMLを許す

多くのMarkdownの方言では表現力の弱さを軽減させるためにHTMLの使用を許しています。
この機能を有効にするのであれば以下のように設定してください。

let g:glance#markdown_html = v:true

レシピ: URLを自動でa要素に変換する

URLを文字列としてでなく、HTMLリンクとして扱えると便利な場合があります。
この機能を有効にするのであれば以下のように設定してください。

let g:glance#markdown_linkify = v:true

レシピ: 独自のスタイルシートを読み込む

Glance Vimでは最低限のスタイルシートしか提供していません。
もしウェブサービス独自のスタイルシートを使いたいのであれば、
以下のように設定してください。

let g:glance#stylesheet = '@import url("https://cdn.jsdelivr.net/npm/water.css@2/out/water.css");'

基本的な使い方

さて、前述のように多少の差異ではなく、絵文字や数式など記法レベルで拡張をしたいときがあります。
この場合は、markdown-itのプラグインを動的に読み込むことで対応できます。

レシピ: 絵文字を使う

絵文字を:smile:のような記法で入力したい場合、markdown-it-emojiが便利でしょう。
esm.shesm.runなどのESM対応のCDNから,
markdown-it-emojiを読み込みましょう。Glance Vimが内部で動的に読み込みます。

let g:glance#markdown_plugins = ['https://esm.sh/markdown-it-emoji']

レシピ: 数式を使う

LaTeX風の記法で数式 $ ... $ を入力したい場合、markdown-it-mathjax3が便利でしょう。
esm.shesm.runなどのESM対応のCDNから,
markdown-it-katexを読み込みましょう。Glance Vimが内部で動的に読み込みます。

let g:glance#markdown_plugins = ['https://esm.sh/markdown-it-mathjax3?bundle']

応用的な使い方

さて、markdown-itのプラグインは便利ですが、高度な使い方としてオプションを
渡したり、はたまま独自のmarkdown-itプラグインを拡張追加したいことがあります。
その場合, Glance VimではTypeScriptによる設定ファイルの読み込みが使えます。

レシピ: Markdown It Emojiを使う

絵文字には沢山の種類があります。markdown-it-emojiは:smile:記法のみを扱いますが、
オプションを渡すことで :)のような顔文字を変換することができます。

まず、読み込む設定ファイルのパスを設定します。

let g:glance#config = expand('~/.config/glance/init.ts')

次に設定ファイルをTypeScriptで書きます。
設定ファイルでは、かならず createMarkdownRendererという関数をエクスポートする必要があります。

// ~/.config/glance/init.ts
import markdownItEmoji from 'https://esm.sh/markdown-it-emoji'
import MarkdownIt from 'https://esm.sh/markdown-it'

export function createMarkdownRenderer(md: MarkdownIt): MarkdownIt {
  return md.use(markdownItEmoji, { shortcuts: { smile: ":)" } });
}

まとめ

Glance Vimは あなたのための Markdownプレビュアーです。
これを使ってあなたのMarkdonwn方言のプレビューをしてくださいね

GitHubで編集を提案

Discussion

「簡易的な使い方」どおりにプラグインをインストールし、ごくシンプルなMarkdownファイルを読み込んで :Glance を実行しましたが、Webブラウザで http://localhost:8765 を開いてもページに何も表示されません。ページのソースを開いてみましたが、bodyタグの中にはiframeタグしかなく、vimに読み込んだMarkdownのコンテンツは何もありませんでした (headタグの中にはscriptタグがあり、いろいろ書かれていました)。

:Glance を実行する前後に何かする必要があるのでしょうか。

ちなみに、glanceが正しく機能したのなら、ブラウザ上ではどのように表示されるのでしょうか。vimのインサートモードでMarkdownを記述し、ノーマルモードに戻ったタイミングでブラウザに反映されるのでしょうか。

環境

  • OS : NixOS 21.11
  • ブラウザ : Google Chrome 98.0.4758.80
  • vim : neovim (NVIM) 0.7.0-dev
  • deno : deno 1.16.2

返事が遅くなってしまい,すみません.コメントありがとうございます.
Glanceのフロントエンド側でIframe要素を取得するタイミングが早過ぎてブラウザによっては,変数が正しく初期化されていなかったようです.適切なタイミングに変更しましたので恐らく動作すると思われます.ご確認くださいませ!

ログインするとコメントできます