ドキュメントの作成

Markdown ソースファイルのレイアウトと書き方。

---

ファイルレイアウト

ドキュメントのソースは、通常の Markdown ファイルとして（下記の Markdown で書くを参照）記述し、ドキュメントディレクトリに配置する必要があります。デフォルトでは、このディレクトリは docs という名前になり、プロジェクトのトップレベルに、mkdocs.yml 設定ファイルと一緒に存在します。

作成できる最もシンプルなプロジェクトは、次のようになります。

mkdocs.yml
docs/
    index.md

慣例として、プロジェクトのホームページは index.md という名前である必要があります（詳細は下記の インデックスページを参照）。Markdown ソースファイルには、以下のファイル拡張子が使用できます：markdown、mdown、mkdn、mkd、md。ドキュメントディレクトリに含まれるすべての Markdown ファイルは、設定に関係なく、ビルドされたサイトにレンダリングされます。

複数の Markdown ファイルを作成することで、複数ページのドキュメントを作成することもできます。

mkdocs.yml
docs/
    index.md
    about.md
    license.md

使用するファイルレイアウトによって、生成されるページの URL が決まります。上記のレイアウトの場合、以下の URL でページが生成されます。

/
/about/
/license/

ドキュメントのレイアウトに合わせて、ネストされたディレクトリに Markdown ファイルを含めることもできます。

docs/
    index.md
    user-guide/getting-started.md
    user-guide/configuration-options.md
    license.md

ネストされたディレクトリ内のソースファイルは、以下のように、ネストされた URL でページが生成されます。

/
/user-guide/getting-started/
/user-guide/configuration-options/
/license/

ドキュメントディレクトリ内の（ファイル拡張子によって）Markdown ファイルとして識別されないファイルは、MkDocs によって変更されずにビルドされたサイトにコピーされます。詳細については、以下の 画像やメディアへのリンク方法を参照してください。

インデックスページ

ディレクトリが要求された場合、デフォルトでは、ほとんどの Web サーバーは、そのディレクトリ内に（通常は index.html という名前の）インデックスファイルが存在すれば、それを返します。そのため、上記のすべての例のホームページは index.md という名前になっています。MkDocs はサイトをビルドする際に、これを index.html にレンダリングします。

多くのリポジトリホスティングサイトは、ディレクトリの内容を閲覧する際に、README ファイルの内容を表示することにより、README ファイルを特別に扱います。したがって、MkDocs では、インデックスページに index.md ではなく README.md という名前を付けることができます。そうすることで、ユーザーがソースコードを閲覧するときに、リポジトリホストは、そのディレクトリのインデックスページを README ファイルとして表示できます。ただし、MkDocs がサイトをレンダリングするときに、ファイルは index.html に名前が変更され、サーバーが適切なインデックスファイルとして提供するようになります。

index.md ファイルと README.md ファイルの両方が同じディレクトリにある場合は、index.md ファイルが使用され、README.md ファイルは無視されます。

ページとナビゲーションの設定

mkdocs.yml ファイルの nav 設定では、グローバルサイトのナビゲーションメニューに含めるページと、そのメニューの構造を定義します。指定されていない場合、ナビゲーションは、ドキュメントディレクトリ内のすべての Markdown ファイルを検出することにより、自動的に作成されます。自動的に作成されたナビゲーション設定は、常にファイル名でアルファベット順にソートされます（ただし、インデックスファイルは常にサブセクション内で最初にリストされます）。ナビゲーションメニューを異なる順序でソートしたい場合は、ナビゲーション設定を手動で定義する必要があります。

最小限のナビゲーション設定は、次のようになります。

nav:
  - index.md
  - about.md

ナビゲーション設定のすべてのパスは、docs_dir 設定オプションを基準とする必要があります。そのオプションがデフォルト値の docs に設定されている場合、上記の構成のソースファイルは docs/index.md および docs/about.md に配置されます。

上記の例では、トップレベルで 2 つのナビゲーション項目が作成され、タイトルは Markdown ファイルの内容から推測されます。ファイル内にタイトルが定義されていない場合は、ファイル名から推測されます。nav 設定でタイトルをオーバーライドするには、ファイル名の直前にタイトルを追加します。

nav:
  - Home: index.md
  - About: about.md

