Mkdocs 使用文档

开始

创建一个新项目

$ mkdocs new my-project
$ cd my-project

一个配置文件 mkdocs.yml, 和一个包含文档源码的 docs 文件夹. 在 docs 文件夹里包含了一个名为 index.md 的文档.

MkDocs 包含了一个内建的服务器以预览当前文档. 控制台切换当前目录到 mkdocs.yml 配置文件相同文件夹, 输入 mkdocs serve 命令以启动内建服务器:

$ mkdocs serve
Running at: http://127.0.0.1:8000/

在浏览器中打开 http://127.0.0.1:8000/ , 可预览。

内建服务器支持在配置文件,文档目录或主题发生改变时自动载入并重新生成文档。

更改网站标题

编辑 medics.yml 修改 site_name 值即可。

网页标题

编辑 doc/index.md 文档，将默认标题改为 MkLorum，刷新浏览器即可看到网页标题变化

添加页面

$ touch docs/about.md

主配置文件

site_name: MkLorum
pages:
- [index.md, Home]      #添加 Home 导航栏
- [about.md, About]     #添加 About 导航栏
theme: readthedocs      #配置主题为 readthedocs

站点生成

$ mkdocs build                  #生成网页静态文件
$ ls site                               #浏览生成的网站目录内容
$ mkdocs build --clean  #清除site目录里已删除文档的静态内容

发布

只需上传 site 目录到需要发布的位置。

撰写文档

如何撰写 markdown 源码并安排目录结构.

目录结构

mkdocs.yml
docs/
        index.md/.markdown/.mdown/.mkdn/.mkd        #支持后缀名形式
        about.md
        license.md
        user-guide/getting-started.md           #多级目录

生成的目录

/
/about/
/license/
/user-guide/getting-started/

链接

Markdown 扩展

表格

First Header | Second Header | Third Header
------------: | :-------------: | :------------
Content Cell | Content Cell  | Content Cell
Content Cell | Content Cell  | Content Cell

代码块

三个 ` 反引号

配置

所有配置参数

简介

项目配置在 medics.yml 文件中设置

配置文件中至少应包含 site_name 选项. 其余选项都是可选的.

参数	解释	默认值
site_name	必要，项目文档的主标题
site_url	设置站点的 URL	null
repo_url	如果设置了该项, 每个页面将会添加一个链接到你的 GitHub 或 Bitbucket 版本库.	null
repo_name	添加外部链接	GitHub 、Bitbucket、null
site_description	设置站点描述。在 HTML 头部添加一个 meta 标签	null
site_author	设置站点作者。这将这 HTML 头部添加一个 meta 标签	null
site_favicon	需要将 favicon.ico 放到 docs/ 目录	null
copyright	设置站点版权信息	null
google_analytics	设置 Google 站点分析工具	null
pages	设置目录结构
theme	设置主题
theme_dir	主题所在位置
docs_dir	设置 markdown 文档目录
site_dir	设置生成的 HTML 和其他文件所在目录
extra_css	设定主题所需的额外的样式文件
extra_javascript	设定主题所需的额外的脚本文件
use_directory_urls	设置文档中的链接类型
dev_addr	设置映射地址	0.0.0.0:80
markdown_extensions	Markdown 语法扩展，例如, 激活 SmartyPants typography extension 扩展