最小配置

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文件上方自定义标题标签等

- tables




site_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


    # 切换到暗色
    - media: &quot;(prefers-color-scheme: dark)&quot;
      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 # 代码段上的赋值按钮

在 博客园 BEMAKE 的配置 上修改

配置说明：

• 网站基本信息：定义网站名称、描述和作者。
• 主题配置：指定使用 material​ 主题。
• 导航栏配置：定义文档的导航结构。
• 插件：启用和配置各种插件，以增强文档功能。使用前需要安装插件，参考附录
• Markdown 拓展：启用和配置常用的 Markdown 语法拓展，增强文档的编写和显示效果。
• 额外配置选项：例如社交链接，可以根据需要添加其他自定义选项。

通过这个 mkdocs.yml​ 配置文件，你可以轻松启用常用的 Markdown 语法拓展和插件，使你的文档网站功能更加丰富和易于使用。

‍