VS Code拡張機能「Markdown Digit 」のバージョン1.1.0を開発しました。
これまでのMarkdown Digitは、次のように数字ごとにlocaleを明示する使い方が中心でした。
$123456789${jp}
この記法なら変換対象が明確ですが、売上報告や統計資料のように大きな数字が何度も登場する文書では、毎回localeを書く必要があります。
バージョン1.1.0では、VS Code設定またはMarkdown先頭のYAML Front Matterから文書設定を読み取り、通常の文章に書かれた数字を文書全体で自動変換できるようにしました。
今回追加した機能
主な変更は次のとおりです。
markdown-it-digitを1.1.0へ更新- VS Code設定として
markdownDigit.localeとmarkdownDigit.minDigitsを追加 - YAML Front Matterの
markdown.digitを文書単位の設定として利用 - 明示記法、YAML、VS Code設定の優先順位を定義
$123456789${raw}による個別の自動変換除外- 拡張機能情報と設定画面の多言語化
- 英語、日本語、簡体字中国語、韓国語、繁体字中国語のREADMEと参考画像を用意
markdown-it-digit 1.1.0の開発ログは、以下の記事で詳しく紹介しています。
1. VS Code設定で既定値を指定する
普段使う形式はVS Code設定で指定できます。
{
"markdownDigit.locale": "jp",
"markdownDigit.minDigits": 4
}localeにはen、in、jp、cn、kr、twを指定できます。minDigitsは自動変換を始める最小桁数で、既定値は4です。
自動変換は初期状態では無効です。拡張機能を更新しただけで既存のMarkdown表示が変わらないよう、localeの既定値は空にしました。
2. YAML Front Matterで文書ごとに上書きする
特定の文書だけ設定を変える場合は、文書先頭に次のFront Matterを書きます。
---
markdown:
digit:
locale: jp
minDigits: 4
---この設定がある文書では、次のような通常の数字が、
売上は123456789円でした。プレビュー上で日本語の単位を使った表記になります。
売上は1<sub>億</sub>2345<sub>万</sub>6789円でした。YAMLが壊れている場合はMarkdownプレビュー全体を失敗させず、VS Code設定へフォールバックします。Front Matterが文書先頭にない場合や、markdown.digitが存在しない場合も同様です。
設計上のポイント
1. YAMLを理解する責務は拡張機能側に置いた
設計上のポイントは、markdown-it-digit自体にはYAMLを解析させなかったことです。
Markdown文書
↓
vscode-markdown-digit
├─ VS Code設定を取得
├─ js-yamlでFront Matterを解析
└─ env.markdownDigitへ設定
↓
markdown-it-digit
└─ 通常の数字をlocaleに従って変換拡張機能側では、レンダリングごとにVS Code設定を読み取り、Front Matterの内容と統合してenv.markdownDigitへ格納します。
markdown-it-digitは、その設定がVS Code由来なのかYAML由来なのかを知りません。最終的なlocaleとminDigitsだけを受け取るため、ライブラリ単体でも別の利用環境でも同じAPIを使えます。
2. markdown-itのルール実行順を利用する
文書設定は、markdown-it-digitの自動変換処理より前に設定する必要があります。
そこで、まずmarkdown-it-digitを登録し、その後でautomatic_digitより前に文書設定用のコアルールを差し込みました。
markdownIt.use(markdownItDigit);
markdownIt.core.ruler.before(
'automatic_digit',
'markdown_digit_document_settings',
createDocumentSettingsRule(getWorkspaceSettings),
);これにより、Markdownのインライン解析が終わったあと、自動変換が始まる直前に文書ごとの設定を確定できます。
3. 優先順位はプロパティ単位で解決する
設定の優先順位は次のようにしました。
本文の明示記法
> YAML Front Matter
> VS Code設定
> 設定なしYAMLにlocaleだけがあれば、minDigitsはVS Code設定を引き継ぎます。設定オブジェクト全体ではなく、プロパティ単位で上書きする設計です。
また、文書全体の自動変換が有効でも、次のような明示記法はその数字だけ別の形式にできます。
$123456789${en}変換したくない管理番号などにはrawを使います。
$123456789${raw}これはマーカーを取り除き、元の数字をそのまま表示します。
4. コードやURLはこれまでどおり変換しない
文書全体を対象にするからといって、すべての数字を機械的に置換するとMarkdownを壊します。
そのため、次の内容は従来どおり変換対象外です。
- フェンスコードブロックとインデントコードブロック
- インラインコード
- URLとMarkdownリンクのリンク先
- HTML属性とHTMLコメント
- バックスラッシュでエスケープされた記法
本番を想定した売上報告とアクセス分析のMarkdown文書も作り、Extension Development Host上でYAML経路とVS Code設定経路の両方を手動確認しました。
5. 設定画面とREADMEを多言語化した
VS Codeのpackage.nls.jsonを利用し、英語を既定として次の表示言語へ対応しました。
- 日本語
- 簡体字中国語
- 韓国語
- 繁体字中国語
READMEも同じ5言語を用意し、それぞれMarkdownソースとプレビュー結果を並べた参考画像を掲載しました。
その他
相対画像URLの警告
READMEへ相対パスの画像を追加したところ、Marketplace用の確認で、相対画像URLにはHTTPSのリポジトリ指定が必要だという警告が出ました。
package.jsonのリポジトリURLは、従来次の形式でした。
"url": "git+https://github.com/yusu79/vscode-markdown-digit.git"typeですでにGitリポジトリと分かるため、URLを通常のHTTPS形式へ変更しました。
"url": "https://github.com/yusu79/vscode-markdown-digit.git"変更後にvsce lsを実行し、相対画像URLの警告が消え、5言語のREADMEと5枚の画像がVSIXへ含まれることを確認しました。
npm auditで表示された4件を確認する
依存関係の更新後、npmからlow 2件、moderate 1件、high 1件の脆弱性が報告されました。
経路を調べると、すべてテスト用の依存関係でした。
@vscode/test-cli
└─ mocha
├─ diff
└─ serialize-javascript本番依存だけを対象にしたnpm audit --omit=devでは0件でした。今回追加したmarkdown-it-digitとjs-yamlが原因ではありません。
npm audit fix --forceはテストCLIのダウングレードを伴うため、機械的には適用しませんでした。本番への影響と修正による互換性リスクを分けて判断することが大切です。
テスト
VS CodeのExtension Hostを使う統合テストは、従来の4件から11件へ増やしました。
確認した主な内容は次のとおりです。
- 設定がない場合の後方互換性
- VS Code設定による自動変換
- YAML Front Matterによる文書全体の変換
- YAMLとVS Code設定のプロパティ単位の優先順位
- 不正なYAMLからのフォールバック
- 明示localeと
rawの優先 - コード、URLなどの除外対象
最終確認では、Lint、統合テスト11件、JSON整合性、NLSキーの一致、VSIX収録対象、Git差分の形式を確認しました。
まとめ
Markdown Digit 1.1.0では、数字ごとの明示記法を残しながら、VS Code設定とYAML Front Matterによる文書全体の自動変換を追加しました。
普段はVS Code設定を既定値として使い、特定の文書だけYAMLで上書きし、さらに個別の数字だけ明示localeやrawで調整できます。
責務を拡張機能とmarkdown-it-digitに分離したことで、YAMLに依存しないライブラリAPIを維持しながら、VS Codeでは文書単位の使いやすい設定を提供できました。
ローカルではmainとdevelopをリリースコミットへ揃え、署名付きv1.1.0タグを作成しています。pushとMarketplaceへの公開は、別途確認してから行います。