编写你的文档

如何布局和编写你的 Markdown 源文件。

---

文件布局

你的文档源文件应编写为常规的 Markdown 文件（参见下面的使用 Markdown 编写），并放置在文档目录中。默认情况下，此目录将被命名为 docs，并位于项目的顶层，与 mkdocs.yml 配置文件并列。

你可以创建的最简单的项目将如下所示：

mkdocs.yml
docs/
    index.md

按照惯例，你的项目主页应命名为 index.md（详见下面的索引页面）。以下任何文件扩展名都可用于你的 Markdown 源文件：markdown、mdown、mkdn、mkd、md。所有包含在你的文档目录中的 Markdown 文件都将被渲染到构建的站点中，无论任何设置。

注意： 以点开头的文件和目录（例如：.foo.md 或 .bar/baz.md）会被 MkDocs 忽略。这可以通过 exclude_docs 配置来覆盖。

你也可以通过创建多个 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 文件，显示其内容。因此，MkDocs 允许你将索引页面命名为 README.md 而不是 index.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。

上述示例将在顶层创建两个导航项，并从 Markdown 文件的内容或文件名（如果文件中未定义标题）推断其标题。要在 nav 设置中覆盖标题，请在文件名前添加标题。

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

请注意，如果在导航中为页面定义了标题，该标题将在整个站点中用于该页面，并覆盖页面本身定义的任何标题。

可以通过在节标题下列出相关页面来创建导航子节。例如：

nav:
  - 首页: index.md
  - 用户指南:
    - 编写您的文档: writing-your-docs.md
    - 美化您的文档: styling-your-docs.md
  - 关于:
    - 许可证: license.md
    - 发行说明: release-notes.md

通过上述配置，我们拥有三个顶级项目：“首页”、“用户指南”和“关于”。“首页”是网站的主页链接。在“用户指南”部分下列出了两个页面：“编写您的文档”和“样式化您的文档”。在“关于”部分下列出了另外两个页面：“许可证”和“发布说明”。

请注意，一个部分不能分配给一个页面。部分仅作为子页面和子部分的容器。您可以根据需要嵌套部分。然而，请注意不要通过过度复杂化嵌套结构，使得用户难以通过站点导航进行浏览。虽然部分可以反映您的目录结构，但它们不必如此。

任何未列在导航配置中的页面仍将被渲染并包含在构建的站点中，但它们不会从全局导航中链接，也不会包含在“上一页”和“下一页”链接中。除非直接链接到这些页面，否则它们将被“隐藏”。

使用 Markdown 编写

MkDocs 页面必须使用 Markdown 编写，这是一种轻量级标记语言，能够生成易于阅读、易于编写的纯文本文档，这些文档可以以可预测的方式转换为有效的 HTML 文档。

MkDocs 使用 Python-Markdown 库将 Markdown 文档渲染为 HTML。Python-Markdown 几乎完全符合 参考实现，尽管存在一些非常小的 差异。

除了所有 Markdown 实现通用的基本 Markdown 语法 外，MkDocs 还支持通过 Python-Markdown 扩展 扩展 Markdown 语法。有关如何启用扩展的详细信息，请参阅 MkDocs 的 markdown_extensions 配置设置。

MkDocs 默认包含一些扩展，下面将重点介绍这些扩展。

内部链接

MkDocs 允许您通过使用常规的 Markdown 链接 来相互链接文档。然而，如下所述，为 MkDocs 格式化这些链接有一些额外的好处。

链接到页面

在文档中的页面之间进行链接时，您可以简单地使用包含目标 Markdown 文档的 相对路径 的常规 Markdown 链接 语法。

请参阅 [项目许可证](license.md) 以获取更多详细信息。

当 MkDocs 构建运行时，这些 Markdown 链接将自动转换为指向相应 HTML 页面的 HTML 超链接。

警告： 使用绝对路径的链接不受官方支持。相对路径由 MkDocs 调整，以确保它们始终相对于页面。绝对路径根本不会被修改。这意味着使用绝对路径的链接在本地环境中可能正常工作，但在部署到生产服务器后可能会中断。

如果目标文档文件在另一个目录中，您需要确保在链接中包含任何相对目录路径。

请参阅 [项目许可证](../about/license.md) 以获取更多详细信息。

MkDocs 使用的 toc 扩展为 Markdown 文档中的每个标题生成一个 ID。您可以使用该 ID 通过锚链接链接到目标文档中的某个部分。生成的 HTML 将正确转换链接的路径部分，并保留锚部分。

