VSCode の Markdown を拡張する

Last updated at 2024-05-07Posted at 2024-05-07

VSCode の Markdown を拡張する

Markdown でドキュメントを作成しようとして、「他にもこういった記法があれば」と思ったことはありませんか。
VSCode で Markdown を作成する上での拡張機能の利用方法と、独自の記法を追加するための方法を記録に残します。

やりたいこと

スタイル（色やサイズ）を自由に設定したい
リストの連番に数字以外（ローマ数字など）を設定したい
見出しに連番を振り、目次を挿入したい
独自の記法を追加したい（ここでは埋め込み文字を設定できる記法を追加するものとします）

環境構築

（筆者の環境は Windows11 です）
VSCode をローカル端末にインストールした上で、下記の拡張機能をインストールします。

Japanese Language Pack for Visual Studio Code
Markdown All in One
Markdown Preview Enhanced

スタイルの設定

スタイルの設定により、下記2つを実現します。

スタイル（色やサイズ）を自由に設定したい
リストの連番に数字以外（ローマ数字など）を設定したい

基本テーマの設定
設定から「Markdown-preview-enhanced: Preview Theme」を検索して、「github-light.css」を選択します。

拡張スタイルの設定
「すべてのコマンドの表示」に「Markdown Preview Enhanced: Customize CSS (Global)」を入力して「style.css」を開きます。
「style.css」に下記のスタイルシートを入力して保存します。

style.css

@charset "UTF-8";

/* スタイル（色やサイズ）を設定します */
/* whole ======================================== */
.markdown-preview {
padding:2em 2em !important;
}

/* heading ======================================== */
h1 {
padding: 0.4em 0.5em;
background: #7db4e6;
box-shadow: 7px 7px 7px #808080;
border: none;
font-weight: bold !important;
color: #000000 !important;
}
h2 {
padding: 0.4em 0.5em;
background: #deedfa;
box-shadow: 5px 5px 5px #808080;
border: none;
font-weight: bold !important;
color: #000000 !important;
}
h3 {
padding: 0.4em 0.5em;
border-bottom: solid 5px #808080;
font-weight: bold !important;
color: #000000 !important;
}
h4 {
padding: 0.3em 0.5em;
border-bottom: solid 3px #808080;
font-size: 1.4em !important;
font-weight: bold !important;
color: #000000 !important;
}
h5 {
padding: 0.2em 0.5em;
border-bottom: solid 2px #808080;
font-size: 1.3em !important;
font-weight: bold !important;
color: #000000 !important;
}
h6 {
padding: 0.2em 0.5em;
border-bottom: dashed 2px #808080;
font-size: 1.2em !important;
font-weight: bold !important;
color: #000000 !important;
}

/* table ======================================== */
table {
border-collapse: collapse;
}
th {
background-color: #deedfa;
border: solid 2px;
border-color: #808080;
}
td {
border: solid 2px;
border-color: #808080;
}

/* リストの連番に数字以外（ローマ数字など）を設定します */
@counter-style harf-katakana {
system: fixed;
symbols: ｱ ｲ ｳ ｴ ｵ ｶ ｷ ｸ ｹ ｺ ｻ ｼ ｽ ｾ ｿ ﾀ ﾁ ﾂ ﾃ ﾄ ﾅ ﾆ ﾇ ﾈ ﾉ ﾊ ﾋ ﾌ ﾍ ﾎ ﾏ ﾐ ﾑ ﾒ ﾓ ﾔ ﾕ ﾖ ﾗ ﾘ ﾙ ﾚ ﾛ ﾜ ｦ ﾝ;
suffix: ". ";
}
ol ol, ul ul, ul ol, ol ul {
padding-left: 20px !important;
}
ol > li {
list-style-type: decimal;
}
ol li ol > li {
list-style-type: lower-roman;
}
ol li ol li ol > li {
list-style-type: upper-alpha;
}
ol li ol li ol li ol > li {
list-style-type: harf-katakana;
}
ol li ol li ol li ol li ol > li {
list-style-type: upper-roman;
}
ol li ol li ol li ol li ol li ol > li {
list-style-type: lower-alpha;
}
ul > li {
list-style-type: disc;
}
ul li ul > li {
list-style-type: circle;
}
ul li ul li ul > li {
list-style-type: square;
}
ul li ul li ul li ul > li {
list-style-type: disc;
}
ul li ul li ul li ul li ul > li {
list-style-type: circle;
}
ul li ul li ul li ul li ul li ul > li {
list-style-type: square;
}