ナビゲーションでページのタイトルが定義されている場合、そのタイトルはサイト全体でそのページに使用され、ページ自体で定義されたタイトルよりも優先されることに注意してください。

ナビゲーションサブセクションは、関連するページをセクションタイトルの下にまとめてリストすることで作成できます。例：

nav:
  - Home: index.md
  - User Guide:
    - Writing your docs: writing-your-docs.md
    - Styling your docs: styling-your-docs.md
  - About:
    - License: license.md
    - Release Notes: release-notes.md

上記の設定では、「ホーム」、「ユーザーガイド」、「概要」の 3 つのトップレベル項目があります。「ホーム」は、サイトのホームページへのリンクです。「ユーザーガイド」セクションの下には、「ドキュメントの作成」と「ドキュメントのスタイル設定」の 2 つのページがリストされています。「概要」セクションの下には、「ライセンス」と「リリースノート」の 2 つのページがリストされています。

セクションにページを割り当てることはできないことに注意してください。セクションは、子ページとサブセクションのコンテナにすぎません。セクションは、必要なだけ深くネストできます。ただし、ネストを複雑にしすぎて、ユーザーがサイトのナビゲーションを通過するのが難しくならないように注意してください。セクションはディレクトリ構造を反映している可能性がありますが、そうである必要はありません。

ナビゲーション設定にリストされていないページもレンダリングされ、ビルドされたサイトに含まれますが、グローバルナビゲーションからはリンクされず、前へ および 次へ リンクにも含まれません。そのようなページは、直接リンクされない限り、「隠された」状態になります。

Markdown で書く

MkDocs ページは、Markdown で作成する必要があります。Markdown は、読みやすく、書きやすいプレーンテキストドキュメントであり、予測可能な方法で有効な HTML ドキュメントに変換できる軽量マークアップ言語です。

MkDocs は、Markdown ドキュメントを HTML にレンダリングするために Python-Markdown ライブラリを使用します。Python-Markdown は、参照実装にほぼ完全に準拠していますが、いくつかのごくわずかな違いがあります。

すべての Markdown 実装に共通の基本 Markdown 構文に加えて、MkDocs には、Python-Markdown 拡張機能を使用して Markdown 構文を拡張するためのサポートが含まれています。拡張機能を有効にする方法の詳細については、MkDocs の markdown_extensions 設定を参照してください。

MkDocs には、デフォルトでいくつかの拡張機能が含まれており、以下に示します。

内部リンク

MkDocs では、通常の Markdown リンクを使用して、ドキュメントを相互リンクできます。ただし、以下に示すように、MkDocs 用にリンクを具体的にフォーマットすることには、いくつかの追加の利点があります。

ページへのリンク

ドキュメント内のページ間をリンクする場合は、通常の Markdown リンク構文を使用できます。これには、リンク先の Markdown ドキュメントへの相対パスが含まれます。

Please see the [project license](license.md) for further details.

MkDocs のビルドが実行されると、これらの Markdown リンクは、自動的に適切な HTML ページへの HTML ハイパーリンクに変換されます。

ターゲットのドキュメントファイルが別のディレクトリにある場合は、リンクに相対ディレクトリパスを必ず含める必要があります。

Please see the [project license](../about/license.md) for further details.

toc 拡張機能は、MkDocs によって Markdown ドキュメント内のすべてのヘッダーの ID を生成するために使用されます。アンカーリンクを使用することにより、その ID を使用してターゲットドキュメント内のセクションにリンクできます。生成された HTML は、リンクのパス部分を正しく変換し、アンカー部分をそのまま残します。

