MkDocs 安装使用

时间：2020/7/1 9:55:22

环境:

CentOS 7
Python 3.6

参考：

MkDocs#

简介#

MkDocs 是一个基于 MarkDown 的文档构建工具。把一个文件夹下的内容构建成一个以文件夹目录结构为网页菜单结构的静态网页。支持主题配置。不同的主题支持不同的插件。

我的自己的一个配置模板,可以直接使用。但是需要提前安装模板需要的插件。参考: MkDocs 配置模板使用

具体效果:

MkDocs 使用 python 编写。因此需要 python 环境,我把操作系统的python升级到3.6之后进行的安装。在 CentOS 上也可以使用 yum install mkdocs 安装, 但是为了安装最新版本，推荐使用 pip install mkdocs 安装最新版本。我自己安装的是 1.1.2版本 , 安装命令 pip install mkdocs==1.1.2。

使用步骤#

最简使用
1. 安装 mkdocs。
2. 使用 mkdocs new project_name 创建新项目。
3. 使用 mkdocs serve 预览。
扩展：
1. 安装主题，配置主题。
2. 安装插件配置插件。

安装及使用#

安装
```
pip install mkdocs==1.1.2
```
创建项目
```
mkdocs new project_name 
```
启动服务(进入项目目录),之后即可访问 http://127.0.0.1:8000 预览效果.
```
cd project_name
mkdocs serve -a 0.0.0.0:8000
```

构建项目成静态文件

mkdocs build
# 删除已经没有的文件 
mkdocs build --clean

帮助信息
```
mkdocs -help
mkdocs command --help
```

主题#

主题配置,在 mkdocs.yml 文件中加入下面内容。

theme:
    name: material

mkdocs-material #

安装:
```
pip install mkdocs-material
```
配置:
```
theme:
    name: material
```
预览: Material for MkDocs

Material 插件#

修订日期: 基于 git 提交日志生成修订日期。

安装

pip install mkdocs-git-revision-date-localized-plugin

配置

plugins:
    - search # necessary for search to work
    - git-revision-date-localized

目录控制: 控制目录标题，目录文章的顺序，目录是否展示等。

安装

pip install mkdocs-awesome-pages-plugin

配置

plugins:
- search # necessary for search to work
- awesome-pages:
    filename: .pages.yml        # 指定配置文件名，默认文件名是 .pages
    collapse_single_pages: true # 当目录只有一个文件时是否收缩目录
    strict: false               # 当 arrange 配置的文件不存在是是否报错

目录配置模板

# 目录显示的标题
title: Lua 使用

# 目录顺序
arrange:
    - Lua 协程.md
    - ... # 其余的文件
    - Lua 基础语法.md
    - Lua 常用函数库.md

# 是否隐藏
hide: false

# 当目录只有一个文件的时候收缩目录
collapse: true

MkDocs 配置#

可参考配置模板进行配置。

配置模板

# 网站名字
site_name: 蓝田的笔记

# 主题
theme:
    name: material

# 代码高亮
markdown_extensions:
    - codehilite:
        linenums: true
    - toc:
        permalink: true

# 插件配置
plugins:
    - search:
        prebuild_index: true
        lang:
            - en
            - de
            - ru
            - ja
    - git-revision-date-localized:
        type: iso_datetime
    - awesome-pages:
        filename: .pages.yml
        collapse_single_pages: true
        strict: false