3.配置MkDocs
最小配置
MkDocs项目只有一个配置文件，使用yml格式。配置文件的作用是修改网站样式、启用功能、启用插件。MkDocs的大部分功能是关闭的，需要用户在配置文件中开启。
site_name: 你的网站标题
示例配置
以下是一个 mkdocs.yml 配置文件的示例，包含常用的 Markdown 语法拓展，并附有注释说明各部分的功能：
theme: icon: logo: material/home name: material language: zh palette: # 切换到亮色 - media: "(prefers-color-scheme: light)" # 根据系统的颜色模式自动切换 scheme: default # primary: pink # accent: pink toggle: icon: material/weather-night name: 切换到暗色模式# 切换到暗色 - media: "(prefers-color-scheme: dark)" scheme: slate # primary: pink # accent: pink toggle: icon: material/weather-sunny name: 切换到亮色模式 features: - navigation.instant # 现在页面不会跳转,而是类似单页应用,搜索和各种跳转都是在当前页面完成,对美观有很大帮助 - navigation.tabs # 页面上方的标签页 - navigation.tracking # 页面滚动时，导航栏高亮当前页面 - navigation.sections # 使导航栏分块 - navigation.expand # 默认展开导航 - navigation.prune # 只渲染当前页面的导航 - toc.follow # 滚动的时候侧边栏自动跟随 - navigation.top # 返回顶部按钮 - search.suggest # 补全建议 - search.highlight # 搜索结果高亮 - search.share # 搜索结果分享 - navigation.footer # 页脚提示下一章 - content.code.copy # 代码段上的赋值按钮markdown_extensions:
- pymdownx.highlight: # 代码高亮
anchor_linenums: true
- admonition # 警告语法
- def_list
- footnotes
- abbr
- pymdownx.caret
- pymdownx.mark
- pymdownx.tilde
- md_in_html
- pymdownx.arithmatex: # latex支持
generic: true
- toc:
permalink: true # 固定标题位置为当前位置
toc_depth: 3 # 目录深度
- pymdownx.highlight: # 代码块高亮
anchor_linenums: true
linenums: true # 显示行号
use_pygments: true # 代码高亮
pygments_lang_class: true
auto_title: true # 显示编程语言名称
linenums_style: pymdownx-inline # 行号样式,防止复制的时候复制行号
- pymdownx.betterem # 强调美化,比如text会被美化
- pymdownx.caret # 上标和下标
- pymdownx.mark # 上标和下标
- pymdownx.tilde # 上标和下标
- pymdownx.keys # 显示按键组合
- pymdownx.critic
- pymdownx.details # 可以折叠的代码块 ??? note 可以让警告变成折叠的
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
- pymdownx.magiclink # 自动识别链接
- pymdownx.smartsymbols # 智能符号
- pymdownx.snippets # 代码段
- pymdownx.tasklist:
custom_checkbox: true # 自定义复选框
- attr_list
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
- pymdownx.superfences: # 代码块中支持Mermaid
custom_fences: # 支持 Mermaid
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
alternate_style: true
combine_header_slug: true
- pymdownx.tasklist:
custom_checkbox: true
clickable_checkbox: true
- meta # 支持Markdown文件上方自定义标题标签等
- tablessite_name: 灵魂io的笔记 # 设置网站标题
copyright: Copyright © 灵魂io # 左下角的版权声明
site_description: "一个使用 MkDocs 构建的笔记网站"手动导航，使用后自动导航将失效
nav:
- Home: index.md
- 教程: tutorials.md
- guides: how-to-guides.md
- 更多:
- 更多/中文.md
- 接口文档:
- interface/1.md
plugins:
- mkdocstrings:
handlers:
python:
paths: [src]
- search # 搜索插件
# - offline # 离线本地搜索，和navigation.instant不能同时启用extra:
# generator: false #删除页脚显示“使用 MkDocs 材料制造”
social:
- icon: fontawesome/brands/github
link: soul-io.github.io
name: GitHub
- icon: fontawesome/brands/bilibili
link: https://space.bilibili.com/294675129
name: Bilibili
- icon: material/email
link: soulio:<xxx@qq.com>
name: Email
在 博客园 BEMAKE 的配置 上修改
配置说明：
- 网站基本信息：定义网站名称、描述和作者。
- 主题配置：指定使用
material 主题。 - 导航栏配置：定义文档的导航结构。
- 插件：启用和配置各种插件，以增强文档功能。使用前需要安装插件，参考附录
- Markdown 拓展：启用和配置常用的 Markdown 语法拓展，增强文档的编写和显示效果。
- 额外配置选项：例如社交链接，可以根据需要添加其他自定义选项。
通过这个 mkdocs.yml 配置文件，你可以轻松启用常用的 Markdown 语法拓展和插件，使你的文档网站功能更加丰富和易于使用。
