如何在MkDocs编写Markdown时实现模板化,自动插入带样式的作者日期头部?
解决方案
完全可以通过Jinja模板实现你的需求,这也是MkDocs场景下处理统一内容模块的标准方案,完全符合你避免重复代码、后续统一迭代格式的要求。
具体实现步骤
- 第一步:抽离公共CSS避免重复加载
你完全不需要在每篇笔记里插入<style>标签,直接把公共样式统一放到全局自定义样式文件中即可:
- 在你的docs目录下新建
css/custom.css文件,写入以下内容:
table, td, th { border:none!important; font-size:15px }
- 在
mkdocs.yml配置文件中添加全局样式引用:
extra_css: - css/custom.css
配置完成后这段样式会在全站所有页面生效,无需再在单篇笔记中重复声明。
- 第二步:安装启用MkDocs宏插件支持Jinja能力
MkDocs官方生态的mkdocs-macros-plugin插件原生支持在Markdown文件中使用Jinja模板语法,安装和配置方式如下:
- 执行安装命令:
pip install mkdocs-macros-plugin - 在
mkdocs.yml中启用插件:
plugins: - macros
- 第三步:编写统一的头部Jinja模板
在docs目录下新建_templates文件夹用于存放公共模板,新建note_header.md模板文件,内容如下:
| | | | -------------- | :-------------------------- | | **Author(s):** | {{ authors | join(', ') }} | | **Date:** | {{ date }} |
- 第四步:用户编写笔记时的使用方式
后续用户写实验记录笔记,仅需要在文件开头的YAML元数据块中声明作者和日期,再引入模板即可,无需手动写表格和样式:
--- authors: - 第一作者 - 第二作者 date: 2024-01-23 --- {% include "_templates/note_header.md" %} <!-- 以下为笔记正文内容 -->
如果需要简化调用步骤,还可以把头部封装为Jinja宏,调用时仅需写{{ note_header(authors, date) }},进一步降低使用成本。
后续如果需要调整头部的格式、增减字段、修改样式,你只需要修改_templates/note_header.md模板文件,所有引用了该模板的笔记会在构建时自动更新,完全不需要逐篇修改每个笔记文件。
内容的提问来源于stack exchange,提问作者tothsa
相关产品推荐
相关产品推荐

