跳转至

编辑文档文件

注意

在阅读这部分内容之前，请确保您理解了 开发周期 并完成了 设置指南。

目录结构

首先，您需要了解文档的目录结构。

根目录

在项目的根目录下，您将看到一个类似于以下的目录结构：

├───.github
│   ├───ISSUE_TEMPLATE
│   └───workflows
├───docs
├───overrides
│   ├───home.html
│   └───main.html
├───mkdocs.yaml
└───requirements.txt

重要文件

  • mkdocs.yaml: 文档的顶层配置。包含诸如导航树和插件使用的信息。
  • requirements.txt: 用于存储文档所需的所有依赖版本。您不需要编辑此文件。

重要目录

  • .github: 此文件夹包含有关github的信息，例如问题模板和工作流程。

  • docs: 此文件夹包含用于创建文档页面的所有文件。您将在这里找到Markdown文件。

  • overrides/: 此文件夹包含“主题覆盖”，使我们能够对文档进行非常精细的控制。

其他目录

您的项目目录中还有一些其他文件/文件夹，例如 venv/、.gitignore 和 README.md。所有这些文件都不需要编辑，因此我在这里不解释它们。

特殊文件

这些文件/文件夹中的大部分内容在 特殊文件 页面中有更详细的说明。

docs/ 目录结构

docs/ 文件夹是您将花费大部分时间的地方。它包含所有 *.md 文件以及文档中使用的资源。基本的目录结构如下所示：

├───assets
│   └───images
│       ├───icons
│       ├───logo
│       └───screenshots
├───contributing
├───getting-started
├───layouts
├───stylesheets
└───index.md

资源

此文件夹包含文档中使用的资源。目前此文件夹主要包含图像。您会发现它已组织到子文件夹中，在本例中仅为 images/。当您需要引用任何图像时，您将在这里进行导航。

特殊目录

  • layouts/: 包含文档中用于特定用例的图像和布局。目前它仅包含构成社交卡片的Jinja模板的数据。

  • stylesheets/: 包含用于覆盖文档样式的额外 *.css 文件。例如，配色方案在这里找到。

其他目录

在这里找到的其余目录是文档的各个部分。这些目录中的每一个都与一个部分对应。例如，contributing/ 目录对应于您当前所在的“帮助参与”部分。

index.md - 特殊文件

index.md 是一个特殊文件，您会发现它在包含 *.md 文件的每个文件夹中。此文件是每个文件夹的“主页”。因此，当它在根 docs/ 文件夹中时，它是整个站点的首页。另一个示例是 contributing/ 文件夹中的 index.md，它是“帮助参与”部分的主页，等等。

特殊情况：主页

根 docs/ 目录中的 index.md 文件不包含任何实际的Markdown。这是因为它是一个完全自定义的页面，使用html和css作为主题覆盖编写，有关更多信息 这里。

Markdown简介

本节将作为一个非常基础的Markdown介绍。此外，还将描述文档中包含的额外功能，这些功能在普通Markdown中不可用。

首先，大多数编写的内容都只是纯文本，例如您当前正在阅读的这部分内容就是纯文本。

简单格式选项

  • 标题：# 标题 我们使用井号来表示标题，您可以从此标题到标题6，1是最大的标题，6是最小的标题。此数字对应于井号的数量。标题3将如下所示：### 标题。
  • 粗体：**粗体文本** 我们使用双星号来表示粗体文本。
  • 代码块：这是 `代码块`，特别是行内代码块 多行代码块也是可用的，查看 此 部分了解更多
  • 列表：- 列表项 短横号表示项目符号列表，如下所示。对于编号列表，只需编写 1. 编号列表项

像这样的大纲可以使用 > 在开头编写：> 示例大纲

您会发现所有这些都需要一个特定的字符后跟一个空格。如果您在特殊字符和文本之间不包括一个空格，它将无法正确显示。

超链接

我们使用标准的Markdown实现来创建超链接，但是可以添加一些额外的属性。这是一个带有文本“主页”和主页链接的标准链接：