独自の記法を追加する

パーサー拡張機能の追加により、下記を実現します。

独自の記法を追加したい
??{置換対象のキーワード}={置換後の文字列}を Markdown ファイルに記述すると、プレビュー時に置換するという独自の記法を作ってみました。

パーサー拡張機能の設定
「すべてのコマンドの表示」に「Markdown Preview Enhanced: Extend Parser (Global)」を入力して「parser.js」を開きます。
「parser.js」に下記のプログラム（JavaScript）を入力して保存します。

parser.js

({
  onWillParseMarkdown: async function (markdown) {
    // #### HTML に変換する前に独自の加工したい場合はここにプログラムを書きます

    // ファイルの改行コードを検出します
    let lfCode = '';
    if (markdown.indexOf('\r\n') > -1) {
      lfCode = '\r\n';
    } else if (markdown.indexOf('\n') > -1) {
      lfCode = '\n';
    } else if (markdown.indexOf('\r') > -1) {
      lfCode = '\r';
    }

    // 「??」を埋め込み文字のキーワードとします
    const REP_REG = new RegExp('^\\?\\?[\\s\\S]*?' + lfCode, 'gim');
    let repMatches = markdown.match(REP_REG);
    if (repMatches) {
      for (let matche of repMatches) {
        if (matche.indexOf('=') > -1) {
          matche = matche.replaceAll(lfCode, '');
          let spRepKey = matche.split('=');
          markdown = markdown.replaceAll(spRepKey[0].substring(2), spRepKey[1]);
        }
      }
      // 埋め込み文字のキーワード行を削除します
      markdown = markdown.replaceAll(REP_REG, '');
    }
    return markdown;
  },

  onDidParseMarkdown: async function (html) {
    // #### HTML に変換した後に独自の加工したい場合はここにプログラムを書きます
    return html;
  },

  onWillTransformMarkdown: async function (markdown) {
    return markdown;
  },

  onDidTransformMarkdown: async function (markdown) {
    return markdown;
  },

  processWikiLink: function ({ text, link }) {
    return {
      text,
      link: link ? link : text.endsWith('.md') ? text : `${text}.md`,
    };
  }
})

Markdown ドキュメントの作成

Markdown ファイルを作成
Markdown 記法のファイルを作成します。

sample.md

??REPLACE_DATE=2024年5月6日

# Markdown ドキュメント <!-- omit in toc -->

# H1のサンプル

## H2のサンプル

### H3のサンプル

#### H4サンプル

##### H5サンプル

###### H6サンプル

###### 番号つき箇条下記の例
1. 1階層目（数値）
   1. 2階層目（ローマ数字（小文字））
      1. 3階層目（アルファベット（大文字））
         1. 4階層目（半角カナ）
            1. 5階層目（ローマ数字（大文字））
               1. 6階層目（アルファベット（小文字））

###### 番号なし箇条下記の例
- 1階層目
  - 2階層目
    - 3階層目
      - 4階層目
        - 5階層目
          - 6階層目

###### 埋め込み文字の例
本日は［REPLACE_DATE］です。

見出しに連番を振る
「すべてのコマンドの表示」に「Markdown All in One: Add/Update section numbers」を入力して実行します。

除外設定「」以外の見出しに連番が振られました。
目次を挿入する
目次を挿入したい行にカーソルを置いて、「すべてのコマンドの表示」に「Markdown All in One: Create Table of Contents」を入力して実行します。

目次が作成されました。
Markdown Preview で表示
右上の「Markdown Preview Enhanced: Open Preview to the Side」ボタンをクリックします。

プレビューが表示されました。

設定したスタイル（色やサイズ）が適用されていること、リストの連番に数字以外（ローマ数字など）が設定されていること、追加した独自の記法が適用されていることを確認します。

最後に

他にも、Mermaid 記法でグラフやシーケンス図を挿入したりすることが一般的なようです。
それらとパーサー拡張機能を駆使して、ドキュメント作成の効率化に挑戦していこうと思います。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up