Please see the [project license](about.md#license) for further details.

ID はヘッダーのテキストから作成されることに注意してください。すべてのテキストは小文字に変換され、空白を含む許可されていない文字はすべてダッシュに変換されます。連続するダッシュは、単一のダッシュに縮小されます。

toc 拡張機能が提供するいくつかの設定オプションがあり、mkdocs.yml 設定ファイルで設定して、デフォルトの動作を変更できます。

• permalink

  各ヘッダーの最後に永続的なリンクを生成します。デフォルト：False。

  True に設定すると、段落記号（¶ または ¶）がリンクテキストとして使用されます。文字列に設定すると、指定された文字列がリンクテキストとして使用されます。たとえば、ハッシュ記号（#）を使用するには、次のようにします。

  markdown_extensions:
    - toc:
        permalink: "#"

• baselevel

  ヘッダーのベースレベル。デフォルト：1。

  この設定を使用すると、ヘッダーレベルを HTML テンプレートの階層内に収まるように自動的に調整できます。たとえば、ページの Markdown テキストにレベル 2 (<h2>) より高いヘッダーを含めないようにするには、次のようにします。

  markdown_extensions:
    - toc:
        baselevel: 2

  次に、ドキュメント内のすべてのヘッダーは 1 増加します。たとえば、ヘッダー # Header は HTML 出力でレベル 2 ヘッダー (<h2>) としてレンダリングされます。

• separator

  単語区切り文字。デフォルト：-。

  生成されたID内の空白を置き換える文字。アンダースコアを使いたい場合は、次のようにします。

  markdown_extensions:
    - toc:
        separator: "_"

上記の複数の設定を定義したい場合は、markdown_extensions設定オプションの単一のtocエントリの下で定義する必要があることに注意してください。

markdown_extensions:
  - toc:
      permalink: "#"
      baselevel: 2
      separator: "_"

画像とメディアへのリンク

Markdownソースファイルだけでなく、ドキュメントサイトの生成時にコピーされる他のファイルタイプをドキュメントに含めることもできます。これには、画像やその他のメディアが含まれる場合があります。

たとえば、プロジェクトドキュメントにGitHub Pages CNAMEファイルとPNG形式のスクリーンショット画像を含める必要がある場合、ファイルレイアウトは次のようになる可能性があります。

mkdocs.yml
docs/
    CNAME
    index.md
    about.md
    license.md
    img/
        screenshot.png

ドキュメントのソースファイルに画像を含めるには、通常のMarkdown画像構文を使用するだけです。

Cupcake indexer is a snazzy new project for indexing small cakes.

![Screenshot](img/screenshot.png)

*Above: Cupcake indexer in progress*

ドキュメントをビルドすると画像が埋め込まれ、Markdownエディターでドキュメントを操作している場合はプレビューも表示されます。

生のHTMLからのリンク

Markdownでは、Markdown構文が著者のニーズを満たさない場合に、ドキュメント作成者が生のHTMLにフォールバックできます。MkDocsはこの点でMarkdownを制限しません。ただし、すべての生のHTMLはMarkdownパーサーによって無視されるため、MkDocsは生のHTMLに含まれるリンクを検証または変換できません。生のHTML内に内部リンクを含める場合は、レンダリングされたドキュメントに合わせてリンクを手動でフォーマットする必要があります。

メタデータ

MkDocsには、YAML形式とMultiMarkdown形式の両方のメタデータ（多くの場合、フロントマターと呼ばれます）のサポートが含まれています。メタデータは、Markdownドキュメントの先頭で定義された一連のキーワードと値で構成され、Python-Markdownによる処理の前にドキュメントから削除されます。キーと値のペアは、MkDocsによってページテンプレートに渡されます。したがって、テーマがサポートを含んでいる場合、任意のキーの値をページに表示したり、ページレンダリングを制御するために使用したりできます。サポートされているキーがある場合は、テーマのドキュメントで確認してください。

テンプレートに情報を表示することに加えて、MkDocsには、その特定のページのMkDocsの動作を変更できる、事前定義されたいくつかのメタデータキーのサポートが含まれています。次のキーがサポートされています。

• template

  現在のページで使用するテンプレート。

  デフォルトでは、MkDocsはテーマのmain.htmlテンプレートを使用してMarkdownページをレンダリングします。templateメタデータキーを使用して、その特定のページに対して異なるテンプレートファイルを定義できます。テンプレートファイルは、テーマの環境で定義されたパスで使用できる必要があります。

• title

  ドキュメントに使用する「タイトル」。

  MkDocsは、次の順序で、ドキュメントのタイトルを決定しようとします。

  1. ドキュメントのnav設定で定義されたタイトル。

  2. ドキュメントのtitleメタデータキーで定義されたタイトル。

  3. ドキュメント本文の最初の行のレベル1のMarkdownヘッダー。
     (Setext形式のヘッダーは、MkDocs 1.5以降でのみサポートされています。)

  4. ドキュメントのファイル名。

  ページのタイトルを見つけると、MkDocは上記のリストの追加のソースの確認を続行しません。

YAML形式のメタデータ

YAML形式のメタデータは、メタデータの開始および/または終了をマークするためにYAML形式の区切り文字でラップされたYAMLキーと値のペアで構成されています。ドキュメントの最初の行は---である必要があります。メタデータは、終了区切り文字（---または...のいずれか）を含む最初の行で終わります。区切り文字の間のコンテンツは、YAMLとして解析されます。

---
title: My Document
summary: A brief description of my document.
authors:
    - Waylan Limberg
    - Tom Christie
date: 2018-07-10
some_url: https://example.com
---
This is the first paragraph of the document.

YAMLはデータ型を検出できます。したがって、上記の例では、title、summary、およびsome_urlの値は文字列であり、authorsの値は文字列のリストであり、dateの値はdatetime.dateオブジェクトです。YAMLキーは大文字と小文字が区別され、MkDocsはキーがすべて小文字であることを想定していることに注意してください。YAMLの最上位はキーと値のペアのコレクションである必要があり、Pythonのdictが返されます。他の型が返されたり、YAMLパーサーがエラーを検出した場合、MkDocsはそのセクションをメタデータとして認識せず、ページのmeta属性は空になり、そのセクションはドキュメントから削除されません。

MultiMarkdown形式のメタデータ

MultiMarkdown形式のメタデータは、MultiMarkdownプロジェクトで最初に導入された形式を使用します。データは、Markdownドキュメントの先頭で定義された一連のキーワードと値で構成されています。次のような形式です。

Title:   My Document
Summary: A brief description of my document.
Authors: Waylan Limberg
         Tom Christie
Date:    January 23, 2018
blank-value:
some_url: https://example.com

This is the first paragraph of the document.

キーワードは大文字と小文字が区別されず、文字、数字、アンダースコア、ダッシュで構成でき、コロンで終わる必要があります。値は、行のコロンに続く任意の文字列で構成され、空白でもかまいません。

行が4つ以上のスペースでインデントされている場合、その行は前のキーワードの値の追加の行であると見なされます。キーワードには、必要な数の行を含めることができます。すべての行が1つの文字列に結合されます。

最初の空白行で、ドキュメントのすべてのメタデータが終了します。したがって、ドキュメントの最初の行は空白にすることはできません。

テーブル

tables拡張機能は、複数の実装で一般的な基本的なテーブル構文をMarkdownに追加します。構文は非常にシンプルで、一般的に単純な表形式のデータにのみ役立ちます。

簡単なテーブルは次のようになります。

First Header | Second Header | Third Header
------------ | ------------- | ------------
Content Cell | Content Cell  | Content Cell
Content Cell | Content Cell  | Content Cell

必要に応じて、テーブルの各行に先頭と末尾のパイプを追加できます。

| First Header | Second Header | Third Header |
| ------------ | ------------- | ------------ |
| Content Cell | Content Cell  | Content Cell |
| Content Cell | Content Cell  | Content Cell |

区切り記号の行にコロンを追加して、各列の配置を指定します。

First Header | Second Header | Third Header
:----------- |:-------------:| -----------:
Left         | Center        | Right
Left         | Center        | Right

テーブルセルにはブロックレベルの要素を含めることができず、複数行のテキストを含めることはできません。ただし、Markdownの構文ルールで定義されているように、インラインMarkdownを含めることができます。

さらに、テーブルは空白行で囲む必要があります。テーブルの前後に空白行が必要です。

フェンス付きコードブロック

フェンス付きコードブロック拡張機能は、インデントなしでコードブロックを定義する代替方法を追加します。

最初の行には3つ以上のバッククォート（`）文字を含める必要があり、最後の行には同じ数のバッククォート（`）文字を含める必要があります。

```
Fenced code blocks are like Standard
Markdown’s regular code blocks, except that
they’re not indented and instead rely on
start and end fence lines to delimit the
code block.
```

このアプローチでは、最初の行のバックティックの後に言語をオプションで指定でき、使用される言語の構文ハイライターに通知します。

```python
def fn():
    pass
```

フェンス付きコードブロックはインデントできないことに注意してください。したがって、リストアイテム、引用符などの内部にネストすることはできません。