はじめに

社内共有用やブログ用のドキュメントをローカルで書き、git で管理しています。今のところ快適な体験になっているので、各種設定を晒してみたいと思います。なおエディタは Visual Studio Code です。

ドキュメントを書くために入れている VSCode 拡張

基本的にマークダウンのための Linter/Formatter や補助機能、見た目上の拡張が多いです。ローカルで書く理由として、git の管理下に置きたいのはもちろんですが markdown-lint や textlint の恩恵を受けたいというのも大きいです。

拡張機能 説明
yzhang.markdown-all-in-one いろいろできる
bierner.markdown-checkbox プレビューでチェックボックスを表示する
bierner.markdown-mermaid マーメイド記法で書かれた図を表示する
bierner.markdown-preview-github-styles マークダウンのプレビューを GitHub 風にする
DavidAnson.vscode-markdownlint マークダウンの Linter
taichi.vscode-textlint nodejs 製文書校正ツール textlint の VSCode 拡張
k–kato.vscode-backlog-wiki-previews Backlog 記法をシンタックスハイライトする

VSCode 設定抜粋

以下のような設定を入れています。

{
  "markdown.preview.fontSize": 12,
  "markdown.preview.lineHeight": 1.4,
  "markdown.preview.breaks": true,
  "markdown.extension.orderedList.marker": "one",
  "markdown.extension.orderedList.autoRenumber": false,
  "markdownlint.run": "onType",
  "markdownlint.config": {
    "MD010": false, // タブでのインデントを許可する
    "MD024": false, // 複数の見出しで同じ文言を書くことを許可する
    "MD033": false, // HTML を使用することを許可する
    "MD041": false  // 最初の見出しがトップレベル (h1) でなくても許可する
  },
  "textlint.autoFixOnSave": true,
  "textlint.configPath": "~/.textlintrc.json",
  "textlint.run": "onType",
  "backlog.preview.fontSize": 12,
  "backlog.preview.lineHeight": 1.4,
  "[markdown]": {
    "editor.defaultFormatter": "yzhang.markdown-all-in-one",
    "editor.wordWrap": "off",
    "editor.fontFamily": "'PlemolJP Console NF', Menlo, Monaco, 'Courier New', monospace",
    "files.trimTrailingWhitespace": false
  },
  "[backlog]": {
    "editor.quickSuggestions": {
      "other": "on",
      "comments": "off",
      "strings": "off"
    }
  },
}

テーブル整形

Markdown All in One には Table Formatter が付属しています。保存時にテーブルが自動整形される体験はいちど味わうとやめられなくなります。ただし日本語 (というか East Asian Ambiguous Width な文字) を含む場合は、テーブルレイアウトが崩れます。

この問題が気に入らない場合、文字幅比率「半角 1 : 全角 2」の等幅フォントを設定すればよいです。私は通常のフォントは Monaspace Neon を使い、マークダウンの時は PlemolJP Console NF を使っています。

"[markdown]": {
  "editor.defaultFormatter": "yzhang.markdown-all-in-one",
  "editor.wordWrap": "off",
  "editor.fontFamily": "'PlemolJP Console NF', Menlo, Monaco, 'Courier New', monospace", // これ
  "files.trimTrailingWhitespace": false
},

なお、この設定の場合テーブル以外は保存時に整形されません。markdown-lint で出た警告を fix-all すれば整形されるので、そこは割り切っています。

Formatter は remark も試しましたが、テーブル整形でマルチバイト文字のサポートがなかったので採用しませんでした。

文書校正

もっとも重宝しているのが文書校正ツールの textlint です。node.js でインストールする必要があります。特定のフォルダにドキュメントがまとまっているわけではないので、以下のようにグローバルインストールしています。

$ npm ls -g
:
├── textlint-rule-preset-ja-spacing@2.3.0
├── textlint-rule-preset-ja-technical-writing@10.0.1
└── textlint@14.0.3

以下 2 つのルールを入れています。最小限だと思います。

  • textlint-rule-preset-ja-spacing: 日本語のスペース周りのスタイルに関するルール
  • textlint-rule-preset-ja-technical-writing: 日本語の技術文書向けルール

textlint の設定はホーム下に .textlintrc.json を置いて管理します。

{
  "rules": {
    "preset-ja-spacing": {
      "ja-space-between-half-and-full-width": {
        "space": ["alphabets", "numbers"],
      },
      "ja-no-space-between-full-width": true,
      "ja-nakaguro-or-halfwidth-space-between-katakana": true,
      "ja-no-space-around-parentheses": false,
      "ja-space-after-exclamation": true,
      "ja-space-after-question": true,
      "ja-space-around-code": {
        "before": true,
        "after": true
      }
    }
  }
}

