MkDocs 宏插件使用教程

MkDocs 宏插件使用教程

mkdocs-macros-plugin Create richer and more beautiful pages in MkDocs, by using variables and calls to macros in the markdown code. 项目地址: https://gitcode.com/gh_mirrors/mk/mkdocs-macros-plugin

1. 项目介绍

mkdocs-macros-plugin 是一个为 MkDocs 文档生成工具设计的通用插件，它通过使用变量和宏（函数）来自动化任务，并生成更丰富、更美观的页面。该插件将 markdown 页面转换为 Jinja2 模板，使用变量、宏和自定义过滤器，使得 MkDocs 网站的贡献者能够轻松地创建出高质量的文档。

2. 项目快速启动

安装

• 确保你的系统中安装了 Python 版本大于 3.7 和 MkDocs 版本大于等于 1.0（兼容 1.5 版本之后）。
• 使用 pip 命令安装插件：

pip install mkdocs-macros-plugin

配置

在 mkdocs.yml 配置文件中声明插件：

plugins:
  - search
  - macros

如果要启用严格模式，当遇到未定义的变量时，页面将不会显示，可以在配置文件中添加：

plugins:
  - search
  - macros
on_undefined:
  strict: true

验证安装

在文档的某个页面（比如 info.md）中添加以下代码：

{{ macros_info() }}

重新启动 MkDocs 服务器，在终端中应该会看到插件的额外信息。在浏览器中访问该页面，应该能看到插件环境的描述信息。

3. 应用案例和最佳实践

使用变量

在 markdown 文档中，可以使用 Jinja2 语法来定义和使用变量：

The unit price of product A is {{ unit_price }} EUR.

在 main.py 文件中定义变量：

def setup Macros:
    env = Environment()
    env.variables['unit_price'] = 10.00

使用宏

宏可以用来创建自定义的 HTML 代码，如嵌入 YouTube 视频等。定义一个宏：

def price(value, units):
    return f"{value * units:.2f}"

在 markdown 文档中调用宏：

Taking the standard discount into account,
the sale price of 50 units is {{ price(unit_price, 50) }} EUR.

使用过滤器

过滤器是简单的函数，用于处理变量的值。例如，可以创建一个过滤器来转换价格：

def to_eur(value):
    return f"{value:.2f} EUR"

在 markdown 文档中使用过滤器：

The total is {{ price(unit_price, 50) | to_eur }}

4. 典型生态项目

mkdocs-macros-plugin 可以与其他 MkDocs 插件和项目配合使用，以增强文档的功能和表现力。以下是一些典型的生态项目：

• MkDocs Material: 一个为 MkDocs 提供 Material Design 风格的主题。
• MkDocs-bootstrapped: 一个基于 Bootstrap 的 MkDocs 主题。
• mkdocs-genner: 一个为 MkDocs 生成文档的自动化工具。

通过这些项目的结合使用，可以让你的 MkDocs 项目更加完善和强大。

mkdocs-macros-plugin Create richer and more beautiful pages in MkDocs, by using variables and calls to macros in the markdown code. 项目地址: https://gitcode.com/gh_mirrors/mk/mkdocs-macros-plugin