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 功能的插件项目。以下是项目的目录结构及其组成部分的介绍：

mkdocs-macros-plugin/
├── .github/              # GitHub 工作流和相关配置
├── .gitignore            # 指定 Git 忽略的文件和目录
├── README.md             # 项目说明文件
├── contributing.md       # 贡献者指南
├── LICENSE.md            # 项目许可证文件
├── MANIFEST.in           # 打包配置文件
├── README.md             # 项目自述文件
├── setup.py              # Python 打包和安装脚本
├── logo.png              # 项目标志文件
├── macros_info.png       # 插件信息图片
├── pyproject.toml        # Python 项目配置文件
└── test_fixture.sh       # 测试固件脚本

• .github/：包含与 GitHub 工作流程相关的文件，例如自动化测试和构建流程。
• .gitignore：定义了哪些文件和目录应该被 Git 忽略。
• README.md：项目的主要说明文件，包含项目描述、安装步骤和使用说明。
• contributing.md：提供有关如何为项目做贡献的指南。
• LICENSE.md：项目的开源许可证信息。
• MANIFEST.in：包含打包项目时需要包含的文件列表。
• setup.py：用于安装 Python 包的脚本。
• pyproject.toml：Python 项目配置文件，可以包含项目的元数据和构建系统信息。
• 其他文件：包括项目图标、插件信息图片等。

2. 项目的启动文件介绍

mkdocs-macros-plugin 项目的启动主要是通过 setup.py 文件来进行安装。以下是 setup.py 文件的主要内容：

from setuptools import setup, find_packages

setup(
    name='mkdocs-macros-plugin',
    version='1.3.7',
    packages=find_packages(),
    include_package_data=True,
    install_requires=[
        'mkdocs>=1.0',
    ],
    entry_points={
        'mkdocs.plugins': [
            'macros = mkdocs_macros.plugin:MkDocsMacrosPlugin',
        ]
    }
)

该文件定义了插件的名字、版本、需要安装的依赖以及如何将插件注册到 MkDocs 中。

3. 项目的配置文件介绍

mkdocs-macros-plugin 项目的配置主要是通过 MkDocs 的配置文件 mkdocs.yml 来进行。以下是 mkdocs.yml 文件的一个示例：

site_name: MkDocs 宏插件示例
plugins:
  - search
  - macros
    on_undefined:
      strict: false

在配置文件中，首先指定了网站的名称 site_name。然后在 plugins 部分，声明了两个插件：search 和 macros。对于 macros 插件，可以设置 on_undefined 选项来定义当遇到未定义变量时的行为。如果设置为 strict: true，则在遇到未定义变量时，页面渲染会失败；如果设置为 strict: false，则会正常显示。

这些配置项使得 mkdocs-macros-plugin 可以正确地集成到 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