Skip to content

Mkdocs 配置

约 452 个字 20 行代码 预计阅读时间 2 分钟

安装

mkdocs 是 python 的一个包，

直接 pip install mkdocs 就可以了

$ mkdocs new blog    # 创建一个名为 blog 的文件夹,存储博客
此时的目录结构

blog/
 ├── docs/            # 存放markdown文档
 │     └── index.md   # 主页
 └── mkdocs.yml       # 配置文件

打开实时渲染服务（默认端口 8000），并且使用 watchdog 监控文件夹内的更改 

mkdocs serve
在浏览器中输入 127.0.0.1:8000 预览，终端键入 ctrl+c 关闭服务器

mkdocs build         # 生成静态网页代码
这时已经生成了site/文件夹，可以将里面的内容部署到网站上了

github pages

在 github 创建远端仓库 <username.github.io> ，其中 username 是你的github用户名，例如我的是 lzcgeorge.github.io，将本地和远端通过 git 工具连接起来。

执行 mkdocs gh-deploy 命令，这个命令将 ..\site 中的文件传送到远端仓库的 gh-pages 分支，这样就实现了 github pages 功能：即用户可以通过 <username.github.io> 来访问了。

配置文件

  • site_name：必填，文档主标题名称
  • site_url：最终的网站 url
  • repo_url：对应的 GitHub repo 的链接，用于 deploy 和右上角的链接
  • edit_url：相对于 repo 链接的 docs 目录地址
  • site_description 站点描述
  • copyright：左下角版权信息
  • theme: 主题样式例如: 
    theme: 
  name: 'material'     # 使用material主题,需要pip安   装mkdocs-material
  language: 'zh'       # 使用中文
  icon:
    logo: ...          # 左上角的 logo 
  custom_dir: ...      # 用于覆盖模板
  feature: 
    ...
  font:                # 字体
    text: ...
    code: ...
  palette:
    ... # 配色方案
  • markdown_extensions：需要添加的 pymarkdown 扩展（包已经随 mkdocs 默认安装），具体各种扩展的用法看官方文档
  • extra：主题需要的其他配置，比如 material 主题的右下角链接 social 和流量分析 analytics 的设置
  • extra_css：附加的 css 文件，可以是 url 也可以是相对于 docs 的相对路径
  • extra_javascript：附加的 js 文件，可以是 url 也可以是相对于 docs 的相对路径。会放到 body 的最后，如果需要放到 head 里需要用覆盖模板的方式
  • plugins：一些插件，比如搜索 search，显示最近修改时间 git-revision-date-localized
  • nav：目录结构

参考

Last update: March 5, 2024
Created: January 7, 2024