mkdocs-techdocs-core

这是在使用Mkdocs与Spotify的TechDocs时使用的Mkdocs插件的基础。它用Python编写，并将我们所有的Mkdocs默认设置，如主题、插件等，包装在单个插件中。

用法

需要Python版本 >= 3.8

$ pip install mkdocs-techdocs-core

安装了mkdocs-techdocs-core插件后，您需要将其添加到您的mkdocs.yml中。

site_name: Backstage Docs

nav:
  - Home: index.md
  - Developing a Plugin: developing-a-plugin.md

plugins:
  - techdocs-core

(可选) 要使用material主题搜索生成search/search_index.json（负责TechDocs阅读器中的搜索功能），您需要在mkdocs.yml中添加以下配置

plugins:
  - techdocs-core:
      use_material_search: true

开发

本地运行

您可以使用pip和用于开发Python包的--editable标志在本地上安装此包。

pip install --editable .

您将可以使用 techdocs-core 包在 Mkdocs 中，并且 pip 将将依赖项指向此文件夹。

代码风格检查

我们使用 black 作为我们的代码风格检查工具。请在提交拉取请求之前运行它对您的代码进行检查。

pip install black
black .

注意： 这将把格式化后的代码写入 src/ 目录下的所有 Python 文件。如果您只想检查是否通过，请简单地在命令中添加 --check 标志。

端到端测试依赖项

如果您对插件本身进行了更改，或者更新了依赖项，强烈建议您测试该插件。

要在本存储库中构建带有您更改的 spotify/techdocs Docker 镜像版本，请在此存储库中运行以下脚本

./build-e2e-image.sh

该脚本仅在 MacOS 上进行了测试

该脚本假设您已将 镜像仓库 克隆在本存储库的兄弟目录中（或者您也可以指定其位置）。

它将构建一个名为 mkdocs:local-dev 的镜像，包括您在本地上所做的更改。要在 backstage 中测试此镜像，请使用以下内容编辑配置（例如 app-config.yaml）

techdocs:
  generator:
    runIn: "docker"
    dockerImage: "mkdocs:local-dev"
    pullImage: false

发布

1. 更新 变更日志。
2. 在 setup.py 中增加版本号，这将在 GitHub Actions 上触发发布工作流程，以在 PyPI 上发布新版本。

MkDocs 插件和扩展

TechDocs Core MkDocs 插件附带一套 mkdocs 支持的扩展和插件。以下列出了 TechDocs Core 插件中包含的所有扩展和插件

插件:

• 搜索：MkDocs 默认提供搜索插件，它使用 lunr.js 作为搜索引擎。
• mkdocs-monorepo-plugin：此插件允许您在一个 MkDocs 项目中构建多套文档。它旨在解决在 Spotify 最大的和最关键的代码库中编写文档的问题（通常是单体或单一代码库）。

扩展:

• 警告：警告（也称为呼叫）是包含侧边内容而不显著打断文档流的绝佳选择。Material for MkDocs 提供了多种不同的警告类型，并允许包含和嵌套任意内容。

• 目录：目录扩展从 Markdown 文档生成目录并将其添加到生成的 HTML 文档中。此扩展包含在标准的 Markdown 库中。

• pymdown：PyMdown 扩展是 Python Markdown 的扩展集合。所有扩展都位于 pymdownx 模块命名空间下。

  • 插入符：插入符是一个围绕 ^ 字符构建的扩展。它添加了对插入上标的支持，并提供了将文本放在 <ins> 标签中的简便方法。
  • 批评：批评添加了对 Critic 标记的支持。
  • 详细内容：详细内容创建带有 <details> 和 <summary> 标签的可折叠元素。
  • 表情符号：表情符号通过 Markdown 简单地添加表情符号 😄。
  • 超级围栏：超级围栏类似于 Python Markdown 的围栏，但更好。可以在列表、警告和其它语法下嵌套围栏。您甚至可以为像 UML 这样的内容创建特殊的自定义围栏。
  • 行内高亮：行内高亮突出显示行内代码：from module import function as func。
  • 魔法链接：MagicLink 自动将 URL 和电子邮件链接链接起来，无需使用 Markdown 语法进行包装。它还可以自动缩短流行的代码托管提供商的存储库问题、拉取请求和提交链接。您甚至可以使用特殊的简写语法来链接到问题、差异甚至提及人员。
  • 标记：标记功能让您轻松标记单词。
  • 智能符号：智能符号通过简单的ASCII表示法插入常用Unicode字符：= /= → ≠。
  • 高亮显示：高亮显示允许您配置SuperFences和InlineHilite的语法高亮。同时，通过语法高亮器通过标准Markdown缩进代码块。
  • 额外功能：额外功能类似于Python Markdown的Extra包，但它使用PyMdown Extensions来替代类似的扩展。
  • 标签页：标签页允许使用标签页Markdown内容。
  • 任务列表：任务列表允许插入带有复选框的列表。
  • 波浪号：波浪号是在 ~ 字符周围构建的语法。它增加了插入下标的支持，并提供了一种将文本放置在 <del> 标签中的简单方法。

