VSCodeとDocker（devcontainer）で書くQiita執筆環境のボイラープレートです。このテンプレートを複製して、すぐに記事を書きはじめることができます。
- Qiitaの執筆に便利なVSCode拡張機能やスニペットが自動的にインストールされます。
- VSCodeの見た目はQiitaのテーマカラーに合わせています。
- Qiita Syncを使って、マークダウンで書いた記事をQiitaへ投稿（同期）できます。
- Qiita Markdown Previewを使ってローカル環境でプレビューを確認しながら記事を書くことができます。
- 記事の内容は
markdownlint,textlintでマークダウンの静的解析（lint）を行います。 - 英単語の誤字がないか
cspell（Code Spell Checker）でチェックをします。 huskyとlint-stagedでコミット時に自動でlintします。不正な形式の文章はコミットされません。
記事を編集するエディタはVSCode（Visual Studio Code）を使います。Qiitaの執筆に最適化されたVSCodeの拡張機能やスニペットが入ります。
また、Dockerで専用コンテナを準備して環境をつくります。そのため、ローカル環境にDockerのインストールが必要です。特にこだわりが無ければ、GUIで簡単にDockerコンテナを導入できるDocker Desktopが（個人利用であれば）無料で使えて便利です。
VSCodeからコンテナにアクセスして執筆するため、Dev ContainersのVSCode拡張機能も必要です。
利用にあたって、ローカル環境にVSCodeとDockerが準備されていることを前提としています。
まずは右上の "Use this template" をクリックして、このボイラープレートからリポジトリを複製します。
VSCodeで複製したリポジトリをクローンして "Reopen in Container" でコンテナを立ち上げます。
コンテナを立ち上げると docker/Dockerfile の内容に基づきコンテナ環境を構築します。package.json に書かれたライブラリがインストールされます。また devcontainer.json に書かれた設定によって、VSCode拡張機能がインストールされます。
ローカルのエディタでQiitaの記事が執筆できるようにQiita SyncのGithubアクションを設定しています。
Qiita SyncはQiita APIを活用した非公式の連携ツールです。Githubリポジトリにプッシュして同期アクションを実行すれば、連携したアカウントのQiita記事と同期されます。
詳しくはツール製作者の@ryokat3さんが書いている使い方の記事を確認してください。ご利用にあたって、連携対象のQiitaアカウントでQiita Access Tokenを発行し、記事を管理するGithubリポジトリへ登録する必要があります。
なお、このボイラープレートでは誤った操作で意図しない同期が起こる事故を防ぐためにプッシュ時の自動同期はコメントアウトしています。
name: Qiita Sync
on:
# push:
# branches:
# - main
workflow_dispatch:
# 以下略同期する際はブラウザ操作でGithubリポジトリのアクションから同期対象ブランチを選んで実行します。
またQiita Markdown Previewの拡張機能を入れています。VSCodeのプレビュー機能で、実際にQiitaに記事が表示される際の見た目で確認できます。この拡張機能もQiita Syncと同じ方が製作しています。
記事を書く際は、Qiitaに最適化されたVSCode拡張機能やスニペットを使うと便利です。また、コミット時に静的解析（lint）が実行されます。文章が不正な場合、警告メッセージが表示されてコミットできません。
詳しい設定について、後述していきます。
マークダウンの文章を書く効率を上げる目的で以下の拡張機能を入れています。
| 拡張機能 | 説明 |
|---|---|
| Markdown All in One | ショートカットや便利なコマンド |
| :emojisense: | 絵文字入力の補助 |
| Insert Date String | 現在時刻をショートカット入力 |
| Copy file name | ファイル名を右クリックメニューからコピー |
| Path Intellisense | パスを入力補完 |
拡張機能の使い方は以下の記事で動画付きで詳しく解説しています。よければ参考にしてください。
Markdown（マークダウン）をVSCodeの拡張機能とスニペットで効率良く書く
.vscode/markdown.code-snippets にQiita独自の記法を含むマークダウン記法のスニペットを登録しています。
Qiitaで使えるマークダウン記法はQiita公式が書いた以下の記事を参考にしてください。
このボイラープレートには、以下に対してlintする設定が入っています。
- マークダウンの形式（
markdownlint） - 文章の校正（
textlint） - 英単語の誤字（
cspell）
また、マークダウンファイル以外はコードフォーマット（自動整形）を prettier を使って実施します。マークダウンファイルはmarkdownlintと設定が競合するため、意図的に対象から外しています。
静的解析（lint）はVSCodeの拡張機能も入れているので、問題があればエディタ上で常に確認できます。
| 拡張機能 | 説明 |
|---|---|
| markdownlint | VSCodeのエディタ上でマークダウン構造を解析 |
| vscode-textlint | VSCodeのエディタ上でテキストを解析 |
| Code Spell Checker | VSCodeのエディタ上で英単語の誤字をチェック |
| Prettier - Code formatter | VSCodeでコードフォーマット（自動整形） |
husky と lint-staged でコミット時に自動でlintします。そのため、不正な形式の文章はコミットされません。
ボイラープレートなので、特に設定を変更せずそのまま使えます。使っていきながら、好みの設定に書き換えてください。
デフォルトの構文チェックは厳しめに設定されています。
そのため .vscode/settings.json と .markdownlint-cli2.jsonc で一部ルールを調整しています。
"markdownlint.config": {
"line-length": false, // MD013: Disable the maximum number of characters per sentence
"no-duplicate-heading": false, // MD024: Allow duplicate heading text
"no-trailing-punctuation": false, // MD026: Allow headings with . ,;:
"no-inline-html": false, // MD033: Allow HTML description
"no-bare-urls": false // MD034: Allow URLs to be written as is
}ベースとして以下の2つのプリセットを適用しています。
| プリセット名 | 説明 |
|---|---|
| textlint-rule-preset-ja-spacing | 日本語のスペース有無を決定するtextlintルールプリセット |
| textlint-rule-preset-ja-technical-writing | 技術文書向けのtextlintルールプリセット |
プリセットのままだと厳し過ぎる箇所があるため .textlintrc で設定を一部上書きしています。
{
"plugins": {
"@textlint/markdown": {
"extensions": [
".md"
]
}
},
"filters": {
"comments": true
},
"rules": {
"prh": {
"rulePaths": [
"./prh/index.yml"
]
},
"preset-ja-technical-writing": {
"sentence-length": {
"max": 150
},
"no-exclamation-question-mark": {
"allowFullWidthExclamation": true,
"allowFullWidthQuestion": true
},
"ja-no-successive-word": false,
"ja-no-mixed-period": {
"allowPeriodMarks": [
":",
"："
]
},
"no-doubled-joshi": {
"strict": false,
"allow": [
"も",
"や",
"か"
],
"separatorCharacters": [
",",
"，",
"、",
".",
"．",
"。",
"?",
"!",
"？",
"！",
"「",
"」",
"\"",
"”",
"“"
]
}
},
"preset-ja-spacing": {
"ja-space-around-code": {
"before": true,
"after": true
}
}
}
}また、校正用辞書を /prh/rules へ追加できるようにしています。初期設定では /prh/rules/tech.yml に技術用語の校正辞書をいくつか登録しています。必要に応じて用語を追加してください。
meta:
- title: 技術用語の固有名詞ルール
rules:
- expected: インターフェース
patterns:
- インターフェイス
- インタフェース
- インタフェイス
prh: 技術用語
- expected: ソフトウェア
pattern: ソフトウェアー
prh: 技術用語
- expected: ハードウェア
pattern: ハードウェアー
prh: 技術用語
- expected: デフォルト
pattern: ディフォルト
prh: 技術用語許可する言葉は .cspell.json の words に追加します。対象の文字列にカーソルを合わせてVSCodeのクイックフィックスで登録するのが便利です。
.prettierignore に *.md 記載して、マークダウンファイルをコードフォーマットの対象外にしています。その他の設定は特に入れていません。自動整形時はデフォルト設定が適用されます。