跳转至

Add new pages to custom documentation（向自定义文档添加新页面）

In-platform custom documentation is written in Markdown. To add a new page to a custom documentation bundle, create a new Markdown file (.md) in the documentation repository and ensure that it meets these requirements:

Each Markdown file (.md) in a documentation repository is published as a separate page of documentation, grouped by bundle and linked via the automatically-generated table of contents.

To edit the content of a custom docs page, use Code Repositories to create a new branch of the docs repository, modify the Markdown file, and commit/build your changes.

Specify a page title

All content pages within a documentation bundle require the specification of a page title. This is done using the @title annotation at the top of each Markdown file (other than overview.md, which uses @name).

For example:

@title Example title

This is the text of the documentation page named "Example title in sentence case".

:::callout{theme="neutral"} Note that the actual filename and page name specified with the @title annotation do not need to be the same. :::

Add the new page to ordering.md

Each page in a documentation bundle (other than the mandatory overview.md) must be specified in an ordering.md file in the documentation repository. The ordering.md enables you to structure and organize the documentation bundle with section annotations. The left-hand table of contents is automatically generated with these section annotations.

Learn more about organizing your documentation bundle.

Optional: Use a different label in the table of contents

The filename of a content page is used to generate the URL for that page, but the @title page title is used in the left-hand table of contents. If you want a page's label in the table of contents label to be different from the page's title (for instance, if the page title is very long), you can specify a table of contents label using the @toc annotation.

Building off the example above, we might have a file like:

@title Example long title in sentence case
@toc Example

This is the text of the documentation page named "Example long title in sentence case". The page's title will appear in the table of contents as "Example".

中文翻译

向自定义文档添加新页面

平台内的自定义文档使用 Markdown 编写。要向自定义文档包（custom documentation bundle）添加新页面，请在文档仓库中创建一个新的 Markdown 文件（.md），并确保满足以下要求：

文档仓库中的每个 Markdown 文件（.md）都会作为独立的文档页面发布，按包（bundle）分组，并通过自动生成的目录（table of contents）进行链接。

要编辑自定义文档页面的内容，请使用代码仓库（Code Repositories）为文档仓库创建一个新分支，修改 Markdown 文件，然后提交/构建您的更改。

指定页面标题

文档包中的所有内容页面都需要指定页面标题。这可以通过在每个 Markdown 文件顶部使用 @title 注解来实现（overview.md 除外，它使用 @name）。

例如：

@title 示例标题

这是名为“示例标题（句子首字母大写形式）”的文档页面文本。

:::callout{theme="neutral"} 请注意，实际文件名与通过 @title 注解指定的页面名称不必相同。 :::

将新页面添加到 ordering.md

文档包中的每个页面（除必需的 overview.md 外）都必须在文档仓库的 ordering.md 文件中指定。ordering.md 允许您使用章节注解（section annotations）来构建和组织文档包。左侧的目录会根据这些章节注解自动生成。

了解有关组织文档包的更多信息。

可选：在目录中使用不同的标签

内容页面的文件名用于生成该页面的 URL，但左侧目录中显示的是 @title 指定的页面标题。如果您希望页面在目录中的标签与页面标题不同（例如，页面标题过长），可以使用 @toc 注解指定目录标签。

基于上述示例，我们可以创建一个如下所示的文件：

@title 示例长标题（句子首字母大写形式）
@toc 示例

这是名为“示例长标题（句子首字母大写形式）”的文档页面文本。该页面的标题在目录中将显示为“示例”。