玩转mkdocs

免费 - Sunrise - 3年前 - 浏览量： 0 - 文章来源

mkdocs安装使用

linux下安装mkdocs

$ pip install mkdocs
$ ln -s /usr/local/python3/bin/mkdocs /usr/bin
$ mkdocs --version

windows下安装mkdocs

$ python -m pip install mkdocs
$ python -m mkdocs
$ mkdocs --version

初始化项目

$ mkdocs new documents

项目配置 mkdocs.yaml

site_name: TBlog        # 项目名称
site_description: 这是描述 # 网页描述
site_author: 日出         # 指定作者
site_url: https://www.tengre.cn # 指定域名 - canonical
repo_name: GitHub       # 指定此网站所在的托管平台【github】
repo_url: https://github.com/oksvip/documents   # 此项目的仓库地址
copyright: &copyright 2018-2020 # 网站版权信息（可把网站统计代码放在后面）
theme:
    name: readthedocs       # 指定文档模板
    highlightjs: true       # 开启代码高亮
    hljs_style: github      # 设置高亮样式
    hljs_languages:         # 支持代码高亮语言
        - shell
    shortcuts:              # 定义键盘快捷键（下文有详细描述）
        help: 191    # ?
        next: 78     # n
        previous: 80 # p
        search: 83   # s

nav:                    # 添加页面 注：如nav为空，则软件会按系统默认格式生成docs目录下所有md文件
  - 首页: index.md
  - 关于: about.md

nav:                    # 多级菜单格式
- 首页: 'index.md'
- 用户导航:
    - 'Writing your docs': 'writing-your-docs.md'
    - 'Styling your docs': 'styling-your-docs.md'
- 关于:
    - 'License': 'license.md'
    - 'Release Notes': 'release-notes.md'

快捷键

所有值都是数字键代码。 您可以使用https://keycode.info/来确定给定的键的代码。

• help：显示一个列出键盘快捷键的帮助模式。默认：191（＆quest;）
• next：导航到“下一页”。 默认值：78（n）
• previous：导航到“上一页”。 默认值：80（p）
• search：显示搜索模式。 默认值：83（s）

readthedocs主题

除了默认的[主题配置选项]之外，readthedocs主题还支持以下选项：

• include_homepage_in_sidebar：列出侧栏菜单中的主页。由于MkDocs要求在“nav”配置选项中列出主页，因此此设置允许在侧栏中包含或排除主页。请注意，站点名称/Logo始终链接到主页。默认：True。
• prev_next_buttons_location：bottom, top, both 和 none中的一个值。相应地显示“下一步”和“上一步”按钮。 默认值：bottom。
• navigation_depth：侧栏中导航树的最大深度。 默认值：4。
• collapse_navigation：仅包含当前页面侧栏中的页面部分标题。 默认值：True。
• titles_only：仅包含侧栏中的页面标题，不包括所有页面的所有节标题。 默认值：False。
• sticky_navigation：如果为True，则在滚动页面时使侧边栏与主页面内容一起滚动。 默认值：True。

第三方主题

可以在MkDocscommunity wiki中找到第三方主题列表。 如果您已创建自己的，请随时将其添加到列表中

更改Favicon图标（默认情况下，MkDocs使用MkDocs favicon图标）

要使用不同的图标，请在docs_dir中创建一个img子目录，并将自定义的favicon.ico文件复制到该目录。 MkDocs将自动检测并使用该文件作为你的favicon图标。

开启内置服务器

$ mkdocs serve  # 之后就可以使用127.0.0.1:8000访问网站

编译项目的html文件到site目录下

$ mkdocs build  # 生成html文档，html文件存储在site目录中

清理不需要的html文件

$ mkdocs build --clean  # --clean 清理不需要的html文件

查看有关命令的完整列表

$ mkdocs --help
$ mkdocs build --help  # 要查看给定命令上可用的选项列表，请使用带有该命令的--help标志

部署

 只需要将整个site目录的内容上传到网站根目录即可

编写文档

内部链接【链接到页面】

[证书](license.md)
[证书](../book/license.md)    # 指定其他目录的文件
[证书的名称](license.md#name)  # 指定文件锚点