好みの問題ですが、スペースに関しては細かく設定しています。私は半角文字と全角文字の間に半角スペースを入れる派閥です。

  • 半角文字と全角文字の間にスペースを入れる
  • 全角文字どうしの間にスペースを入れない
  • カタカナ語間は中黒または半角スペースを用いてカタカナ語を区切る
  • 文末に感嘆符、疑問符を使用し、後に別の文が続く場合は、直後に全角スペースを挿入
  • インラインコードの周りをスペースで囲む

マークダウン用の VSCode スニペット

VSCode に以下のようなスニペットを登録し、少ない手数でドキュメントを書く工夫をしています。

{
  "Markdown code line": {
    "prefix": "mline",
    "body": [" `$1` "]
  },
  "Markdown code block": {
    "prefix": "mcode",
    "body": ["```$1", "", "```"]
  },
  "Markdown quote block": {
    "prefix": "mqt",
    "body": ["> $1"]
  },
  "Markdown table block": {
    "prefix": "mt",
    "body": ["|col1|col2|col3|", "|--|--|--|", "||||", "||||"]
  },
  "Markdown h1": {
    "prefix": "mh1",
    "body": ["# $1"]
  },
  "Markdown h2": {
    "prefix": "mh2",
    "body": ["## $1"]
  },
  "Markdown h3": {
    "prefix": "mh3",
    "body": ["### $1"]
  },
  "Markdown h4": {
    "prefix": "mh4",
    "body": ["#### $1"]
  },
  "Markdown checkbox": {
    "prefix": "mcb",
    "body": ["- [ ] $1"]
  },
  "Markdown evidence 1": {
    "prefix": "mev1",
    "body": ["## エビデンス", "```", "$1", "```"]
  },
  "Markdown evidence 2": {
    "prefix": "mev2",
    "body": ["## 作業前", "```", "$1", "```", "## 作業後", "```", "", "```"]
  },
  "Markdown evidence 3": {
    "prefix": "mev3",
    "body": [
      "## $1",
      "### 作業前",
      "```",
      "",
      "```",
      "### 作業後",
      "```",
      "",
      "```"
    ]
  }
}

Backlog 用の VSCode スニペット

Backlog 記法を書く機会がある場合は、そちらも作っておくと便利です。

{
  "Backlog code line": {
    "prefix": "bline",
    "body": [" {code}$1{/code} "]
  },
  "Backlog code block": {
    "prefix": "bcode",
    "body": ["{code}", "$1", "{/code}"]
  },
  "Backlog quote block": {
    "prefix": "bqt",
    "body": ["{quote}", "$1", "{/quote}"]
  },
  "Backlog table block top-header": {
    "prefix": "bt1",
    "body": ["|col1|col2|col3|h", "||||", "||||"]
  },
  "Backlog table block left-header": {
    "prefix": "bt2",
    "body": ["| ~row1 |||", "| ~row2 |||", "| ~row3 |||"]
  },
  "Backlog h1": {
    "prefix": "bh1",
    "body": ["* $1"]
  },
  "Backlog h2": {
    "prefix": "bh2",
    "body": ["** $1"]
  },
  "Backlog h3": {
    "prefix": "bh3",
    "body": ["*** $1"]
  },
  "Backlog h4": {
    "prefix": "bh4",
    "body": ["**** $1"]
  },
  "Backlog checkbox": {
    "prefix": "bcb",
    "body": ["- [ ] $1"]
  },
  "Backlog evidence 1": {
    "prefix": "bev1",
    "body": ["** エビデンス", "{code}", "$1", "{/code}"]
  },
  "Backlog evidence 2": {
    "prefix": "bev2",
    "body": [
      "** 作業前",
      "{code}",
      "$1",
      "{/code}",
      "** 作業前",
      "{code}",
      "",
      "{/code}"
    ]
  },
  "Backlog evidence 3": {
    "prefix": "bev3",
    "body": [
      "** $1",
      "*** 作業前",
      "{code}",
      "",
      "{/code}",
      "*** 作業前",
      "{code}",
      "",
      "{/code}"
    ]
  }
}

おわりに

ドキュメントに限ったことではないですが、設定を再現可能にしておくのは大事です。私の場合は dotfiles 化しています。端末交換後にコマンド一発で環境が再現する状態が目指すところです。

運用手順書などを書く機会が多い場合、ドキュメントにかける工数は肥大化しがちです。それでも体験をよくする工夫はできます。環境整備を楽しみましょう。