This is a template for a repository that manages documents in Markdown. It includes a feature to convert Markdown to PDF.
md2pdf-doc-template は、ドキュメントを Markdown 形式で管理するためのリポジトリテンプレートです。 Markdown ファイルを PDF 形式に変換する機能を含んでいます。
ドキュメントを Markdown 形式で管理することで、 Git などの構成管理システムで、ファイルの差分を管理することが容易になります。 またプルリクエストを利用することで、レビューを効率的に行えます。
このリポジトリテンプレートには、ドキュメントの体裁を保つための設定が施されています。 プルリクエストと同時に、体裁の確認が可能です。 またローカル開発環境でも、同様の確認ができます。 既定では、日本語のドキュメントを作成するのに特化した設定が行われています。
このリポジトリテンプレートの利用には、以下のソフトウェアを事前にインストールする必要があります。
- Visual Studio Code
- Node.js (npm 含む)
Note
既定では、 Windows 環境で動作するように設定されています。 Windows 以外の環境をご利用の場合は、 /docs/base-style.css と /md-to-pdf-config.js のフォント設定を調整してください。
GitHub 上で、このリポジトリをテンプレートとしたご自身のリポジトリを作成します。 md2pdf-doc-template リポジトリのトップにある [Use this template] > [Create a new repository] から作成できます。
リポジトリを作成したら、ローカルマシンにクローンしてください。
リポジトリのルートディレクトリで、以下のコマンドを実行してください。
npm ci
続いて、 Visual Studio Code の拡張機能をインストールします。 /.vscode/extensions.json に設定されている各種拡張機能をインストールしてください。
リポジトリのルートディレクトリで以下のコマンドを実行してください。
npm run lint
リポジトリのルートディレクトリで以下のコマンドを実行してください。
npm run build
初期状態だと、 /docs/_document-template/contents.md を PDF 化して /output/ドキュメントテンプレート.pdf が生成されます。
Note
出力した PDF のサンプルは PDF のサンプル をご覧ください。
/docs/_document-template フォルダーをコピーして、 /docs フォルダー配下にリネームして配置してください。 フォルダー名は、作成するドキュメントの英語名としてください。 以降、リネーム後のフォルダー名を new-doc として記載します。
ドキュメントの PDF 化には npm パッケージの md-to-pdf を利用します。
package.json の scripts に PDF 化のための以下のスクリプトを追加してください。
{
"scripts": {
"build:<ドキュメントの英語名>": "npx md-to-pdf --config-file ./md-to-pdf-config.json ./docs/<ドキュメントの英語名>/contents.md",
}
}ドキュメントの英語名が new-doc の場合、以下のようなスクリプトを追加します。
{
"scripts": {
"build:new-doc": "npx md-to-pdf --config-file ./md-to-pdf-config.json ./docs/new-doc/contents.md",
}
}これにより、 new-doc を PDF 化する npm run build:new-doc コマンドが使えるようになります。
また npm run build 実行時に、 new-doc も PDF 化されるようになります。
Note
各ドキュメントのディレクトリ構造を変更する場合は、 md-to-pdf に渡す Markdown ファイルのパス階層を調整してください。
/docs/new-doc/contents.md を編集してドキュメントを執筆します。 Markdown の方言は、おおよそ GitHub Flavored Markdown (GFM) 形式に従います。 基本的な構文例は ドキュメントテンプレート を参照してください。
ドキュメントの単位で GitHub Actions のワークフローファイルを作成します。 /.github/workflows/ci-document-template-build.yml をコピーして、 /.github/workflows フォルダー配下にリネームして配置してください。 ファイル名は「ci-<ドキュメントの英語名>-build.yml」としてください。 この例では「ci-new-doc-build.yml」とします。
コピーしたワークフローを以下のように修正します。
# ドキュメント名を設定します。
name: <ドキュメント名>のビルド
on:
pull_request:
branches: [main]
paths:
# ドキュメントの英語名を以下 2 行に設定します。
- ".github/workflows/ci-<ドキュメントの英語名>-build.yml"
- "docs/<ドキュメントの英語名>/**"
- "docs/_shared-images/**"
- "docs/base-style.css"
- "package-lock.json"
- "package.json"
workflow_dispatch:
jobs:
build:
name: ドキュメントのビルド
runs-on: windows-latest
steps:
- name: ブランチのチェックアウト
uses: actions/checkout@v4
with:
fetch-depth: 1
lfs: true
- id: build-document
name: ドキュメントのビルドとアップロード（PR時は除く）
uses: ./.github/workflows/build-document
with:
# ドキュメント名を設定します。
build-script-name: "build:<ドキュメントの英語名>"PDF 化する際のページ設定は、 /md-to-pdf-config.js にあります。 ページサイズ、ページ内の余白、ヘッダー・フッターのテンプレートとスタイル設定などの項目があります。 詳細は md-to-pdf の README をご覧ください。
ページ内の細かなスタイル設定は、 /docs/base-style.css で調整します。
base-style.css には、すべてのドキュメントに対して適用する CSS クラスが定義されています。
スタイルを調整したい場合は、 md-to-pdf を --devtools オプション付きで実行し、 PDF に変換する前の HTML を確認してください。
これらのファイルは、リポジトリ内で管理するすべてのドキュメントに対して影響を与えます。
markdownlint は、 Markdown の構文を統一するための検証ツールです。 markdownlint の設定ファイルは以下の 2 つです。
- .markdownlint-cli2.jsonc
- .markdownlint.yaml
.markdownlint-cli2.jsonc には、検証対象のファイルが設定されています。 詳細は GitHub | markdownlint-cli2 をご覧ください。
.markdownlint.yaml には、 markdownlint の検証設定があります。 詳細は GitHub | markdownlint をご覧ください。
textlint は、冗長な文章の検出や、単語レベルでの表記揺れ検出など、日本語の体裁を自動的に検証するツールです。 あらかじめ、いくつかのプラグインが有効になっています。 textlint の設定ファイルは以下の 1 つです。
- .textlintrc
.textlintrc には、 textlint の検証設定があります。 詳細は GitHub | textlint をご覧ください。
CSpell は、主に英単語のスペルミスを検出するツールです。 CSpell の設定ファイルは以下の 1 つです。
- cspell.json
cspell.json には、検証対象のファイルが設定されています。 詳細は GitHub | CSpell をご覧ください。