ただの風邪。

音楽のことを中心にいろいろと書いています。

■カテゴリ別ショートカット

レビュー(音楽) レビュー(本) エッセイ、考えごと

Visual Studio CodeのMarkdown Previewに脚注記法を対応させた話

 エディタをAtomからVisual Studio Code(以下vscode)に乗り換えた。心持ちこっちのが軽快だったからだ。いじる言語もそんなに多くないし使い勝手もさほど変わらない。ショートカットキーを覚え直すのには若干うんざりしているけれど。ただ、どうしても気になるところがあったので、ちょっと調べて頑張ってみた。脚注が使えるMarkdown Previewをvscodeに!

Markdownと脚注

 さて、vscodeを使う最大の目的のひとつはMarkdownでドキュメントを書くことなのだけれど、Atomにせよvscodeにせよ、デフォルトのMarkdown Previewには若干不満があった。脚注に対応していないのだ。いくつかの方言は脚注を記法に組み込んでいるのだけれど(PHPとか)、とりわけAtomについては開発元のGithubが対応していないこともあって見込み薄(だったような。もしかして最近変わったかな)。というのが要因だろうと思う。

 そうそう、Markdown記法を採用しているはてなブログも脚注使えな…… と思ったら、いつのまにか脚注記法に対応していた。PHPの拡張に基づいているそうだ。(以下記事の「ほか一件」がそれに相当する)

staff.hatenablog.com

 具体的にはこんなんだ。

 脚注入ります。[^1]

 [^1]: 脚注入りました

 上記のようにするとリンク付きの脚注が生成される。1この記法はpandocの拡張なんかと共通している。しかし、pandocの拡張記法に採用されているインライン脚注、すなわち ^[こういうふうに編集中の本文に註をそのまま書ける] ような記法が実は一番欲しかったりする。はてな記法における ((二重括弧による脚注))*1に慣れ親しんでいるせい、というのもあるし、いちいちナンバリングするのが億劫だ。ただ、インライン脚注はMarkdownの「プレーンテクストそのままでも可読性を失わない」という利点を犠牲にしてしまうし、本文中の [^1] と定義 [^1]: の対応をきちんと自分でマネジメントするのは長文を欠くときにはかえって大事かも。とは思う。2

vscode内のmarkdown-itをプラグインで拡張する

 話が飛んでしまったが、vscodeMarkdown Previewに脚注記法を対応させられないか、という話。どうやら少し前のヴァージョンからMarkdownのパーサーとしてMarkdown-it!というjavascriptベースのものを採用しているらしいこと、このパーサーがプラグインによって記法を拡張可能だ、ということがわかった。探してみると、markdown-it-footnoteというそのものズバリのプラグインを発見。pandocの拡張記法に基いていることから、[^1][^1]: にも ^[インライン脚注] にも対応しているそうだ。そういうわけで、なんとかしてvscodeのなかで動いているmarkdown-itにプラグインを適用できればひとまず目的は達成できることになる。

 調べてみると、StackOverflowにmarkdown-it-emojiプラグインをvscodeで使いたい旨のスレッドがあって、親切な回答者によって実装例が示されていた。

github.com

 これをmarkdown-it-footnote用に改変するのはさほど面倒でもなさそうだ。ただし、このプロジェクトをまるごと流用しても上手く拡張ファイルをコンパイルできない可能性がある(というかできなかった)ので、あくまでこれを参考にイチからスクリプトを書くことにする。vscode拡張機能の開発環境はNode.jsをベースとして提供されているため、早速Node.jsをインストールし、環境の構築からはじめる。

vscode拡張機能の作り方 with Yo(Yeoman)

 Node.jsをインストールしたら、npmからMarkdown-it!markdown-it-footnoteといった必要なパッケージをインストールしたうえで、Yeomanをインストールする。今回は以下の記事にしたがって、vscodeの拡張向け環境を生成するgenerator-codeをピンポイントでインストールした。その他Yeoman一般のインストール方法とかはは右の記事(Yeomanのあれこれ - Qiita)を参照するとだいたいなんかわかると思う。

