一次偶然的机回,接触到了mkdocs,被它的分明的层次直接就震住了,又想起来本蒻蒻最好自己总结一个ACM的模板(毕竟自己的能更好的看懂。再加上很强的探(zhuang)索(b)精神,就去谷歌百度各种关于mkdocs的介绍及使用,也是成功的搭好了自己的模板(内容尚未完成。
Demo: Uncle drew’s template

安装mkdocs

安装有很多方式。例如apt-get,dnf,homebrew, yum,chocolatey等。但是我一个都没见过,不过mkdocs也可以使用python(中的pip)安装。
安装mkdocs的命令

pip install mkdocs

运行这一行命令之后等一会,会有安装成功的提示。这里因为我之前已经安装过了,所以安装成功的提示我也截不到图,相信你应该是可以看懂successful的。

建立一个基本的页面

安装好mkdocs之后,我们首先要创立一个自己的项目

mkdocs new my-project(项目名可以自定义)

执行完之后,会显示

INFO    -  Creating project directory: my-project
INFO    -  Writing config file: my-project\mkdocs.yml
INFO    -  Writing initial docs: my-project\docs\index.md

然后我们再去你创建新项目的文件夹中就可以看到

这时候最基础的一个网页你就生成好了,你可以选择

mkdocs serve

这行命令实现本地预览(注意,要去到my-projrct的根目录,即有mkdocs.yml的地方运行这一行命令)。运行成功的话可以看到

INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 190629 07:29:38 server:296] Serving on https://127.0.0.1:8000
[I 190629 07:29:38 handlers:62] Start watching changes
[I 190629 07:29:38 handlers:64] Start detecting changes

然后你就可以去浏览器输入https://127.0.0.1:8000进行本地预览。效果如下

添加新的页面

这里以添加about页面为例。在docs里面新建一个文件’about.md’即可。


以此为例,可以添加你想添加的页面,以markdown的格式编辑即可。

建立网站

如果你想把你的mkdocs搭建的东西托管在github(诸如此类)的地方,接着看下去。
执行这个命令

mkdocs build

成功的话会有提示信息

INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: E:\mkdocs\my-project\site

然后在你的mkdocs根目录中会出现一个新的文件夹’site’,里面的文件大致上是这样的

上传到github

这个跟hexo还不一样,但是你需要github上面存在一个仓库用于存放mkdocs的相关文件。只要把site文件夹里面的文件全部上传到github上的仓库里面,github pages就可以直接使用了。
或者你可以直接使用命令

mkdocs gh-deploy

这个命令我现在还有点懵,推荐大家可以去看看这篇博客: https://blog.keybrl.com/professional/2018-05-19-mkdocs-blog.html
不过我只是用mkdocs做出来一个模板,也不是写个人博客。上传频率不高,手动copy完全可以满足我的需要(要是能弄好自动部署,谁还愿意手动啊,卑微。

主题推荐

第一次看到mkdocs的demo,十分中意它两边的目录,可是自己弄了之后发现不是这样的,后来搜索了一番才知道那是另一个主题——mkdocs-material
安装之后就可以出现很炫酷(个人认为 的双目录了。

我的mkdocs.yml文档

关于一些mkdocs的配置,以及这个主题的配置,可以看看我的yml

site_name: Template
site_author: Uncle_drew
repo_url: https://github.com/Drew233
site_url: https://github.com/Drew233
site_description: My own template.
theme:
  language: 'zh'
  feature:
    tabs: true
  name: 'material'
  palette:
    primary: 'indigo'
    accent: 'indigo'
    font:
    text: 'Ubuntu'
    code: 'Ubuntu Mono'
    include_search_page: false
    search_index_only: true

extra:
  search:
    language: 'zh'
  social:
    - type: 'github'
      link: 'https://github.com/Drew233'


markdown_extensions:
  - admonition
  - codehilite:
      guess_lang: false
  - toc:
      permalink: true

extra_css:
  - '_static/extra.css'


nav:
    - 介绍: index.md
    - 关于: about.md
    - 数学:
        - 素数: math/prime.md
        - 快速幂: math/poww.md
        - 大数: math/bign.md
        - 斐波那契(大数): math/Fibo.md
    - 字符串:
        - 最长回文字串: string/Manacher.md
    - 图论:
        - 最小生成树: Graph/kruskal.md
        - 最短路: Graph/Dijkstra.md
    - 搜索:
        - BFS: search/bfs.md
        - DFS: search/dfs.md
    - 动态规划:
        - 编辑距离: dp/distance.md
        - 最长公共子序列: dp/LS.md
        - 最长递增子序列: dp/LIS.md
        - 最大子段和: dp/Maxsum.md
        - 换零钱(背包): dp/pack.md
    - 几何:
        - 求多边形面积: geometric/s.md

extra_javascript:
  - 'https://cdn.jsdelivr.net/gh/ethantw/Han@3.3.0/dist/han.min.js'
  - '_static/js/extra.js?v=10'
  - 'https://cdnjs.loli.net/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML'


extra_css:
  - 'https://cdn.jsdelivr.net/npm/ah@1.5.0/han.min.css'
  - '_static/css/extra.css?v=11'

# Extensions
markdown_extensions:
  - admonition
  - codehilite:
      guess_lang: false
      linenums: true
  - def_list
  - footnotes
  - meta
  - toc:
      permalink: true
  - pymdownx.arithmatex
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_generator: !!python/name:pymdownx.emoji.to_svg
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.magiclink
  - pymdownx.mark
  - pymdownx.progressbar
  - pymdownx.smartsymbols
  - pymdownx.superfences:
      custom_fences:
        - name: math
          class: arithmatex
          format: !!python/name:pymdownx.arithmatex.fence_mathjax_format
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

不支持中文搜索

另外,mkdocs自带的搜索功能似乎只是支持英文搜索,网上有解决的办法,有兴趣的可以去看下。