mkdocs 使用记录 ¶

约 556 个字 22 行代码预计阅读时间 2 分钟

Abstract

我最早接触的网站生成器就是 mkdocs，然后用它搭了博客。但由于当时觉得看起来太平淡、功能少等原因抛弃了它换成了 hexo
后来打算搞一个笔记本整理一些有价值的内容，所以搭了这个网站，用回了 mkdocs

mkdocs 就很适合用来做这种站点，而且它基于 python，使用 pymarkdown 渲染 markdown 文档，最后使用 html 模板渲染，也很方便修改。所以 mkdocs 还是很香的

安装 ¶

mkdocs 是 python 的一个包，直接 pip install mkdocs 就可以了

使用 ¶

$ mkdocs new test    # 创建一个名为 test 的文件夹,存储代码
$ cd test

此时的目录结构

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

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

$ mkdocs serve

在浏览器中输入 127.0.0.1:8000 预览，终端键入 Ctrl+C 关闭服务器

$ mkdocs build         # 生成静态网页代码

这时已经生成了site/文件夹，可以将里面的内容部署到网站上了

$ mkdocs gh-deploy

自动根据 mkdocs.yml 中设置的项目地址部署到 GitHub 的 gh-pages 分支中

配置文件 ¶

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：目录结构

本站的配置文档在：https://github.com/TonyCrane/note/blob/master/mkdocs.yml，可供参考

具体的各种用法还是看官方文档比较好，很全面

Reference¶

最后更新: 2022年9月18日 17:07:46
创建日期: 2022年1月10日 16:56:12