mkdocs
来源:互联网 发布:java工厂设计模式原理 编辑:程序博客网 时间:2024/05/22 17:32
http://wutongtree.github.io/devops/manage-your-cms-using-mkdocs
http://www.mkdocs.org/
http://markdown-docs-zh.readthedocs.io/zh_CN/latest/
托管文档除了用Jekyll管理你的Github Pages外,https://readthedocs.org/也是使用的非常多,上面托管的文档用Sphinx构建的比较多,文档也是比较复杂的,这里我们介绍一个非常好用的工具:MkDocs。
MkDocs是研究Hyperledger的时候发现的一个工具,使用方法和配置都非常的简单,能够不用太关心建站的事情,能够聚焦到文档本身,看这个文章的长短就知道了。
安装和使用MkDocs
- 安装MkDocs
pip install mkdocs
- 创建文档工程
可以直接用mkdocs的命令:
mkdocs new my-projectcd my-project
生成的目录结构如下:
xxx├── docs│ └── index.md└── mkdocs.yml1 directory, 2 files
mkdocs.yml是配置文件,默认的配置项只有一个site_name:
site_name: My Docs
index.md的内容是一个mkdocs的使用说明:
# Welcome to MkDocsFor full documentation visit [mkdocs.org](http://mkdocs.org).## Commands* `mkdocs new [dir-name]` - Create a new project.* `mkdocs serve` - Start the live-reloading docs server.* `mkdocs build` - Build the documentation site.* `mkdocs help` - Print this help message.## Project layout mkdocs.yml # The configuration file. docs/ index.md # The documentation homepage. ... # Other markdown pages, images and other files.
- 配置MkDocs
直接修改mkdocs.yml就可以,比如:
- site_name:站点的名称 比如我们的是这么设置的:
- pages: 导航页面
- theme: 站点主题
- docs_dir: Markdown文档目录
- site_dir: 生成的静态网页目录
- dev_addr: 本地调试的监听地址和端口
- markdown_extensions: 一些扩展
我们的一个工程是这么设置的:
site_name: 基于Hyperledger的基金管理site_url: https://wutongtree.github.io/funds/theme: simplexsite_description: '基于Hyperledger的基金管理'docs_dir: markdownssite_dir: docspages:- 首页: index.md- 功能描述: requirements.md- 设计实现: designs.md- 安装部署: deploy.mdmarkdown_extensions: - extra - tables - toc - fenced_code - smarty - mdx_math: enable_dollar_delimiter: True - footnotescopyright: Copyright © 2014-2016 <a href="https://wutongtree.com" target="_blank">wutongtree.com</a>
写文章
直接在docs目录下写Markdown文档就可以,也可以创建子目录,方便文档管理。 MkDocs对Markdown文档没有侵入性,完全按照标准的格式写就可以了,不像Jekyll一样需要加一些文件头什么的,文档的链接也可以直接链接原始的Markdown文档,最终生成静态网页的时候会替换成最终的html页面。
本地测试
运行命令:
mkdocs serve
然后打开链接http://127.0.0.1:8000就可以预览了,它会监控本地页面的修改,所以一边改一边就能看到最终的效果了。
生成静态网页
运行命令:
mkdocs build
就会在site目录下看到生成的静态网页了,可以托管到任何一个空间服务商那里了。这个目录也是可以修改的,比如Github Pages用的docs目录,就可以在MkDocs里面改下。
解析没有在pages列表中的页面
官方的版本中,没有在mkdocs.yml配置文件的pages选项中出现过的页面不会转换为静态页面,也不能被其他页面链接。类似这样的错误或者警告:
WARNING - The page "hyperledger/index.md" contained a hyperlink to "hyperledger/chaincode.md" which is not listed in the "pages" configuration.
这其实是他们的设计,因为他们还专门有一个选项strict来说这个事情,如果有这种链接错误的话,要不要终止构建啊 :(
可是有的链接我确实不需要出现在导航栏,直接出现在页面的链接中就好了,否则我增加一个页面就要增加一个导航页面,文章多了就比较麻烦了。
如果你也需要这个功能,可以用我们修改的一个版本:
git clone https://github.com/wutongtree/mkdocs.gitcd mkdocssudo python setup.py install
修改的版本已经给官方提交了pull request,估计是不会通过的 :)
错误
如果发现错误:
Traceback (most recent call last): File "/usr/local/bin/mkdocs", line 11, in <module> sys.exit(cli()) File "/Library/Python/2.7/site-packages/click/core.py", line 716, in __call__ return self.main(*args, **kwargs) File "/Library/Python/2.7/site-packages/click/core.py", line 696, in main rv = self.invoke(ctx) File "/Library/Python/2.7/site-packages/click/core.py", line 1060, in invoke return _process_result(sub_ctx.command.invoke(sub_ctx)) File "/Library/Python/2.7/site-packages/click/core.py", line 889, in invoke return ctx.invoke(self.callback, **ctx.params) File "/Library/Python/2.7/site-packages/click/core.py", line 534, in invoke return callback(*args, **kwargs) File "/Library/Python/2.7/site-packages/mkdocs/__main__.py", line 137, in build_command ), clean_site_dir=clean) File "/Library/Python/2.7/site-packages/mkdocs/commands/build.py", line 289, in build build_pages(config) File "/Library/Python/2.7/site-packages/mkdocs/commands/build.py", line 249, in build_pages dump_json) File "/Library/Python/2.7/site-packages/mkdocs/commands/build.py", line 169, in _build_page site_navigation=site_navigation File "/Library/Python/2.7/site-packages/mkdocs/commands/build.py", line 35, in convert_markdown extension_configs=config['mdx_configs'] File "/Library/Python/2.7/site-packages/mkdocs/utils/__init__.py", line 337, in convert_markdown extension_configs=extension_configs or {} File "/Library/Python/2.7/site-packages/markdown/__init__.py", line 159, in __init__ configs=kwargs.get('extension_configs', {})) File "/Library/Python/2.7/site-packages/markdown/__init__.py", line 185, in registerExtensions ext = self.build_extension(ext, configs.get(ext, {})) File "/Library/Python/2.7/site-packages/markdown/__init__.py", line 264, in build_extension module = importlib.import_module(module_name_old_style) File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/importlib/__init__.py", line 37, in import_module __import__(name)ImportError: Failed loading extension 'mdx_math' from 'mdx_math', 'markdown.extensions.mdx_math' or 'mdx_mdx_math'
安装一下缺的库就可以了:
sudo pip install python-markdown-math
- mkdocs
- mkdocs安装
- 文档发布工具mkdocs
- MkDocs 文档编辑器
- MkDocs 快速入门
- mkdocs 编辑及启动
- MkDocs项目文档生成器(一)
- MkDocs项目文档生成器(二)
- MkDocs 文档生成逻辑浅析
- MkDocs 文档生成逻辑浅析
- 使用MKDocs构建Markdown格式API文档(macOS)
- mkdocs完美支持sequence时序图(亲测可用)
- OS X 系统安装mkdocs后命令无法找到错误解决
- 自动行为操控Steering(四)—到达(单体操控)
- Bayes
- curl 详解
- 八百里加急$数据结构追加2组织权限设计
- sha1加密算法
- mkdocs
- 使用md-http快速搭建博客
- thinkphp5.0框架中图标显示问题
- nodejs express制作后台引入富文本编辑器
- (四)Spring Boot自动配置介绍,以及日志配置
- Java后端WebSocket的Tomcat实现
- 敏捷开发:IT人应该做的创新与变
- 二维数组矩阵转置
- ansible基本使用