使用宏和变量释放mkdocs的威力
useurmind-mkdocs-macros-plugin的Python项目详细描述
mkdocs宏插件：通过变量和宏释放mkdocs的威力
- mkdocs宏插件：用变量和宏释放mkdocs的力量
- 概述
- 上下文和目的
- 灵感来源
- 用例：克服降价语法的内在限制
- 解决方案1：降价扩展
- 解决方案2：自定义HTML代码
- 解决方案3：输入宏
- 安装
- 如何使用它
- 在配置文件中定义变量
- 在降价页面中定义变量
- 在python代码中定义变量和宏rel="nofollow">在python代码中定义变量和宏
- 模块的位置
- 模块内容
概述
这是mkdocs宏插件的一个分支，位于fralau/mkdocs_macros_plugin 对于mkdocs版本1.0.2的更改。将在mkdocs宏插件修复后立即删除。
mkdocs宏插件是一个使贡献者更容易使用的插件 到amkdocs网站，使内容更丰富、更漂亮 页面，通过在降价代码中使用变量和调用宏来实现。
常规变量可以通过三种方式定义：
- 全局（对于贡献者）：在
mkdocs.yml文件中， 在"额外"标题下 - 全局（对于程序员）：在
main.py文件（python）中， 将它们添加到字典中 - 本地（供贡献者）：在标记文件中，使用
{%set variable=value%}声明 < > > - python版本>；3.7.0
- mkdocs版本>；1.0.2
变量：包含变量的字典。宏：可以用来声明python的decorator函数 作为jinja2可调用的函数（mkdocs的"宏"。
类似地，程序员可以在main.py文件中将宏定义为python函数，这样用户就可以
在python代码中使用起来没有太多困难。
使用这两个工具，您可以编写例如：
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.
可以翻译成：
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代码： 这使得宏特别有用 对标记的语法进行自定义扩展。
实际上，可以使用 jinja2模板
背景和目的
灵感来源
mkdocs标记额外数据（rosscdh）
在我看到这个优秀的插件之后，我想到了这个扩展。
＜HREF"https://github.com/rosscdh/mkdocs-markdownextrada-plugin" rel="nofollow">rosscdh创建的mkdocs markdownextradata，它接受元数据数据
从mkdocs.yml文件，并允许您插入它们
带双花括号：
The price of the item is {{price}}.
他使用jinja2的概念 用于此目的的模板引擎简单而漂亮： 这个插件只需要几行代码。
jinja2:变量也可以是python可调用的
然后我发现Jinja2的创造者， 以他们的智慧（也要感谢他们！）， 决定支持任何类型的python变量， 包括可调用函数，通常是函数，例如：
The price of the item is {{calculate(2, 7.4)}}.
他们觉得不值得多说几句话， 但这是一颗显而易见的钻石。
哦是吗？让我们在mkdocs的降价页面中也支持它们！
wiki引擎中的宏
< Buff行情>使用"宏"加速网页编写过程的想法 实际上是相当古老的
大多数wiki引擎， 它们还依赖于一些标记 语言，在丰富页面展示方面也有同样的问题， 在2000年初。 作为回应，它们通常以某种形式实现宏 （在mediawiki中，它们被混淆地称为模板。 在许多情况下，这些wiki引擎依赖于双大括号语法。
毕竟，静态网站生成器可以定义为 在线编辑功能已被删除，使之成为"维基维基"！
用例：克服标记语法的内在限制
mkdocs是一个强大而简单的 生成网站的工具。页面基于标记，这在设计上很简单。缺点是降价的表现力是 必须有限。
如果你想用按钮等新功能丰富你的网络，你该怎么办？ 没有弄乱模板的花哨图片等？
解决方案1：降价扩展
为了用它表达更多的东西，标准的追索权是
按标准降价
降价扩展。
添加扩展很简单，因为
可以通过mkdocs.yml配置文件直接激活
例如：
markdown_extensions:-footnotes
（如果它们是非标准的，您只需先在 机器。）
但问题是，总会有一些特定的东西 您需要这样做，但没有可用的降价扩展名。 否则扩展会太复杂，或者不完全符合您的要求。
此外，这些都是对可能的扩展数量的限制， 因为扩展标记的语法总是有点棘手 会造成与标准语法或其他扩展不兼容。
解决方案2：自定义HTML代码
如果没有延期，标准追索权 就是在你的降价中写一些纯html， 也可能包含一些 css代码（特别是如果您使用的css 特定于您的主题或网站），例如：
Here is my code: <aclass='button'href="http:your.website.com/page">Try this</a>
HTML和CSS的结合很好，可以解决很多问题。
但如果你不得不打字的话，很快就会变得乏味 同样的代码一次又一次的变化； 如果你想改变一些东西 调用（通常是css类），然后必须手动更改 该代码的所有实例，以及所有相关风险。 此解决方案不可缩放。
解决方案3：输入宏
如果有一个宏让你写信 上面的html为：
{{button('Try this', 'http:your.website.com/page')}}
那个调用被转换成了正确的html？
这是你可以教给一个 已经记下了，不需要他们参与 在任何css或html中！
更重要的是， 作为程序员，你可以用python轻松地编写自己的新宏， 你什么时候需要？
一个宏简单地说，是一个python函数需要几个参数 并返回一个字符串。它可以包含你想要的所有逻辑；它可以 像上面的例子一样简单，或者像从 一个数据库，并将结果格式化为降价。
由于mkdocs宏插件，所有这些都成为可能！
安装
先决条件
仅使用
程序
要安装软件包，请执行：
pip install mkdocs-macros-plugin
在文件 注意：如果您的配置文件中还没有 要方便快速地定义自定义变量，请在 在您的降价文件中： 如果需要标记页本地的变量，可以使用标准
Jinja2声明，例如： 事实上，你可以
所有您想要的Jinja2的花哨步法！
只需记住，您不需要定义任何页眉、页脚或导航，
因为这已经由mkdocs处理。 python代码必须进入主网站目录中的 in也可以是一个包（即a 如果愿意，可以通过添加
作为第一步，您需要声明一个钩子函数
调用了declare_variables，有两个参数： 示例应该是不言而喻的： 为mkdocs注册变量或宏
应该在里面做
钩子功能。另一方面，没有什么能阻止你进口
此函数外部的声明。 注意：您可以导出范围广泛的对象及其属性
保持可访问状态（请参见更多信息） 欢迎加入QQ群-->： 979659372
mkdocs.yml中声明插件
plugins:-search-macros
< Buff行情>插件条目，
您还应该添加搜索插件。
如果设置了nopluginsentry，mkdocs默认启用search；但是
如果您使用它，则必须明确声明。如何使用
在配置文件中定义变量
mkdocs.yml中声明它们
文件：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.
0
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.
1
在降价页面中定义变量
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.
2
< Buff行情>在python代码中定义变量和宏
模块的位置
main.py文件
（在mkdocs.yml文件旁边）。main目录）。
只要声明变量函数是可访问的。python_模块的参数
（无需添加.py后缀）：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.
3
模块内容
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.
4
推荐PyPI第三方库
