mkdocs-techdocs-core-alexef

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

用法

需要Python版本 >= 3.8

$ pip install mkdocs-techdocs-core-alexef

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

site_name: Backstage Docs

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

plugins:
  - techdocs-core

开发

本地运行

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

pip install --editable .

然后您将拥有可用的techdocs-core包，用于Mkdocs，并且pip将把依赖项指向此文件夹。

代码检查

我们使用black作为我们的代码检查器。请在提交pull请求之前运行它对您的代码进行检查。

pip install black
black .

注意： 这将写入src/目录下的所有Python文件，并使用格式化的代码。如果您只想检查它是否通过，只需追加--check标志。

端到端测试依赖项

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

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

./build-e2e-image.sh

此脚本仅在OSX上进行了测试

脚本假设您已经将镜像仓库克隆到与当前仓库同级的目录中（或者您可以指定其位置）。

它将构建一个名为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 Extensions是Python Markdown的扩展集合。所有扩展都位于pymdownx模块命名空间下。

  • 插入符：插入符是围绕^字符构建的扩展。它支持插入上标，并提供了将文本放置在<ins>标签中的简单方法。
  • 批评：批评添加了处理和Critic Markup的支持。
  • 详细信息：详细信息创建可折叠元素，使用<details>和<summary>标签。
  • 表情符号：表情符号通过简单的ASCII表示法添加表情符号，使添加Markdown中的表情符号变得简单 😄。
  • 超级栅栏：超级栅栏类似于Python Markdown的栅栏，但更好。您可以在列表、警告和其他语法下嵌套栅栏。您甚至可以为像UML这样的内容创建特殊的自定义栅栏。
  • 内联高亮：内联高亮突出显示内联代码：from module import function as func。
  • 魔法链接：魔法链接自动将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.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，导致了一些更改
  • 在v9中，一些mkdocs-material功能已被设置为可选。为了保持兼容性，现在它们被硬编码为通过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，该版本支持markdown >=3.3的svg渲染

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 样式的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），因此用pymdownx.highlight替换了codehilite扩展

• 使用pymdownx扩展v.7.1而不是8.0.0，以允许使用legacy_tab_classes配置。这使得技术文档核心插件能够与以下语法一起使用tab进行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