d.hatena.ne.jp

 コマンドプロンプトyo codeと突っ込むと、アスキーアートで描かれた変なおっさんが陽気に出迎えてくれて、質問に答えていくと勝手に環境一式が整ったディレクトリを作ってくれる。割と適当にぽんぽんぽんと雰囲気でやっていく(ただ、実験なのでGithubリポジトリは用意しなかった)。準備が済むと、ディレクトリを移動してvscodeにプロジェクトを開くよう促される。

 そうして出来上がったディレクトリの構成を先程取り上げたvscode-markdown-emojiと比較してみる。さほど変わらないというか、肝心のスクリプト自体も(動作を理解するのはともかく)導入するプラグインを書き換えるくらいはすぐできそうだ。具体的に編集が必要なのは、以下に示したうち「←」部分。

─プロジェクト名
    │  .gitignore (←Gitで管理/Githubで公開するならいる?)
    │  .vscodeignore
    │  package.json ←
    │  tsconfig.json ←
    │  CHANGELOG.md
    │  README.md   ←
    │  vsc-extension-quickstart.md
    │
    ├─ .vscode
    │    launch.json
    │    settings.json
    │    tasks.json
    │
    ├─ node_modules
    │    └(ディレクトリいっぱいなので略)
    │
    ├─ src
    │    extension.ts ←
    │
    └─ test
         extension.test.ts
         index.ts

 加えて、もしGithub等で公開する場合にはライセンス表記を明示するファイルも必要になるだろう。~emojiのMITライセンスを継承(ファイルをコピペ)すればよいと思うけど。具体的なファイルのいじり方は、上で示したファイルをvscode-markdown-emojiの同名ファイルと逐次対照していけばすぐにわかると思う。また、プロジェクトディレクトリ直下のREADME.mdはデフォルトの状態から変更しないままだと拡張ファイルをコンパイルする際にエラーが出るみたいなのでお気をつけて。

拡張ファイルのコンパイル→インストールまで

 ひととおりファイルのエディットが終わったら、あとは実際にインストール可能な拡張ファイル(.vsix)をコンパイルする。再度上掲の記事を参照してみよう。

$ npm install -g vsce
$ vsce package

このようにnpmでvsceパッケージをインストールしてコマンドを打てばプロジェクトディレクトリに*.vsixファイルが出来ます。これがVSCodeのエクステンションパッケージになります。

 ここでひっかかったらがんばる。とにかくがんばる。とにかく.vsixが出たら勝ち、みたいな気持ちで。無事出力されたらディレクトリを移動せずその場で以下のコマンドを入力。3

$ code --install-extension プロジェクト名.vsix

 で、拡張機能のインストールが成功した旨メッセージがでるはず。そしたら満を持してvscodeを起動しよう。自分のつくった拡張機能が登録されている様子はちょっと誇らしいぞ。まだ動かないけど。

 なんで最後に言うねん、という感じだろうけれど、設定ファイルに一行、"markdown.enableExperimentalExtensionApi": trueというのを追加してあげないと、markdown-it関連のプラグインを拡張するスクリプトは動かないようになっているそうだ。これは今後のアップデート次第でこの拡張が使えなくなる可能性もある、あくまで実験にすぎないということ。拡張を追加している、ではなく、拡張をさせていただいているという精神で行きましょう。

https://gyazo.com/f93d73fa69b65e7251dfe32a727800b5

 まだPreviewのCSSをきちんといじっていないのでわりと不本意な見た目ではあるのだけれど、とりあえず対応することはできました。よかった。このまましばらく問題なさそうだったらGithubリポジトリつくります。


  1. こんな感じで。

  2. その点MS Wordは馬鹿にできなくて、修論を書くときは「こんなに重くて使いにくいのになんて便利なんだ……!」と変な感動を覚えた。さすが世界がMSを中心に回ってるだけある。TeXも一時期使ってたけどあれはやはり組版ソフトであって、できた文書はさほど手をかけなくてもそこそこ美文書になってくれて悪くなかったのだが、どうしても.docファイルを編集させられることが多いこともあって修得は諦めた。

  3. 上掲の記事では.vsixファイルをそのままvscodeに読ませればインストールできると解説されていたが、少なくとも自分の環境ではファイル自体を開けず、インストールもできなかった。--install-extensionオプションは必須っぽい。(via VSCodeにオフラインでExtensionを追加する - Qiita

*1:こんな感じ。って書いてみて気付いたけど表示全然違うな。これはMarkdown式に脚注を統一しなければ…