Skip to main content

故障排除 TechDocs

生成时找不到文档​

如果您使用 "开箱即用 "配置设置 TechDocs，其中文档由 TechDocs 后端动态构建，而 TechDocs 文件是从基于 Git 的源代码控制管理系统(如 GitHub、BitBucket 等)中提取的，则可能会出现这种情况。

如果遇到这种情况，请检查 TechDocs 相关文件(如 markdown、assets 或mkdocs.yml文件)与export-ignore属性中的.gitattributes文件。

TechDocs 的后端无法查看此类文件，因此可能会生成部分(或无)TechDocs。

您需要重新考虑如何根据源代码分发 tar 归档(以及如何防止内部文档包含在这些归档中)。 或者，您可以考虑切换到 "推荐 "的 TechDocs 架构(在 CI/CD 中生成和发布文档)。

MkDocs 生成错误​

使用TechDocs CLI请注意，这要求您有可用的 Docker 来启动映像。 首先、git clone然后在目标版本库的根目录下运行

npx @techdocs/cli serve

例如，如果您忘记将 MkDocs 配置文件放到 repo 中，就会出现错误：

npx: installed 278 in 9.089s
[techdocs-preview-bundle] Running local version of Backstage at http://localhost:3000
INFO    -  Building documentation...

Config file '/content/mkdocs.yml' does not exist.

成功后，Backstage和网站的本地副本都将在本地启动：

npx: installed 278 in 9.682s
[techdocs-preview-bundle] Running local version of Backstage at http://localhost:3000
INFO    -  Building documentation...
WARNING -  Config value: 'dev_addr'. Warning: The use of the IP address '0.0.0.0'
  suggests a production environment or the use of a proxy to connect to the MkDocs
  server. However, the MkDocs' server is intended for local development purposes only.
  Please use a third party production-ready server instead.
INFO    -  Cleaning site directory
DEBUG   -  Successfully imported extension module "plantuml_markdown".
DEBUG   -  Successfully loaded extension "plantuml_markdown.PlantUMLMarkdownExtension".
INFO    -  Documentation built in 0.23 seconds
[I 210115 19:00:45 server:335] Serving on http://0.0.0.0:8000
INFO    -  Serving on http://0.0.0.0:8000
[I 210115 19:00:45 handlers:62] Start watching changes
INFO    -  Start watching changes
[I 210115 19:00:45 handlers:64] Start detecting changes
INFO    -  Start detecting changes

使用 svg_object 的 PlantUML 无法渲染​

plantuml-markdownMkDocs 插件可在mkdocs-techdocs-core但 TechDocs 并不支持所有这些格式。

svg_object格式将图表渲染为 HTML<object>标签，但这是不允许的，因为这样会让坏人在文档页面中注入恶意内容。 请参见CVE-2021-32661了解更多详情。

而应使用svg_inline它被渲染成一个<svg>标签，并提供与svg_object.