Publish in-platform custom documentation（发布平台内自定义文档）¶
Each documentation repository is the "source of truth" for the custom docs published from it; each build publishes only the files that are currently in the documentation repository. Any previously-published content originating from the documentation repository will be removed from the in-platform custom documentation site.
Example: Assume you create and publish custom documentation about Product A. Later, you delete the files for Product A from the documentation repository and add new documentation for Product B and Product C. After the next merge and publish, the in-platform custom documentation will contain documentation for Product B and Product C, but will no longer contain documentation for product A.
Custom docs publishing workflow¶
Custom documentation is published when a build runs on the master branch. No other branches will publish in-platform custom documentation. You can see the status of the publishing process in the commit's checks.
An ideal workflow is to create a new branch, write or edit the desired docs content, then open a pull request (PR) on the master branch. Merging a custom docs PR into master triggers a build to publish the documentation.
Note that committing changes into the master branch, in and of itself, will not propagate those changes into the in-platform custom documentation; a build is required.
When will published changes be visible in custom docs?¶
Upon publishing, changes to files that were previously published will appear immediately. Changes that add new documentation pages, remove documentation pages, or modify the overall content structure will appear once the custom documentation service has recompiled its documentation state. By default, this occurs hourly, but the interval can be adjusted by an administrator.
Remove or delete custom documentation¶
Simply deleting a documentation code repository will not remove or unpublish docs from the in-platform custom documentation. To remove or unpublish custom documentation pages, you must delete the unwanted files from the documentation repository and then re-publish the repository. This will unpublish the unwanted docs content.
:::callout{theme="danger"}
Do not delete a published documentation code repository until after you have removed all content from the docs folder and re-published the repository.
:::
When will deleted pages disappear in the in-platform custom documentation?¶
Upon deletion, individual custom docs pages will disappear immediately. The home page entries and table of contents for deleted docs will disappear once the documentation service has recompiled its documentation state internally. By default, this is done every hour, although an administrator may adjust this interval for changes to appear quicker.
中文翻译¶
发布平台内自定义文档¶
每个文档仓库都是从中发布的自定义文档的"唯一真实来源(Source of Truth)"；每次构建仅发布当前文档仓库中的文件。之前从该文档仓库发布的任何内容都将从平台内自定义文档站点中移除。
示例： 假设您创建并发布了关于产品A的自定义文档。之后，您从文档仓库中删除了产品A的文件，并添加了产品B和产品C的新文档。在下一次合并和发布后，平台内自定义文档将包含产品B和产品C的文档，但不再包含产品A的文档。
自定义文档发布工作流¶
当构建在master分支上运行时，自定义文档即被发布。其他分支不会发布平台内自定义文档。您可以在提交的检查(Checks)中查看发布流程的状态。
理想的工作流是创建一个新分支，编写或编辑所需的文档内容，然后在master分支上发起拉取请求(Pull Request, PR)。将自定义文档的PR合并到master分支会触发构建以发布文档。
请注意，将更改提交到master分支本身并不会将这些更改传播到平台内自定义文档中；需要执行构建操作。
已发布的更改何时在自定义文档中可见？¶
发布后，对先前已发布文件的更改将立即生效。添加新文档页面、删除文档页面或修改整体内容结构的更改，将在自定义文档服务重新编译其文档状态后生效。默认情况下，此过程每小时执行一次，但管理员可以调整此间隔。
移除或删除自定义文档¶
仅删除文档代码仓库不会从平台内自定义文档中移除或取消发布文档。要移除或取消发布自定义文档页面，您必须从文档仓库中删除不需要的文件，然后重新发布该仓库。这将取消发布不需要的文档内容。
:::callout{theme="danger"}
在从docs文件夹中删除所有内容并重新发布仓库之前，请勿删除已发布的文档代码仓库。
:::
已删除的页面何时在平台内自定义文档中消失？¶
删除后，单个自定义文档页面将立即消失。已删除文档的主页条目和目录将在文档服务内部重新编译其文档状态后消失。默认情况下，此过程每小时执行一次，但管理员可以调整此间隔以使更改更快显示。