MkDocs介绍⚓︎
MkDocs是一个符合google material ui规范的静态文档网站生成器，使用markdown进行文档书写。其功能如下： - python编写的markdown解释器、编译器，带有本地cli工具
自带基于Tornado的小型http服务，用于本地调试
内置一键式发布至GitHub Pages
内置mkdocs风格、readthedocs风格的主题，并支持自定义主题
支持调用python模块实现语法及渲染的扩展
环境及部署⚓︎
测试环境在：python: 3以上，windows系统。（本教程也兼容Linux系统）
安装⚓︎
pip install mkdocs若下载慢，可更换安装源为豆瓣
查看版本⚓︎
mkdocs --version
mkdocs, version 1.2.3 from d:\ProgramData\Anaconda3\envs\py39\lib\site-packages\mkdocs (Python 3.9)或
pip show mkdocs查看帮助⚓︎
mkdocs --help或直接输入 mkdocs, 输出如下：
Usage: mkdocs [OPTIONS] COMMAND [ARGS]...
MkDocs - Project documentation with Markdown.
Options:
-V, --version Show the version and exit.
-q, --quiet Silence warnings
-v, --verbose Enable verbose output
-h, --help Show this message and exit.
Commands:
build Build the MkDocs documentation（构建MkDocs文档）
gh-deploy Deploy your documentation to GitHub Pages （部署到GitHub）
new Create a new MkDocs project （创建一个新的项目）
serve Run the builtin development server (启动一个内置的开发服务)升级⚓︎
pip install -U mkdocs卸载⚓︎
pip uninstall mkdocs快速开始⚓︎
初始化项目⚓︎
# 这里项目名是my-projectmkdocs new my-project在命令行窗口中执行完上面命令后，系统会生成my-project目录，进入该目录里，可以看到默认放置了一些文件。如下：
上图中的docs是内容目录，用于管理文档的源文件以及图片的资源；
上图中mkdocs.yml是配置文件，用于配置页面的目录结构以及主题等。
本地运行和调试⚓︎
通过命令行，进入my-project目录，执行命令 mkdocs serve即可：
cd my-project
mkdocs serve
#mkdocs serve -a 0.0.0.0:8888 可以绑定服务的ip和端口命令执行后，在浏览器中输入网址：http://127.0.0.1:8000/，便可以看到网站内容。
mkdocs serve命令仅为调试使用，不建议在生产环境下使用
修改主题⚓︎
MkDocs自带2个主题：mkdocs（默认）和readthedocs，通过修改mkdocs.yml文件可以实现主题更换。
在mkdocs.yml文件里添加:
theme:
name: readthedocs刷新浏览器，会看到如下页面：
除此之外，还可以为MkDocs添加更多的第三方主题,以及自定义主题。
编译网站⚓︎
在命令行中，进入my-project目录，并执行命令 mkdocs build即可对网站进行编译
#mkdocs build --clean 可以在构建时清理一些残留资源
mkdocs build编译后，系统会在my-project目录下生成site子目录。该目录中的内容就是MkDocs所生成的静态网站。
在生产环境下，可以通过远程桌面或命令行ftp，ssh或scp客户端等工具，将site整个目录传到服务器上。
例如，以scp举例：
mkdocs buildscp -r ./site user@host:/path/to/server/root# 其中“user”替换为登录服务提的用户名，“host”替换为主机的域名（ip）待文件上传完成之后，可以通过Nginx、Tomcat等任意http服务器，将该网站发布出去。实现生产环境的部署。
发布至GitHub pages⚓︎
通过mkdocs gh-deploy自动编译出html并发布至GitHub pages
在github上创建一个repo，名字叫my-project
将repo同步到本地
将mkdocs根目录(my-project)下的所有东西移到本地git目录下 (然后可以将mkdocs根目录删除了)
在本地git目录下执行如下命令，即可实现发布任务：
mkdocs gh-deploy还可以按照https://www.cnblogs.com/frytea/p/13411434.html的方法实现自动构建并上传到github。
错误处理⚓︎
启动时提示字符错误⚓︎
在windows编写makedown文档后，执行mkdocs serve命令后，有时会遇到字符集错误，例如：
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc8 in position 13: invalid continuation byte这种情况，只需要使用UltraEdit等工具将其另存为utf-8解码即可。
端口占用⚓︎
在windows编写makedown文档后，执行mkdocs serve命令后，如果本地已经启动相同端口（默认8000）的服务，则会报错错误，例如：
[WinError 10013] 以一种访问权限不允许的方式做了一个访问套接字的尝试。解决办法：在cmd控制台中，输入如下命令：
#查看端口
netstat -ano|findstr 8000执行后会得到如下输出：
(py39) D:\project>netstat -ano|findstr 8000
TCP 0.0.0.0:8000 0.0.0.0:0 LISTENING 2868
UDP 0.0.0.0:8000 *:* 2868在结果中，LISTENING下面的数字就是监听8000端口的进程。使用taskkill /pid 进程号 /F将其关闭即可。
(py39) D:\project>taskkill /pid 2868 /F
成功: 已终止 PID 为 2868 的进程。再次运行mkdocs serve即可。
