利用宏和变量释放MkDocs的强大功能
项目描述
利用变量和宏释放MkDocs的强大功能
:open_file_folder: 在Github上被超过2K个仓库使用
🥇 列为 高质量插件
mkdocs-macros-plugin 是一个用于 MkDocs 的通用插件
，它使用 变量 和 宏（函数）来自动化任务，并生成更丰富、更美观的页面。
The unit price of product A is {{ unit_price }} EUR.
Taking the standard discount into account,
the sale price of 50 units is {{ price(unit_price, 50) }} EUR.
在Read the Docs上查看 mkdocs-macro文档。
概述
mkdocs-macros-plugin 是一个插件，使 MkDocs 网站的贡献者更容易创建更丰富、更美观的页面。它将Markdown页面转换为使用 变量、调用 宏 和自定义 过滤器 的 jinja2 模板。
您还可以使用 mkdocs-macros 模块部分替换 MkDocs 插件，以及 pluglets（预安装模块）。
使用变量
您可以通过编写以下内容利用Python在Markdown中的功能，得益于jinja2
The unit price of product A is {{ unit_price }} EUR.
Taking the standard discount into account,
the sale price of 50 units is {{ price(unit_price, 50) }} EUR.
如果您定义了一个 price() 函数，这可以转换为
The unit price of product A is 10.00 EUR.
Taking the standard discount into account,
the sale price of 50 units is 450.00 EUR.
宏的结果可以是 HTML代码：这使得宏特别适用于对Markdown语法进行自定义扩展，例如按钮、电子邮件调用、嵌入YouTube视频等。
可以使用Jinja2模板提供的丰富功能，如条件语句({% if ... %})和循环语句({% for ... %})。
定义变量
常规变量可以通过五种方式定义
| 无 | 有效性 | 面向对象 | 描述 |
|---|---|---|---|
| 1. | 全局 | 网站设计师 | 在mkdocs.yml文件中，在extra标题下 |
| 2. | 全局 | 贡献者 | 在外部yaml定义文件中 |
| 3. | 全局 | 程序员 | 在main.py文件（Python）中，通过将它们添加到字典中 |
| 4. | 局部（页面） | 作者 | 在Markdown页面的YAML标题中 |
| 5. | 局部（页面） | 作者 | 使用{%set variable = value %}语句 |
此外，还提供了预定义对象（局部和全局），通常用于环境、项目、页面、git信息等。
宏和过滤器
同样，程序员可以在main.py文件中以Python函数的形式定义自己的宏和过滤器，用户将能够轻松地在Markdown页面中使用它们，就像使用jinja2指令一样。
安装
先决条件
- Python版本 > 3.7
- MkDocs版本 >= 1.0（兼容1.5以后的版本）
标准安装
pip install mkdocs-macros-plugin
"手动安装"
要安装包，请下载并运行
pip install .
# or...
python setup.py install
开发/测试安装
要安装测试包所需的额外依赖项，请运行
pip install "mkdocs-macros-plugin[test]"
插件声明
在mkdocs.yml文件中声明插件
plugins:
- search
- macros
注意：如果您配置文件中还没有
plugins条目，您还应添加search插件。如果没有设置plugins条目，MkDocs默认启用search；但是如果您使用它，那么您必须显式声明。
默认情况下，未定义的变量将按原样打印到页面上。如果您希望页面在未定义变量时失败，应使用以下配置
plugins:
- search
- macros
on_undefined: strict
有关详细信息和其他选项，请参阅文档。
检查是否工作正常
检查插件是否正常工作的推荐方法是向您的站点（例如info.md）页面添加以下命令之一
{{ macros_info() }}
在终端中，重新启动环境
> mkdocs serve
您将注意到现在终端中出现了附加信息
INFO - Building documentation...
[macros] Macros arguments: {'module_name': 'main', 'include_yaml': [], 'j2_block_start_string': '', 'j2_block_end_string': '', 'j2_variable_start_string': '', 'j2_variable_end_string': ''}
在浏览器中（例如http://127.0.0.1:8000/info），您应该看到插件环境的描述
如果您看到了这些信息，那么您应该已经设置好了。
仔细查看通用列表，因为它为您提供了宏插件可以开箱即用的功能概述。
其他部分提供了更详细的信息。
使用插件
什么是插件？
插件是小型、易于编写的程序，它使用mkdocs-macro的基础设施为mkdocs项目提供服务，这些服务通常由插件提供。
插件是Python包，可以在GitHub上托管，并通过PyPI分发。
如何将插件添加到mkdocs项目中？
安装它
pip install <pluglet_name>
在项目的配置文件（mkdocs.yml）中声明它
plugins:
- search
- macros:
modules:
- <pluglet_name>
如何编写插件？
示例插件可以在mkdocs-test (github)中找到。
现有插件列表
下载文件
下载适合您平台的文件。如果您不确定选择哪个，请了解更多关于安装包的信息。
源分发
构建分发
mkdocs-macros-plugin-1.2.0.tar.gz的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 7603b85cb336d669e29a8a9cc3af8b90767ffdf6021b3e023d5ec2e0a1f927a7 |
|
| MD5 | db8ab5d1cad35a852220ea90ea80d898 |
|
| BLAKE2b-256 | 5acb77eab7e23d058fe84a2584a20ef1202c708c6ff81c5c30171035cc1d8c0b |
mkdocs_macros_plugin-1.2.0-py3-none-any.whl的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 3e442f8f37aa69710a69b5389e6b6cd0f54f4fcaee354aa57a61735ba8f97d27 |
|
| MD5 | 2fd936e6ac9c47549b9baa06cb4eda1a |
|
| BLAKE2b-256 | 9451cdb21d8c31a5c6a4fd1c28aac707c68b4232c34f523ddf1fdd55539ab478 |