请参阅 [项目许可证](about.md#license) 以获取更多详细信息。

请注意，ID 是根据标题的文本创建的。所有文本都转换为小写，任何不允许的字符（包括空格）都转换为破折号。连续的破折号随后减少为一个破折号。

toc 扩展提供了一些配置设置，您可以在 mkdocs.yml 配置文件中设置这些设置以更改默认行为：

• permalink

  在每个标题末尾生成永久链接。默认值：False。

  当设置为 True 时，段落符号（¶ 或 ¶）用作链接文本。当设置为字符串时，提供的字符串用作链接文本。例如，要使用井号（#），请执行以下操作：

  markdown_extensions:
    - toc:
        permalink: "#"

• baselevel

  标题的基本级别。默认值：1。

  此设置允许自动调整标题级别，以适应 HTML 模板的层次结构。例如，如果页面的 Markdown 文本不应包含高于级别 2（<h2>）的标题，请执行以下操作：

  yaml markdown_extensions: - toc: baselevel: 2

  
  然后，文档中的任何标题都会增加1级。例如，标题 `# Header` 将在HTML输出中渲染为2级标题（`<h2>`）。
  
  *   **`separator`**
  
      单词分隔符。默认值：`-`。
  
      在生成的ID中替换空白字符的字符。如果你更喜欢使用下划线，可以这样做：
  
      ```yaml
      markdown_extensions:
        - toc:
            separator: "_"
      ```
  
  请注意，如果你想定义上述多个设置，必须在 `markdown_extensions` 配置选项中的单个 `toc` 条目下进行。
  
  ```yml
  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 是一个用于索引小蛋糕的新项目。

![截图](img/screenshot.png)

*上方：正在进行的Cupcake索引器*

当你构建文档时，图片将被嵌入，如果你使用Markdown编辑器编写文档，图片也应该会被预览。

从原始HTML链接

Markdown允许文档作者在Markdown语法不满足需求时回退到原始HTML。MkDocs在这方面不限制Markdown。然而，由于所有原始HTML都被Markdown解析器忽略，MkDocs无法验证或转换包含在原始HTML中的链接。当在原始HTML中包含内部链接时，你需要手动格式化链接以适应渲染后的文档。

元数据

MkDocs支持YAML和MultiMarkdown风格的元数据（通常称为front-matter）。元数据由一系列关键字和值组成，定义在Markdown文档的开头，这些内容在文档被Python-Markdown处理之前会被剥离。键/值对由MkDocs传递给页面模板。因此，如果主题支持，任何键的值都可以显示在页面上或用于控制页面渲染。请参阅你使用的主题的文档，了解哪些键可能被支持（如果有的话）。

除了在模板中显示信息外，MkDocs还支持一些预定义的元数据键，这些键可以改变MkDocs对该特定页面的行为。以下键受支持：

• template

  用于当前页面的模板。

  默认情况下，MkDocs使用主题的 main.html 模板来渲染Markdown页面。你可以使用 template 元数据键为特定页面定义不同的模板文件。模板文件必须位于主题环境定义的路径中。

• title

  用于文档的“标题”。

  MkDocs将尝试按以下顺序确定文档的标题：

  1. 在nav配置设置中为文档定义的标题。

  2. 在文档的 title 元数据键中定义的标题。

  3. 文档正文第一行的1级Markdown标题。
     （仅自MkDocs 1.5起支持Setext-style标题。）

  4. 文档的文件名。

  一旦找到页面的标题，MkDoc将不会继续检查上述列表中的任何其他来源。

YAML风格元数据

YAML风格的元数据由YAML键/值对组成，这些键/值对用YAML风格的定界符包裹，以标记元数据的开始和/或结束。文档的第一行必须是 ---。元数据在包含结束定界符（--- 或 ...）的第一行结束。定界符之间的内容被解析为YAML。

---
title: 我的文档
summary: 我的文档的简要描述。
authors:
    - Waylan Limberg
    - Tom Christie
date: 2018-07-10
some_url: https://example.com
---
这是文档的第一个段落。

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 个或更多空格，则该行被认为是前一个关键字的值的附加行。一个关键字可以有任意多行。所有行都被连接成一个字符串。

第一个空白行结束文档的所有元数据。因此，文档的第一行不能是空白的。

注意： MkDocs 不支持 MultiMarkdown 风格元数据的 YAML 风格分隔符（--- 或 ...）。实际上，MkDocs 依赖于分隔符的存在与否来确定是使用 YAML 风格元数据还是 MultiMarkdown 风格元数据。如果检测到分隔符，但分隔符之间的内容不是有效的 YAML 元数据，MkDocs 不会尝试将内容解析为 MultiMarkdown 风格元数据。

表格

[表格] 扩展为 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 个或更多的反引号（`）字符，最后一行应包含相同数量的反引号字符（`）：

```
围栏代码块类似于标准 Markdown 的常规代码块，
除了它们不缩进，而是依赖于开始和结束的围栏线来分隔代码块。
```

通过这种方法，语言可以选择在第一行的反引号后指定，这会通知任何语法高亮器所使用的语言：

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

请注意，围栏代码块不能缩进。因此，它们不能嵌套在列表项、块引用等内部。