Mkdocs在html网页上看markdown

时间 2019-11-30

标签 mkdocs html 网页上看 markdown 栏目 HTML 繁體版

原文原文链接

目录html

Mkdocs在html网页上看markdown

Mkdocs在html网页上看markdown

1. 本文目的

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

2. Mkdocs介绍

Mkdocs是什么？一句话归纳以下web

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

具体能够查mkdocs的官网服务器

https://www.mkdocs.org/

其界面以下图所示markdown

也能够查看Mkdocs的配置文档。curl

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的工程ui

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. 总结

对于项目的发布来讲，须要构建文档，因此文档的建设十分的重要。必定要整理好文档，好记性不如烂笔头，只有多作记录和多些总结，才能进步成长。