Mkdocs在html网页上看markdown

Mkdocs在html网页上看markdown

1. 本文目的

介绍一下目前发布在线文档的时候，如何写出的文档更加的高效简洁，让人赏心悦目的同时，又能学到东西。这就需要利用markdown进行文档的整理，一般来说，如果排版不好看的文档，让人看下去的欲望都没有，更何况涉及到专业领域的知识时，更加没有让人阅读的想法。我想一个人不管技术水平如何，文档一定要整理好，技术水平是能力问题，文档整理是习惯问题。所以坚持写出好文档，这才是我需要思考和不断努力的事情。

2. Mkdocs介绍

Mkdocs是什么？一句话概括如下

MkDocs 是一个用于创建项目文档的快速, 简单 , 完美华丽 的静态站点生成器. 文档源码使用 Markdown 来撰写, 用一个 YAML 文件作为配置文档.

具体可以查mkdocs的官网

https://www.mkdocs.org/

其界面如下图所示

也可以查看Mkdocs的配置文档。

https://markdown-docs-zh.readthedocs.io/zh_CN/latest/

以上介绍的都很详细了，纸上得来终觉浅，绝知此事要恭行。下面来详细介绍一下基本的情况

3. DEMO的演示

3.1 配置需求

安装平台ubuntu16.04

$ python --version

Python 2.7.2

$ pip --version

pip 1.5.2

3.2 安装mkdocs

pip install mkdocs

3.3 新建工程

在这里，我们新建一个mkdocs的工程

mkdocs new my-project

cd my-project

3.4 启动服务器

可以快速开始体验

mkdocs serve

启动服务器自动的地址

如果想自定义一个地址

可以输入下面的地址

mkdocs serve --dev-addr=192.168.31.199:1666

或者

mkdocs serve -a 127.0.0.1:9999

3.5 查看demo

配置完成后，就可以启动了

4. 添加页面

MkDocs 中一个 Markdown 文档渲染后就是一个页面，因此如果我们想添加一个页面，就需要先在 docs 目录下添加一个 Markdown 文件，文件的后缀名可以是 md、markdown 、mdown、 mkdn 、mkd。

4.1 在目录结构中添加一个新的界面

在docs目录中添加test.md文档，并且项目查看的结构

# 查看项目结构

$ tree

.

├── docs

│   ├── index.md

│   └── test.md

└── mkdocs.yml

4.2 修改配置文件mkdocs.yml

site_name: 博客系统

pages:

- 首页: index.md

- 测试: test.md

4.3 添加头部导航栏

curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/development.md

4.4 换主题

theme: mkdocs 默认

theme: readthedocs

下面进行mkdocs主题切换

site_name: 测试博客

page:

- Home: index.md

- Develoment: development.md

- About: about.md

theme: mkdocs

主题分为内置主题、第三方主题和自定义主题，内置主题如上所述，直接配置主题名就可以了；如果是第三方主题，就需要先安装主题再进行配置了；自定义主题有点难度本文暂不介绍。

4.5 生成站点

如果要将项目发布到网站上，则需要生成静态站点

mkdocs build

使用 mkdocs build –clean 可以在构建时清理一些残留资源。
site 需要部署到 webserver 上才能正常运行。

发布的文档可以部署到任意的地方其中GitHub project pages 和Amazon S3 是不错的选择。

5. 总结

对于项目的发布来说，需要构建文档，所以文档的建设十分的重要。一定要整理好文档，好记性不如烂笔头，只有多做记录和多些总结，才能进步成长。