跳转至

Custom docs bundle structure（自定义文档包结构）

The ordering.md file for a custom documentation bundle determines the structure and organization of pages in the bundle. A section annotation must be specified for each page in a documentation bundle; the set of available section annotations is predetermined and cannot be altered.

File structure

Within your documentation repository, the structure of your project might look as follows:

docs/
├── product-A/
│   └── concepts
│       └── concept-doc.md
│   └── tutorials
│       └── tutorial-doc.md
│   └── ordering.md
│   └── overview.md
└── product-B/
    └── ...
  • All documentation must be nested under the docs/ folder as bundles (such as product-A above).
  • These bundle folders map to the set of products that appear on the homepage of the in-platform custom documentation.
  • All bundles should contain an ordering.md and overview.md file at the product folder level.
  • The actual folders and files nested under each "product" (such as the concepts and tutorials folders in the example above) can be customized for your needs.

Table of contents and ordering.md

Every documentation page in a bundle must be listed in the ordering.md file with a section annotation and the filename (without the .md extension). When the custom documentation service service discovers and compiles the documentation, these section annotations are used to construct the left-hand table of contents.

Section annotations

The in-platform custom documentation has a series of section annotations that you can use in the ordering.md file to determine how to organize your content pages.

The section annotations that currently exist are:

  • @quickstart
  • @howto
  • @tutorial
  • @concept
  • @resource
  • @api
  • @reference

There is no requirement to use every section annotation in a documentation bundle. However, every page in a documentation bundle must have a section annotation.

Summary of section annotations

The in-platform custom documentation service imposes a standard structure for documentation, enforced by section annotations. Below is a general guideline for the available sections; however, you should feel empowered to use the sections as you see fit.

  • Overview: Generated from overview.md, this is the home page of a custom documentation bundle.
  • Quick Starts: Brief guides to the fundamentals of the product. A first-time user would start here and walk away with enough knowledge to be able to start using the product.
  • Concepts: Core ideas and concepts related to an application/service. This may not necessarily be actionable content, but describes key concepts that may be useful to describe how or why something works the way it does.
  • How To: Guides that help users with common, generic, self-contained tasks.
  • Tutorials: Step-by-step guides that a user can follow to achieve a specific outcome by completing a set of tasks. Tutorials can be used to outline end-to-end workflows and often use notional data to help users follow along.
  • References: Technical references for syntax, types, and other information.
  • Resources: Internal and external resources, such as useful links or FAQs.
  • APIs: API endpoints of the product.

Example ordering.md

Every page in a documentation bundle must be listed in the ordering.md with a section annotation and the filename (without the .md file extension). For example, an ordering file for Contour might look like:

@quickstart getting-started
@concept core-concepts
@resource faq
@howto boards-add
@howto boards-filter
@howto boards-join
@howto boards-verify-results
@reference boards-descriptions
@tutorial boards-map

The order in which the filenames appear in the ordering.md determines the order of the table of contents. The table of contents for the example ordering.md file above will contain a "How Tos" header with "Add boards" (@howto boards-add) listed first, then "Filter boards" (@howto boards-filter), and so on.

Nesting documentation with child pages

If you do not want a documentation page to show up at the top level of the table of contents, but instead want the page to be nested underneath another page, you can use child pages. There are two ways to declare child<>parent relationships in the custom documentation:

Declare the child on the parent page

You can nest pages as children of a parent page using the @child annotation on the parent page. This allows you to specify the order in which these child pages appear nested below the parent. For example, we might have example-parent-page.md with the following:

@title Parent

@child page-one
@child page-two
@child page-three

The order of the @child annotations determines the order in which the pages will be listed in the table of contents. Child pages do not need to be included in your ordering.md file. As long as parent pages are listed, the documentation service will publish the child pages.

Declare the parent on the child page

:::callout{theme="warning"} If you are referencing files in the same bundle, you should use @child and not @parent. @child allows you to specify the ordering of the children, so @child is strictly more expressive than @parent. @parent should only be used to add a child to a parent page that is not aware of the child’s existence (for example, adding a custom Contour board as a child under the Contour boards page in a different bundle). :::

If you are writing a page and know that another page will be its parent, you can use the @parent annotation at the top of the file as follows: @parent parent-filename. You only need to use one of @child or @parent; there is no need to use both.

中文翻译

自定义文档包结构

自定义文档包中的 ordering.md 文件决定了包内页面的结构与组织方式。文档包中的每个页面都必须指定一个章节注释；可用的章节注释集合是预定义的，不可更改。

