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


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

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

5. 总结

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