> For the complete documentation index, see [llms.txt](https://huataihuang.gitbook.io/cloud-atlas-draft/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://huataihuang.gitbook.io/cloud-atlas-draft/develop/doc/mkdocs/using_mkdocs_write_book.md). # 使用MkDocs撰写书籍 我使用[gitbook](https://github.com/huataihuang/cloud-atlas-draft/tree/6f3204fffc11cf006abd394631e2598d98b415c3/develop/doc/gitbook/README/README.md)撰写日常技术笔记已经很久了，但是非常麻烦的是，`gitbook build`非常缓慢并且消耗资源。所以，我撰写[Cloud Atlas](https://github.com/huataihuang/cloud-atlas)改为采用[Sphinx Doc](http://www.sphinx-doc.org/)。 不过，[reStructuredText](http://docutils.sourceforge.net/rst.html)语法比较复杂，日常轻量级的文档撰写比较累，所以我一直想如何更方便地记录个人工作笔记。我发现[MkDocs](https://www.mkdocs.org/)采用了Python作为运行平台，markdown作为撰写语法，并且界面简洁，可能是比较好的的笔记平台。 > 所有的静态网站文档工具，在最初搭建架构时候比较痛苦，但是在逐步完善了体系之后，只需要填充内容，则非常方便易用。需要跨越这个最初比较陡峭的阶段。 ## 安装 > 我已经在[Sphinx](https://github.com/huataihuang/cloud-atlas-draft/tree/6f3204fffc11cf006abd394631e2598d98b415c3/develop/doc/mkdocs/develop/doc/sphinx/README/README.md)采用了[Python3和virtualenv环境](https://github.com/huataihuang/cloud-atlas-draft/tree/6f3204fffc11cf006abd394631e2598d98b415c3/develop/doc/mkdocs/develop/python/startup/install_python_3_and_virtualenv_on_macos/README.md)，所以同样也在Python的virtualenv中安装MkDocs。 ``` pip3 install virtualenv pip3 install --upgrade pip cd ~ virtualenv venv3 . venv3/bin/activate pip install mkdocs ``` * 检查版本 ``` mkdocs --version ``` ## 使用 * 创建项目 ``` mkdocs new my-project cd my-project ``` 在目录下有一个 `mkdocs.yml` 文件，以及 `docs` 目录包含了文档源代码，当前仅在 `docs` 目录下有一个 `index.md` 文件。 MkDocs自带了一个dev-server，可以用于预览文档： ``` mkdocs serve ``` 此时浏览器访问 可以看到文档。并且 dev-server 支持自动重新加载，即对于配置文件中指定的文档目录，任何修改和theme变化都会重新渲染文档。 * 编辑 `docs/index.md` ，修改第一行 `# Welcome to MkDocs` ，例如修改成 `# 我的工作` ，保存立即可以看到首页重新加载刷新。 * 编辑配置文件 `mkdocs.yml` 修改 `site_name` 配置 ### 添加页面 * 添加第二个 `docs/about.md` 内容也是MarkDown： ``` # 说明 ## 目标 整理工作中的技术、管理以及日常 ``` 保存以后，在网站最上方的导航栏就会但看到有两个 ### 文档风格 * 编辑 `mkdocs.yml` 配置，添加 `theme` 设置: ``` site_name: MkLorum nav: - Home: index.md - About: about.md theme: readthedocs ``` 则会看到 ReadTheDocs 风格。 参考 推荐采用 [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) 风格，这是一款遵循了Google [Material Design](https://material.io/design/) 的theme，可以看到及其类似Google官方文档的设计风格。 ``` pip install mkdocs-material ``` 然后修订 `mkdocs.yml` 设置: ``` theme: name: 'material' ``` * 语法高亮使用 [codeHilite](https://python-markdown.github.io/extensions/code_hilite/) 扩展 首先安装 pygments ``` pip install pygments ``` > 搜索功能只支持英文，遗憾 ## 构建网站 如果预览都正常，则可以开始部署，首先build文档: ``` mkdocs build ``` 则生成一个新的目录 `site` ，在增目录下有生成的文档html 如果使用git管理，一般不需要将 `site/` 目录下的html文件也存储到仓库，则配置 `.gitignore` 文件: ``` echo "site/" >> .gitignore ``` 要清理掉 `site` 目录下生成掉网站文件: ``` mkdocs build --clean ``` > 我发现从0开始撰写文档并不容易，因为没有摸到规律。但是，可以模仿网上已经完整体系的mkdocs文档来撰写。例如 [glusterdocs](https://github.com/gluster/glusterdocs) ## 中文搜索 > 目前还没有折腾出来 在mkdocs-material官方issue中有 [Seperate search language and theme language setup #531](https://github.com/squidfunk/mkdocs-material/issues/531) 指出： mkdocs-material是通过 `lunr.js` 来实现搜索的，仅支持日语，但实际上日语的搜索设置也可以用于中文。 [About Chinese search #524](https://github.com/squidfunk/mkdocs-material/issues/524) 提示了支持搜索是修改 `/Library/Python/2.7/site-packages/mkdocs/assets/search/mkdocs/js/lunr.min.js` 我检查了virtualenv环境中， `lib/python3.8/site-packages/mkdocs/contrib/search/lunr-language/` 包含了各种语言搜索，其中就有 `lunr.jp.js` 参考 [基于mkdocs-material实现的帮助中心(markdown + 中文搜索 + 图片放大)](https://segmentfault.com/a/1190000018592279) / [Seperate search language and theme language setup #531](https://github.com/squidfunk/mkdocs-material/issues/531) / [7. 支持中文搜索](https://cyent.github.io/markdown-with-mkdocs-material/appendix/search/) ： * mkdocs-masterial 是支持中文搜索的，但是需要设置为 `jp` : ```yaml extra: search: language: 'jp' ``` * mkdocs是通过 lunr 实现搜索功能，原理是提取页面纯文本内容奥一个json文件爱你，包含锚点位置、标题、描述及标题与描述对应的分词库；把搜索框输入的内容根据分隔符(空格、标点符号等)切分分词，并和第一步的分词库进行对比，根据对应锚点寻址页面。 * 英文版的lunr现在已经支持日文。这种机制是，lunr分词是由分隔符导向，同时对词长有一定限制，类似这种汉字过多的成句，只能保留每段分割的前两个字。所以在搜索的时候，成句（一般是大于俩字）目前是搜索不到的，但可以通过空格切割成句进行搜索。 我发现我的 `mkdocs serve` 启动有一个提示: ``` Ignore: /home/huatai/venv3/lib/python3.8/site-packages/mkdocs/contrib/search/templates/search/lunr.js ``` ## 定制 * 设置logo：图片文件可以存放在 `docs/images` 目录下，图片会自动缩放到合适大小 ``` theme: logo: 'images/logo.svg' ``` 并且可以使用默认的icon: ``` theme: logo: icon: 'cloud' ``` * 多国语言搜索 中文采用 `jp` ，注意只加载需要的语言搜索，否则会占用过多内存 ``` extra: search: language: 'en, jp' ``` ## 插件 ### PDF输出插件 * [MkDocs PDF Export Plugin](https://github.com/zhaoterryy/mkdocs-pdf-export-plugin) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://huataihuang.gitbook.io/cloud-atlas-draft/develop/doc/mkdocs/using_mkdocs_write_book.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.