简介介绍项目文档生成器,生成静态站点,管理MarkDown文档; 官网特点
内建服务器允许我们在编写文档时预览文档。 每当我们保存更改时,其甚至会自动重新加载并刷新我们的浏览器。
通过自定义主题,让我们的项目文档以我们希望的方式查找。
安装(MacOS)
使用初步试用根据官方文档的步骤创建和使用MkDocs 常用命令
mkdocs 指定命令 --help - 查看给定命令上可用的选项列表。 eg.mkdocs new --help - 查看新建工程命令上可用的选项列表。
注* 以上命令除创建新的MkDocs命令外,均须在工程目录下执行。 操作流程1.创建工程 - 花一点时间来回顾一下我们创建的初始项目: 有一个名为mkdocs.yml的配置文件,以及一个名为docs的文件夹,里面是我们文档的源文件。现在,该docs文件夹只包含一个名为index.md的文档页面。 MkDocs附带一个内建服务器,可以让我们在处理文档时预览文档。确保我们与mkdocs.yml配置文件位于同一目录中,然后启用内建服务器: 2.启用内建服务器 - ➜ MkDocs git:(master) ✗ mkdocs serve INFO - Building documentation... WARNING - Config value: 'pages'. Warning: The 'pages' configuration option has been deprecated and will be removed in a future release of MkDocs. Use 'nav' instead. INFO - Cleaning site directory [I 190725 14:56:46 server:292] Serving on http://127.0.0.1:8000[I 190725 14:56:46 handlers:59] Start watching changes [I 190725 14:56:46 handlers:61] Start detecting changes [I 190725 14:56:46 handlers:132] Browser Connected: http://127.0.0.1:8000/[I 190725 14:56:47 handlers:92] Reload 1 waiters: None [I 190725 14:56:47 handlers:132] Browser Connected: http://127.0.0.1:8000/[I 190725 14:56:48 handlers:79] Ignore: /usr/local/Cellar/mkdocs/1.0.4_1/libexec/lib/python3.7/site-packages/mkdocs/contrib/search/templates/search/lunr.js 3.在浏览器中打开我们将看到显示的默认主页: 内建服务支持自动重新加载,只要配置文件、文档目录或主题目录中的任何内容发生更改,都将重建文档。 现在尝试编辑mkdocs.yml配置文件:将site_name值更改为MyMkdocs并保存。 我们的浏览器将自动重新加载,我们应该立即看到更新过的文档 - 新的站点名称生效。 4.添加页面
site_name: My MkDocs pages: - 首页: index.md - 关于: about.md
请注意,搜索结果包括网站上每次出现的搜索字词,并直接链接到搜索字词所在页面的部分。我们无需付出任何努力或配置即可完成所有这些工作! 5.配置主题
site_name: My MkDocs pages: - 主页: index.md - 关于: about.md theme: readthedocs
6.更改favicon图标 默认情况下,MkDocs使用MkDocs favicon图标。 要使用其他图标,须在我们的docs目录下创建img子目录,然后将自定义favicon.ico文件复制到该目录。 MkDocs将自动检测并使用该文件作为我们的的favicon图标。 7.生成站点 - 至此,我们已经准备好部署My MkDocs文档的第一个过程。
mkdocs build
➜ site git:(master) ✗ tree -L 2 . ├── 404.html ├── about │ └── index.html ├── css │ ├── base.css │ ├── bootstrap-custom.min.css │ └── font-awesome.min.css ├── fonts │ ├── fontawesome-webfont.eot │ ├── fontawesome-webfont.svg │ ├── fontawesome-webfont.ttf │ ├── fontawesome-webfont.woff │ ├── fontawesome-webfont.woff2 │ ├── glyphicons-halflings-regular.eot │ ├── glyphicons-halflings-regular.svg │ ├── glyphicons-halflings-regular.ttf │ ├── glyphicons-halflings-regular.woff │ └── glyphicons-halflings-regular.woff2 ├── img │ ├── favicon.ico │ ├── grid.png │ └── index ├── index.html ├── js │ ├── base.js │ ├── bootstrap-3.0.3.min.js │ └── jquery-1.10.2.min.js ├── search │ ├── lunr.js │ ├── main.js │ ├── search_index.json │ └── worker.js ├── sitemap.xml └── sitemap.xml.gz 请注意,我们的源文档已输出为两个名为index.html和about/index.html的HTML文件。 我们还有各种其他媒体已作为文档主题的部分复制到site了目录中。 我们甚至有一个sitemap.xml文件和mkdocs/search_index.json。
echo "site/" >> .gitignore
mkdocs build --clean 8.其它命令和选项
mkdocs --help
mkdocs build --help 9.部署
注*:1. 如果是公司的项目,项目文档不能对外开放,我们可以上传到公司的GitLab上。2. 如果是个人的项目,我们可以上传到GitHub上 注意
MkDocs项目文档生成器(二)前言前面一篇讲了如果搭建自己的MkDocs来管理自己的文档,在搭建完成后既可以使用内设的小型服务器来生成一个静态的站点、又可以将我们的site文件夹直接放到服务器上; eg. 放在本地的Tomcat: apacht-comcat-8.0.36webapps路径下,启用自己的Tomcat,就能够直接访问:http://ipaddress:8080/site/,就会默认打开site目录下的index.html。同理,我们也可以将其放到自己公司的服务器或者托管到GithubPages上; 项目发布到GitHub Pages
编辑
简单的配置页面: pages: - 首页: index.md - 关于: about.md
pages: - 首页: index.md - 用户指南: - 编辑你的文档: user-guide/writing-your-docs.md - 设计你的文档: user-guide/styling-your-docs.md - 关于: - 许可证: about/license.md - 发行说明: about/release-notes.md
docs/ index.md user-guide/getting-started.md user-guide/configuration-options.md license.md getting-started.md这个文档的路径就是user-guide/getting-started.md,默认根目录就是docs 这样的话,就可以在一个文档中链接另外一个文档了,即可以从文档A中打开文档B,见下面的内容。
[如何开始构建文档](user-guide/getting-started.md) 其实最后会被转化成从一个网页打开另外一个网页
mkdocs.yml docs/ CNAME index.md about.md license.md img/ screenshot.png 在MarkDown中写法如下,其实这个就是markdown的标准语法,圆括号中的就是图片的地址,可以是本地的地址,也可以是网络的地址: ![Screenshot](img/screenshot.png)
推荐一个十分不错的MarkDown软件Typora 样式MkDocs包含许多不同的内置的样式和扩展的样式,也可以很容易的实现个性定制
theme: readthedocs 即 theme: 样式的名称
其它几个主题需要安装,因为不会附带,但是安装的时候提示升级,升级的时候提示错误,所以我就忽略了,重点在文档的内容,主题什么的以后再说吧! 配置下面给出部分主要的配置信息: 项目信息
site_name: The Library of Development
配置信息太多了,可以查看中文文档的翻译,然后从官方网站上复制代码 |
|