はじめに
本ブログは ナレッジサイトである Classmethod Cloud Guidebook(CCG) 1 の執筆者向けに公開しているブログです。 一般的なMarkdown(MkDocs)シンタックスでも参考になる部分があると思うので、ブログにて公開しています。
CCGを構成しているドキュメントの文法(シンタックス)を共有します。 執筆の際のリファレンスとして活用してください。
基本のMarkdownシンタックス
CCGは 静的サイトジェネレーターである MkDocs (およびその拡張プラグインである Material for MkDocs )から構成されています。 MkDocsでは Markdown で記載されたドキュメントを表示します。
基本的なMarkdown記法については、 普段のブログ執筆などで慣れていると思うので 丁寧に説明しません。
以降で「表示差異が出やすいポイント」に絞って紹介します。
見出しの書き方
見出しはレベル2以降を使います。 なお、見出しレベル1はドキュメントタイトルです。 タイトルは別ファイル( mkdocs.yml ) で管理しています。
段落、改行
段落を作る場合は、空白行を追加してください。 1改行のみの場合は、表示上は改行されません。
リスト
リストの前後には空白行を入れてください。 また、ネストする場合は「半角スペース 4つ」を空けてください。
画像挿入
 の形式で画像を挿入します。 イメージパスはローカルの場合、相対パスで記載します。
Tips: 細かい調整を行いたい場合は以下ページを参考ください。
リンク挿入
[タイトル](URL) 形式で書きます。 タイトルには出典元を載せましょう。
コメントアウト
<!-- および --> で括られた部分はコメントアウトとなります。
コメントアウトした情報も、MkDocsのビルドに含まれることに注意してください。 機密情報は載せないようにしましょう。
MkDocs独自のシンタックス
コールアウト
admonitions(call-outs) を使えます。 目立たせたいコンテンツがある場合に役立ちます。
詳しい使い方は以下ページを参考ください。
Mermaid
Mermaid による図の描画が可能です。 フローチャートなどを書く際に便利です。
詳しい使い方は以下ページを参考ください。 もしくは Mermaid リファレンス を参照ください。
アイコン、絵文字
:thinking: といった書き方でアイコンや絵文字を挿入できます。
使える絵文字は以下ページで検索できます。
その他
他にも、Material for MkDocs に特化した記法があります。 使いたい場合は以下リファレンスを参照ください。
おわりに
以上、CCGドキュメントの文法(シンタックス)を共有しました。
ガンガン執筆していきましょう！
3