文件结构

在您的文档仓库中，项目结构可能如下所示：

docs/
├── product-A/
│   └── concepts
│       └── concept-doc.md
│   └── tutorials
│       └── tutorial-doc.md
│   └── ordering.md
│   └── overview.md
└── product-B/
    └── ...
  • 所有文档必须嵌套在 docs/ 文件夹下，作为包（如上述的 product-A）。
  • 这些包文件夹对应平台内自定义文档首页上显示的产品集合。
  • 所有包应在产品文件夹层级包含 ordering.md 和 overview.md 文件。
  • 每个"产品"下嵌套的实际文件夹和文件（如上例中的 concepts 和 tutorials 文件夹）可根据您的需求自定义。

目录与 ordering.md

包中的每个文档页面都必须在 ordering.md 文件中列出，并附带章节注释和文件名（不含 .md 扩展名）。当自定义文档服务发现并编译文档时，这些章节注释将用于构建左侧目录。

章节注释

平台内自定义文档提供了一系列章节注释，您可以在 ordering.md 文件中使用它们来决定内容页面的组织方式。

当前存在的章节注释包括：

  • @quickstart
  • @howto
  • @tutorial
  • @concept
  • @resource
  • @api
  • @reference

文档包中不要求使用所有章节注释。但文档包中的每个页面都必须有一个章节注释。

章节注释汇总

平台内自定义文档服务通过章节注释强制执行标准的文档结构。以下是可用章节的通用指南；但您可以根据需要灵活使用这些章节。

  • 概述 (Overview)：由 overview.md 生成，是自定义文档包的首页。
  • 快速入门 (Quick Starts)：产品基础知识的简要指南。首次使用的用户可从这里开始，获得足够的知识以开始使用产品。
  • 概念 (Concepts)：与应用程序/服务相关的核心思想和概念。这些内容不一定可操作，但描述了关键概念，有助于解释某事物为何以特定方式工作。
  • 操作指南 (How To)：帮助用户完成常见、通用、独立任务的指南。
  • 教程 (Tutorials)：用户可遵循的分步指南，通过完成一系列任务来实现特定结果。教程可用于概述端到端工作流，通常使用模拟数据帮助用户跟随操作。
  • 参考 (References)：关于语法、类型和其他信息的技术参考。
  • 资源 (Resources)：内部和外部资源，如实用链接或常见问题解答。
  • API (APIs)：产品的 API 端点。

ordering.md 示例

文档包中的每个页面都必须在 ordering.md 中列出，并附带章节注释和文件名（不含 .md 文件扩展名）。例如，Contour 的排序文件可能如下所示：

@quickstart getting-started
@concept core-concepts
@resource faq
@howto boards-add
@howto boards-filter
@howto boards-join
@howto boards-verify-results
@reference boards-descriptions
@tutorial boards-map

文件名在 ordering.md 中出现的顺序决定了目录的顺序。上述示例 ordering.md 文件的目录将包含一个"操作指南 (How Tos)"标题，其中"添加面板 (Add boards)"（@howto boards-add）列在首位，然后是"筛选面板 (Filter boards)"（@howto boards-filter），依此类推。

使用子页面嵌套文档

如果您不希望文档页面显示在目录的顶层，而是希望将其嵌套在另一个页面下，可以使用子页面。在自定义文档中声明子页面与父页面关系有两种方式：

在父页面上声明子页面

您可以使用父页面上的 @child 注释将页面嵌套为父页面的子页面。这允许您指定这些子页面在父页面下嵌套显示的顺序。例如，example-parent-page.md 可能包含以下内容：

@title Parent

@child page-one
@child page-two
@child page-three

@child 注释的顺序决定了页面在目录中的列出顺序。子页面无需包含在您的 ordering.md 文件中。只要父页面被列出，文档服务就会发布子页面。

在子页面上声明父页面

:::callout{theme="warning"} 如果您引用的是同一包中的文件，应使用 @child 而非 @parent。@child 允许您指定子页面的顺序，因此 @child 的表达能力严格强于 @parent。@parent 仅应用于将子页面添加到不知道其存在的父页面（例如，将自定义 Contour 面板作为子页面添加到不同包中的 Contour 面板页面下）。 :::

如果您正在编写一个页面，并且知道另一个页面将是其父页面，您可以在文件顶部使用 @parent 注释，如下所示：@parent parent-filename。您只需使用 @child 或 @parent 其中之一，无需同时使用。