• markdown_inline_graphviz：一个Python Markdown扩展，将内联Graphviz定义替换为内联SVG或PNG。使用以下使用说明激活inline_graphviz扩展。

• plantuml_markdown：此插件实现了一个块扩展，可以用来指定一个PlantUML图表，该图表将被转换为图像并插入到文档中。

  • 注意，svg_object格式不支持用于渲染图表。更多内容请参阅TechDocs故障排除部分。

• mdx_truly_sane_lists：一个Python-Markdown扩展，使列表真正合理。功能包括嵌套列表的自定义缩进和对列表之间混乱的换行和段落进行修复。

其他插件和扩展

注意，上述插件和扩展列表是一个有观点的列表，提供了一组核心功能，对于大多数技术文档需求是必要的（因此：techdocs-core）。欢迎提交引入新插件或扩展的PR，但它们不一定会被接受。

为了解决您组织的具体需求，我们鼓励您在techdocs-core（无论是TechDocs后端容器还是自定义TechDocs构建容器）之上安装任何必要的扩展/插件。

注意事项

主题

我们仅使用material-mkdocs作为基础样式，因为Backstage也使用客户端的Material UI。我们不期望人们使用除Material UI之外的任何主题来维护所有Backstage页面的一致性（换句话说，文档页面与其他Backstage页面具有相同的外观和感觉），因此我们使用前端应用程序中配置的BackstageTheme作为所有应用程序设计令牌（如颜色、字体等）的真相来源。因此，您可以查看，一些样式总是会根据mkdocs-material插件主题设置被覆盖，这可能导致在mkdocs.yaml文件中覆盖主题设置的用户出现意外行为。

变更日志

1.4.2

• 修复了当扩展包含在pymdownx.extra中时忽略单个扩展配置的问题。请参阅#147

1.4.1

• 引入了mkdocs-redirects插件（v1.2.1）。

1.4.0

• 将最小mkdocs依赖项从1.5更新到1.6。
  • 修复了#187问题。
• 将mkdocs-material提升到9.5.27。

1.3.6

• 将mkdocs-material提升到9.5.26。

1.3.5

• 将mkdocs-material提升到9.5.13，增加了对卡片网格和网格布局的支持。

1.3.3

• 将mkdocs-material提升到9.4.14，增加了对：Mermaid.js版本10.6.1、emoji扩展和对MkDocs进行更新到1.5.3的支持。
• 为Python版本3.11添加了测试。

1.3.2

• 将pymdown-extensions更新到10.3.1，增加了对material.extensions的支持
• 移除了对Python版本3.7的支持

1.3.1

• 将pygments更新到2.17.2，增加了对JSX的支持。

1.3

• 将mkdocs-material（及其依赖项）从9.1.3升级到9.2.7，导致了一些变化
  • MkDocs的依赖现在是1.5
• theme.palette现在硬编码为{}而不是""，这导致了一些Material插件的某些问题

1.2.3

• 将pygments更新到2.16.1，修复了漏洞。
• 更新依赖项plantuml-markdown到3.9.2。

1.2.2

• 为安全添加了pymdownx.snippets的配置覆盖。 restrict_base_path始终为true。如果您当前使用目录之外的文件片段，这些文件将不再包含在内。

1.2.1

• 使用最新版本的pymdown-extensions，其中包含安全修复。

1.2.0

• 将mkdocs-material（及其依赖项）从8.1.11更新到9.1.3，导致了一些变化
  • 一些mkdocs-material功能在v9中变为可选。为了保持兼容性，现在它们被硬编码为由mkdocs-techdocs-core启用。这些功能包括
    • navigation.footer
    • content.action.edit
  • theme.palette现在硬编码为""以保留之前的行为。如果不硬编码调色板，它将获得default的值，这会导致不希望的视觉变化。
  • 一些组件（例如admonitions）的外观略有不同。
  • 一些微小的颜色变化可以通过更新到最新版本的@backstage/plugin-techdocs来避免，该版本可以补偿这些变化。

1.1.7

• 将mkdocs-monorepo-plugin更新到1.0.4，其中包括对mkdocs版本1.4.0及更高版本的兼容性修复。

1.1.6

• 移除了对pyparsing和Jinja2依赖项的固定版本，这些依赖项不再需要。
• 将mkdocs-monorepo-plugin和markdown_inline_graphviz_extension固定到特定的（最新）版本，以提高稳定性。从现在起，这些（以及所有其他与功能相关的依赖项）将定期更新，任何变化都将反映在此更改日志中。

