docs-gen v0.6.0

ページを書く

ページを書く

コンテンツはすべて pages/<lang>/ の下に Markdown ファイルとして配置します。

対応する Markdown 記法

docs-gen は標準の CommonMark に加えて、以下の拡張をサポートしています:

  • テーブル — パイプ区切りのテーブル（列の揃え指定可）
  • 取り消し線 — ~~削除されたテキスト~~
  • タスクリスト — - [ ] 未完了 と - [x] 完了

見出しにはアンカーリンク用の id 属性が自動で付与され、コードブロックはテーマに応じたシンタックスハイライトが適用されます。

フロントマター

.md ファイルの先頭には必ず YAML フロントマターを書きます:

---
title: "ページタイトル"
order: 1
---

---
title: "ページタイトル"
order: 1
---
フィールド必須説明
titleはいページタイトル（サイドバーとブラウザタブに表示）
orderいいえセクション内の並び順（デフォルト: 0）
statusいいえ"draft" にすると DRAFT バナーが表示される

セクションとナビゲーション

言語ディレクトリ配下のサブディレクトリがセクションになり、サイドバーナビゲーションを持ちます:

pages/en/
├── index.md              # ホームページ（サイドバーなし）
└── guide/
    ├── index.md          # セクション見出し
    ├── 01-intro.md       # order → ファイル名の順にソート
    └── 02-deploy.md

pages/en/
├── index.md              # ホームページ（サイドバーなし）
└── guide/
    ├── index.md          # セクション見出し
    ├── 01-intro.md       # order → ファイル名の順にソート
    └── 02-deploy.md
  • セクションの index.md の title がサイドバーの見出しになります。
  • セクション内の他のページはその下に一覧表示されます。
  • ルートの index.md はポータルレイアウト（サイドバーなし）で表示されます。

新しいページを追加する

  1. .md ファイルを作ります（例: pages/en/guide/03-tips.md）。
  2. フロントマターに title と order を書きます。
  3. サイドバーに自動的に表示されます。

ページ間の相対リンク

各ページはクリーンURLのために独自のディレクトリにレンダリングされます（例: 01-getting-started.md → 01-getting-started/index.html）。相対リンクの書き方に影響するので注意してください。

リンク元リンク先書き方
ページ（例: 01-intro.md）同階層のページ../02-deploy/（一階層上がってから指定）
セクションの index.md子ページ01-intro/（直接指定）

例 — 同階層リンク:

次へ: [ページを書く](../02-writing-pages/)

次へ: [ページを書く](../02-writing-pages/)

例 — index から子ページ:

[はじめよう](01-getting-started/)

[はじめよう](01-getting-started/)

画像とファイル（コロケーション）

画像などのファイルをMarkdownページと同じディレクトリに置くと、ビルド時に自動的に正しい場所にコピーされます。

pages/ja/guide/
├── index.md
├── 01-intro.md
├── diagram.png        ← このセクションに配置
└── screenshot.jpg

pages/ja/guide/
├── index.md
├── 01-intro.md
├── diagram.png        ← このセクションに配置
└── screenshot.jpg

セクションの index.md から参照する場合:

![Diagram](./diagram.png)

![Diagram](./diagram.png)

通常のページ（例: 01-intro.md）から参照する場合:

各ページは独自のディレクトリにレンダリングされるため（01-intro/index.html）、../ で一階層上がります:

![Screenshot](../screenshot.jpg)

![Screenshot](../screenshot.jpg)

static/ ディレクトリ

プロジェクトルートの static/ ディレクトリは、サイト全体で共有するファイル（favicon、ロゴなど）を置く場所です。static/ 内のファイルはそのまま出力ルートにコピーされます。

my-docs/
├── static/
│   ├── favicon.svg       → /favicon.svg
│   └── logo.png          → /logo.png
└── pages/

my-docs/
├── static/
│   ├── favicon.svg       → /favicon.svg
│   └── logo.png          → /logo.png
└── pages/

サイト全体で使うファイルには static/ を、特定のページやセクションに属するファイルにはコロケーション（上記）を使います。

画像のサイズ指定

画像はデフォルトでコンテンツ幅に収まります（max-width: 100%）。表示サイズを変えたいときは、画像URLに #fragment を付けます:

![Screenshot](./screenshot.png#small)
![Screenshot](./screenshot.png#half)
![Screenshot](./screenshot.png#large)

![Screenshot](./screenshot.png#small)
![Screenshot](./screenshot.png#half)
![Screenshot](./screenshot.png#large)
Fragment最大幅
(なし)100%
#small300px
#half50%
#large80%

画像を中央揃えにするには、fragmentに -center を付けます:

![Screenshot](./screenshot.png#half-center)

![Screenshot](./screenshot.png#half-center)

#center だけでもフル幅の中央揃えになります。

多言語での画像共有

多言語サイトでは、デフォルト言語（langs の最初のエントリ）のディレクトリにある画像が他の言語でも自動的に使えます。言語固有の画像（ローカライズされたスクリーンショットなど）がある場合だけ、その言語のディレクトリに置いてください。

pages/
├── en/
│   └── guide/
│       ├── index.md
│       └── screenshot.png   ← 全言語で共有される
└── ja/
    └── guide/
        └── index.md         ← コピーなしで screenshot.png を参照できる

pages/
├── en/
│   └── guide/
│       ├── index.md
│       └── screenshot.png   ← 全言語で共有される
└── ja/
    └── guide/
        └── index.md         ← コピーなしで screenshot.png を参照できる

同名のファイルがその言語のディレクトリにあれば、そちらが優先されます。

次へ: 設定

ESC