執筆ガイド¶

このページでは、ドキュメントを作成・編集する際のガイドラインを説明します。

本サイトは Zensical というPythonパッケージを利用して構築されています。
いわゆる静的サイトジェネレーターと呼ばれるもので、markdown を記述することで静的サイトを作成することができます。
Python製のパッケージでは MkDocs がメジャーでしたが、Zensical は MkDocs の作者が開発した後継パッケージとされています。

2025年11月にリリースされたばかりで、現在は alpha 版です。

基本ルール¶

ページの作成方法¶

新しいドキュメントページを作成する際は、以下の手順を実施してください。

1. docs/ ディレクトリ配下に Markdown ファイルを作成

   # md ファイルを作成
   touch docs/new-feature-guide.md
   

   Note

   サブディレクトリのルールは特に設けていませんが、ページが増えてきたら検討します (2025/11/20)

2. フロントマターでメタ情報を設定

   各ページの先頭には、YAML形式のフロントマターでアイコンやタグなどのメタ情報を指定します。

   ---
   icon: lucide/lightbulb
   tags:
     - Google Cloud
     - Cloud SQL
     - データベース
   ---
   
   # ページタイトル
   
   ここから本文が始まります。
   

   Icon（アイコン）

   • ページのナビゲーションに表示されるアイコンを指定します
   • Lucide Icons から選択できます
   • 形式：lucide/アイコン名（例：lucide/lightbulb, lucide/cable, lucide/cloud-cog）

   Tags（タグ）

   • ドキュメントにタグを付けることで、関連するドキュメントをグループ化できます
   • タグは 最大5個まで とします
   • 推奨カテゴリ：
     • 技術カテゴリ（例：Google Cloud, AWS, Azure）
     • プロダクト名（例：Cloud SQL, Cloud Run, BigQuery）
     • トピック（例：データベース, ネットワーク, セキュリティ）

3. mkdocs.yml の nav セクションに追加

   Markdown ファイルを作成しただけでは、サイトのナビゲーションに表示されません。

   nav:
       - Home: index.md
       - Guides:
           - writing-guide.md
           - contribution-guide.md
           - new-feature-guide.md  # 新しく追加
   

見出しの使い方¶

• 見出し1（#）はページにつき1つ ページタイトルとして使用します
• 見出し2（##）：大セクション
• 見出し3（###）：中セクション
• 見出し4（####）：小セクション

画像ファイルの取り扱い¶

ファイル名は、内容を示すような命名が好ましいですが、悩んだ場合は、以下の命名規則に従ってください。

命名規則: {page-name}-{number}.{ext}

• ページ名（画像が参照されるファイル名から .mdを除いたもの）をプレフィックスとする
• 連番は2桁のゼロ埋め（01, 02, ...）
• ページ名と連番はハイフン（-）で区切る

記法¶

基本的なMarkdown記法に加え、Zensical 固有の記法を用いることで リッチコンテンツが作成できます。
MkDocs では拡張機能として install が必要でしたが、Zensical では 標準機能として実装されてる機能が多数あります。
詳細は以下を確認してください。

https://zensical.org/docs/setup/extensions/

拡張記法やちょっとした Tips を後述しますが、必ずしもこれらの記法を利用する必要はありません。

Admonitions（注意書きボックス）¶

重要な情報を目立たせるための装飾ボックスです。

!!! note

    これは **note** タイプのadmonitionです。補足情報を提供する際に使用します。

!!! warning

    これは **warning** タイプのadmonitionです。注意が必要な情報を伝える際に使用します。

!!! tip "タイトルを指定できます"

    これは **tip** タイプのadmonitionです。「この書き方でタイトルが上書きできる」という `tips` です(仕様です)

その他の利用可能なタイプ：tip, info, success, question, danger, bug, example, quote

Details（折りたたみ可能なブロック）¶

長い説明やFAQなど、折りたたみ可能なコンテンツを作成できます。

??? info "クリックして詳細を表示"

    この内容はクリックするまで非表示です。
    長い説明やFAQに最適です。

コードブロック¶

シンタックスハイライト、行番号、タイトル、ハイライト行などの機能が利用できます。

``` python hl_lines="2 3" title="example.py"
def example():
    # この行がハイライトされます
    print("Hello")
```

def example():
    # この行がハイライトされます
    print("Hello")

Content tabs¶

複数の選択肢やコード例をタブで切り替えて表示できます。

=== "Python"

    ``` python
    print("Hello from Python!")
    ```

=== "JavaScript"

    ``` javascript
    console.log("Hello from JavaScript!");
    ```

print("Hello from Python!")

console.log("Hello from JavaScript!");

Diagrams（図表）¶

Mermaid記法を使って図表を作成できます。

``` mermaid
graph LR
  A[開始] --> B{エラー?};
  B -->|Yes| C[確認];
  C --> D[デバッグ];
  D --> B;
  B -->|No| E[完了];
```

graph LR
  A[開始] --> B{エラー?};
  B -->|Yes| C[確認];
  C --> D[デバッグ];
  D --> B;
  B -->|No| E[完了];

Footnotes（脚注）¶

文章に脚注を追加できます。

これは脚注付きの文章です。[^1]

[^1]: これが脚注の内容です。

Icons/Emojis¶

絵文字やアイコンを使用できます。

:sparkles: :rocket: :memo: :eyes:

Task Lists¶

チェックリストを作成できます。

- [x] 完了したタスク
- [ ] 未完了のタスク
- [ ] これから着手するタスク

テキスト装飾¶

- **太字**
- ==ハイライト（マーカー）==
- ^^挿入（下線）^^
- ~~削除（取り消し線）~~
- H~2~O（下付き文字）
- A^T^A（上付き文字）

これは**NG**です。この~~取り消し線~~は正しく表示されません。

これは **OK** です。この ~~取り消し線~~ は正しく表示されます。

画像の挿入方法¶

通常のMarkdown 形式に加えて、リファレンス形式 (そう呼んでるだけ) があります。

通常のMarkdown形式

![altText](assets/images/example-document-01.svg)

リファレンス形式

[![example-document-01]][example-document-01]

[example-document-01]: assets/images/example-document-01.svg

リンクの記述¶

内部リンク¶

サイト内の他のページへのリンクは相対パスで記述します。

[トップページ](../../index.md)を参照してください。

外部リンク¶

外部サイトへのリンクには、リファレンス形式を推奨します。

詳細は[Zensical公式ドキュメント][zensical-docs]を参照してください。

[zensical-docs]: https://zensical.org/docs/

参考リンク¶

• Zensical公式ドキュメント
• Material for MkDocs
• Markdown Guide