MKdocs配置记录¶
安装material主题¶
安装命令
pip install mkdocs-material
验证安装
安装后，在 mkdocs.yml 配置文件中指定 Material 主题
theme:
name: material
相关插件¶
awesome-pages¶
pip安装
pip install mkdocs-awesome-pages-plugin
在 mkdocs.yml 中启用插件：安装完成后，需要在项目的 mkdocs.yml 配置文件中启用它。在 plugins 部分添加 awesome-pages，通常建议将其放在 search 插件之后
plugins:
- search
- awesome-pages
启用
awesome-pages插件后,请确保mkdocs.yml文件中没有定义nav配置，两者同时存在可能引发冲突。
核心功能：插件安装并启用后，其核心功能通过在各文档目录下创建名为 .pages 的配置文件来实现，用于控制其所在目录及子目录在导航中的标题和排列顺序。
# .pages 文件示例
title: 自定义标题 # (可选) 为此章节设置导航标题，默认为目录名
nav: # (可选) 定义页面和子目录的显示顺序
- 页面或子目录1
- 页面或子目录2
- ... # 特殊符号，用于包含未在列表中指定的项目
blog¶
material主题中内置了blog插件，允许为 MkDocs 添加博客功能。
直接在 mkdocs.yml 中启用插件
plugins:
- blog:
post_dir: blog/posts #指定博客文章存放路径，相对于Docs/
组织方式：Material 内置插件不强制特定的目录结构，只要博文文件都在 posts 目录（或你自定义的目录）下即可，你可以自由地按日期或主题创建子文件夹来管理。
Front Matter：在每篇博文的 Markdown 文件顶部，都需要使用 Front Matter（元数据块）来添加标题、日期等信息
---
title: 我的第一篇文章
date: 2025-11-23
tags:
- 示例标签
categories:
- 测试分类
excerpt: 这是文章摘要
slug: hello-world
author: Walter
links:
- External link: https://cncfstack.com/p/material-for-mkdocs/practices/zh/setup/setting-up-a-blog/#_13
---
这里是文章的开头，作为摘要显示。
<!-- more -->
这里是文章的剩余内容，只有在点击“阅读更多”才会看到。
增强内容与功能
- 摘要分隔符：在博文内容中插入
<!-- more -->，此标记之前的内容会作为摘要显示在博文列表页。 - 分类与标签：在 Front Matter 中使用
categories和tags可以为博文分类打标，插件会自动生成分类和标签索引页。 - 相关链接： 在 Front Matter 中使用
links可以在侧栏展示博文所引用的相关链接。 - 作者信息：Material 内置插件支持通过
.authors.yml文件定义作者信息，并在博文的 Front Matter 中通过authors字段关联。 - 置顶帖子：如果希望将某个帖子固定在索引页面的顶部，以及它所属的归档和分类索引中，可以在front matter中使用
pin属性:pin: true
使用
tags功能需要在mkdocs.yml的插件配置中启用
plugins:
- tags:
其他设置¶
隐藏侧边栏：可以通过在文档的头部（front matter）属性中添加 hide 属性来隐藏导航目录侧边栏。在 Markdown 文件的顶部添加以下行：
---
hide:
- navigation # ← 隐藏左侧sidebar
- toc # ← 隐藏右侧TOC
---
搜索排除：可以通过在页面前置事项（front matter）中添加 search.exclude 属性来将页面从搜索中排除，从而将其从索引中移除。在 Markdown 文件的顶部添加以下行：
---
search:
exclude: true
---
更多设置访问相关链接
定制化¶
项目结构
├── docs
│ ├── blog
│ │ ├── img
│ │ │ └── imgtest
│ │ │ └── 1.jpg
│ │ ├── index.md <--博客首页
│ │ ├── posts <--博客文章文件夹
│ │ │ ├── xxxx.md
│ │ └── tag.md <--标签索引页
│ ├── doc
│ │ ├── xxxx.md
│ ├── index.md <--站点首页
│ └── styles
│ └── extra.css
└── mkdocs.yml
mkdocs.yml
site_name: SeekTHink
site_url: http://note.sth.ink/ #自动生成页面url将引用的域名
site_author: Walter
site_description: 简单实用的文档网站
theme:
name: material
language: zh
features:
- navigation.tabs # 当启用标签页时，顶级部分将在标题下方的菜单层中呈现
- navigation.top # 回到页面顶部按钮
- search.suggest #搜索建议
- search.highlight #搜索高亮
- navigation.instant # 为了在使用即时导航时在网络连接较慢的情况下提供更好的用户体验，可以启用进度指示器，下同
- navigation.instant.progress
#- toc.integrate # (1)! # 页面中右上角的页面导航集成到左侧导航侧边栏
- content.code.copy # md代码块复制
palette:
# ----- 亮色模式 -----
- scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/weather-sunny
name: 切换深色模式
# ----- 暗色模式 -----
- scheme: slate
primary: indigo
accent: indigo
toggle:
icon: material/weather-night
name: 切换亮色模式
# ----- 自定义主题色 -----
- scheme: default
primary: blue
accent: blue
toggle:
icon: material/palette
name: 蓝色主题
- scheme: default
primary: green
accent: green
toggle:
icon: material/palette
name: 绿色主题
- scheme: default
primary: deep purple
accent: deep purple
toggle:
icon: material/palette
name: 紫色主题
- scheme: default
primary: red
accent: red
toggle:
icon: material/palette
name: 红色主题
- scheme: default
primary: grey
accent: grey
toggle:
icon: material/palette
name: 灰色主题
- scheme: default
primary: cyan
accent: cyan
toggle:
icon: material/palette
name: cyan主题
plugins:
- search
- awesome-pages
- tags:
- blog:
post_dir: blog/posts
post_url_format: "{date}/{slug}"
authors_profiles: true
archive: true
markdown_extensions:
- admonition
- codehilite
- footnotes
- toc:
permalink: true
extra_css:
- styles/extra.css
extra:
generator: false #隐藏页脚网站生成器声明
copyright: Copyright © 2022 - 2025 Walter