1.1.5

• 添加了对Python 3.10的支持#73
• 解决了在1.1.4中引入的运行时错误，该错误在某些情况下阻止了网站的建设。

1.1.4

• 支持markdown版本>3.2,<4
• 使用markdown_inline_graphviz_extension 1.1.1，该版本支持svg渲染markdown >=3.3

1.1.3

• 将plantuml-markdown升级到3.5.1，删除了uuid作为依赖项。

1.1.2

• 简化主题代码，只更新backstage必要的属性。

1.1.1

• 修复运行时AttributeError: 'Theme' object has no attribute 'copy'错误。

1.1.0

• 添加了覆盖mkdocs主题属性的新功能

注意：请参阅readme中的注意事项部分，关于Backstage主题的考虑

1.0.2

• 将pymdown-extensions更新到9.3并启用pygments_lang_class以允许在TechDocs Addons中通过语言轻松定位代码块。

1.0.1

Jinja2固定到v3.0.3。

1.0.0

• 本包已升级到v1.0！

注意：从现在起，此包将遵循semver约定。

0.2.3

• 升级mkdocs-material及其依赖项

0.2.2

• 将plantuml-markdown的版本更新到3.5.0以支持图像映射

0.2.1

• 由于Python依赖项的更改，修复了运行时module 'pyparsing' has no attribute 'downcaseTokens'错误。
• 更新到最新的mkdocs-monorepo-plugin，允许在monorepos中使用.yaml文件扩展名和非slug-like的site_name。

0.2.0

• 添加mdx_truly_sane_lists以处理mkdocs与commonmark/gf markdown之间的非常讨厌的列表差异。请参阅https://github.com/backstage/backstage/issues/6057#issuecomment-862822002

0.1.2

• 修复Markdown的依赖版本，以确保GraphViz SVG渲染正常工作。

0.1.1

• 确保所需的mkdocs-monorepo-plugin与Mkdocs 1.2.x兼容。

0.1.0

• 提高了与其他mkdocs插件的依赖兼容性。
• 将mkdocs最低版本升级到1.2.2

0.0.16

• 在setup.py的install_requires中复用requirements.txt文件中的数据。#24

0.0.15

• 升级monorepo以跟踪最新的补丁，包括各种错误修复。#22

0.0.14

• 将plantuml-markdown升级到3.4.2，支持外部文件源。#18

0.0.13

• 修复了整个临时目录可能包含在构建站点输出中的问题。#7

0.0.12

• 更新主仓库到新的https://github.com/backstage/mkdocs-techdocs-core

0.0.11

• 来自mkdocs.yml的任何MkDocs插件配置现在将正常工作并覆盖默认配置。请参阅https://github.com/backstage/backstage/issues/3017

0.0.10

• 将Markdown版本锁定以修复与Graphviz相关的问题

0.0.9

• 将开发状态更改为3 - Alpha

0.0.8

• Superfences和Codehilite结合使用时效果不佳（squidfunk/mkdocs-material#1604），因此将codehilite扩展替换为pymdownx.highlight

• 使用pymdownx扩展v.7.1而不是8.0.0，以允许legacy_tab_classes配置。这使得techdocs核心插件与以下语法使用的分组markdown兼容

    ```java tab="java 2"
        public void function() {
            ....
        }
    ```

以及新的

    === "Java"

    ```java
    public void function() {
        ....
    }
    ```

在不久的将来，pymdownx扩展也将升级到8.0.0。

• 添加了pymdownx.tabbed以支持使用tab分组markdown内容，例如代码块。

• "PyMdown Extensions包括三个扩展，旨在替换默认Python Markdown扩展中的对应扩展。" 因此，一些默认从pymdownx.extra添加的扩展在这个版本中被移除（https://facelessuser.github.io/pymdown-extensions/usage_notes/#incompatible-extensions）

0.0.7

• 修复了emoji支持配置问题

0.0.6

• 进一步调整版本以找到兼容版本

0.0.5

• 降低某些markdown扩展的版本到更稳定的版本

0.0.4

• 添加了对更多mkdocs扩展的支持
  • mkdocs-material
  • mkdocs-monorepo-plugin
  • plantuml-markdown
  • markdown_inline_graphviz_extension
  • pygments
  • pymdown-extensions

许可证

版权所有 © 2020-2023 Backstage作者。保留所有权利。Linux基金会注册了商标并使用商标。有关Linux基金会的商标列表，请参阅我们的商标使用页面：https://www.linuxfoundation.org/trademark-usage

根据Apache许可证第2版授权：https://apache.ac.cn/licenses/LICENSE-2.0