[主页](https://hass-agent.github.io/latest/)

内部链接

内部链接指向此文档内的页面或部分，例如我想将用户导航到设置文档的分支部分：

[有关分支存储库的更多信息](./setup.md/#forking-the-repo)

有关分支存储库的更多信息

此链接通过使用 ./ 后跟文件名指向本地文件。如果您想进入上一级目录，请使用 ../ 这些可以链接在一起以获取文档中的任何位置。例如 ../../getting-started/index.md

井号指定您要链接到的页面部分，VSCode应自动完成此内容，但如果未自动完成，您可以点击文档中任何标题右侧的P图标，顶部URL将以正确的井号链接结束。

示例

我们当前所在的这一部分可以通过 #inside-links 链接

外部链接

您可以添加指向任何地址的链接，但是大多数情况下它们应该在新的标签页中打开。除非链接是直接文件下载链接，否则您需要添加此属性以告诉浏览器在新标签页中打开链接：{: target="\_blank"}

示例链接在新标签页中打开谷歌
[谷歌](https://google.com){: target="\_blank"}

谷歌

换行和文档结构

每种不同的“文本类型”都应该有一个换行符将其与上一个文本分开。因此，标题和段落之间应该有一个换行符，标题和列表项组之间也应该有一个换行符，等等。

分隔段落

您可以通过两种方式分隔段落，以下是两个选项：
文本从下一行开始。

在下一个文本块之前创建一个间隙。

您可以通过在文件中创建一个换行符来在段落之间创建一个间隙。要在下一行继续文本而不创建间隙，请在上一行的末尾添加两个空格。

代码块

代码块正如其名，用于表示代码，它们具有不同的样式，并且可以根据语法进行复制和高亮显示。

行内代码块

这些是最简单的。它们只是段落或行的一部分。这些选项没有复制按钮或注释。

示例：行内代码块 普通文本

您可以通过在代码块的开始和结束处添加反引号：` 来编写这些行内代码块。

多行代码块

这些代码块稍微复杂一些，但包括复制按钮和行高亮显示等功能。

基本代码块

一个基本代码块可以使用开始和结束处的三个反引号：``` 来编写。

示例基本代码块语法
```
def add1(num):
  return num += 1
```

看起来像这样：

def add1(num):
  return num += 1

您会注意到每个代码块右上角都有一个复制按钮。

语法高亮显示

您可以为几乎所有语言添加语法高亮显示。以下是相同的Python函数，带有一些高亮显示：

def add1(num):
  return num += 1

为此，您需要在反引号后添加语言短代码。例如：

```py
高亮显示为python
```

行号、标题和高亮显示行

行号

您可以使用 linenums="1" 添加行号，这将使第一行成为1。您可以设置第一行为任何数字；
例如，要从54(1)开始，请使用 linenums="54"。

  1. 这只是一个示例数字，可以使用任何数字。
高亮显示行

您还可以使用 hl_lines="2 3" 高亮显示任何行；这将高亮显示行2和行3，如果您想使用范围，只需添加一个连字符：hl_lines="3-5"

添加标题

您可以使用 title="这是一个标题" 添加标题。

具有行号、标题和突出显示行2
1
2
def add1(num):
  return num += 1

注释、脚注和警告

文档还具有注释和警告，这些不是普通的Markdown功能。

注释

注释概述

注释是可以在文档中几乎任何位置放置的小加号按钮，当点击时显示更多信息。(1)

  1. 这是一个示例注释

语法

您可以在任何地方添加这些内容，在两个括号内添加一个数字，例如：(1)。然后在该块的末尾添加 {.annotate} 后跟与注释编号对应的编号列表。这里有一个带注释的示例，以帮助您理解：

示例文本带有注释： (1)

这里还有另一个注释： (2)
{.annotate}

1. 这是第一个注释 - 对应于 `(1)`
2. 另一个注释 - 对应于 `(2)`

注意

注意代码块后的 {.annotate}，它对于列表项不被渲染并链接到 (1) 是必需的。 还要注意使用的数字，它们必须匹配以使注释正确工作。

更多信息可以在 这里 找到

脚注

脚注可以添加到页面的任何位置。它们与注释类似，如下所示：

这句话的末尾有一个脚注。1

语法

您可以用 [^1] 在页面中的任何位置表示脚注，编号与注释相同。只需确保页面中的位置和底部的编号对应即可。

在页面的最底部，您编写相同的标识符，因此在这种情况下 [^1] 后跟一个冒号，如下所示：

文本带有脚注： [^1]

[^1]: 这是一个示例脚注文本

更多信息可以在 这里 找到

警告

警告是您看到的“备注”或“警告”，它们位于彩色框中，非常突出。以下是一个示例：

示例警告

警告文本

语法

它们可以这样编写：

!!! 注意

    这是一个备注警告

通过在警告类型后添加文本在 "" 中添加标题：

!!! 注意 "备注警告示例标题"

可折叠警告

您可以创建静态警告或可折叠警告。可折叠警告用 ??? 而不是 !!! 表示，如果您希望可折叠警告默认打开，则使用 ???+。

更多信息，包括警告类型列表，可以在 这里 找到

图表

文档中的多个图表分布在页面中，可以从此Markdown文件中编辑。所有这些都是基于 mermaidjs。

文档基本上只使用流程图以获得更好的样式，但所有mermaid类型从技术上讲都是支持的。您可以在 这里 找到流程图文档，有关我们mermaidjs实现的更多信息 这里。

  1. 示例脚注，您可以在这里使用Enter按钮返回到您之前的位置： ↩