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(?)
  • next:导航到“下一页”。 默认值:78(n)
  • previous:导航到“上一页”。 默认值:80(p)
  • search:显示搜索模式。 默认值:83(s)

readthedocs主题#

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

  • include_homepage_in_sidebar:列出侧栏菜单中的主页。由于MkDocs要求在“nav”配置选项中列出主页,因此此设置允许在侧栏中包含或排除主页。请注意,站点名称/Logo始终链接到主页。默认:True
  • prev_next_buttons_locationbottom, top, bothnone中的一个值。相应地显示“下一步”和“上一步”按钮。 默认值: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)  # 指定文件锚点

设置文档样式#