新建网站¶

在完成Material for MkDocs的安装后，可以使用mkdocs相关命令来启动文档。转到要放置项目的目录，然后输入：

mkdocs new .

如果你正在使用的是Docker中的Material for MkDocs，则使用以下命令：

Unix

docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .

Windows

docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material new .

以上操作会新建以下结构的文件：

.
├─ docs/
│  └─ index.md
└─ mkdocs.yml

配置¶

最小配置¶

只需要简单的添加以下几行内容到mkdocs.yml即可启用主题。请注意，由于有几种不同的安装方法，因此配置可能会略有不同：

pip, docker

theme:
  name: material

git

theme:
  name: null
  custom_dir: mkdocs-material/material

  # 404 page
  static_templates:
    - 404.html

  # Necessary for search to work properly
  include_search_page: false
  search_index_only: true

  # Default values, taken from mkdocs_theme.yml
  language: en
  font:
    text: Roboto
    code: Roboto Mono
  favicon: assets/favicon.png
  icon:
    logo: logo

如果是从GitHub克隆的MkDocs from GitHub，那么应当列出所有主题的默认项，因为mkdocs_theme.yml不会作为官方的描述文件被自动载入

高级设置¶

Material for MkDocs包含许多可配置项，_设置_章节有如何设置或者自定义颜色、字体、图标等等的详细说明。

预览¶

MkDocs包含一个试试预览的服务，所有可以在撰写文档的过程中进行实时预览。当文档修改保存后，这个服务会自动重建整个网站的文档。使用以下命令启动：

mkdocs serve

如果使用的是Docker中的Material for MkDocs，则使用以下命令：

Unix

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

Windows

docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material

浏览器打开localhost:8000，应该就能看到类似下图所示的内容：

生成网站¶

当文档编辑完成后，可以通过以下命令将所有的Markdown文件生成一个静态网站：

mkdocs build

该目录中的内容就是项目文档/网站。因为是完全独立的，所以不需要操作数据库或者服务器。生成的网站可以托管在GitHub Pages、GitLab Pages、CDN网络或者其它的web服务器上。