创建你的站点¶

在你[安装] Material for MkDocs 后，可以使用 mkdocs 可执行文件来启动项目文档。前往你希望项目位于的目录，并输入：

mkdocs new .

另外，如果你在 Docker 中运行 Material for MkDocs，请使用：

Unix, PowershellWindows (cmd)

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

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

这将创建以下结构：

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

配置¶

最小配置¶

只需设置 site_name 并在 mkdocs.yml 中添加以下行以启用主题：

site_name: 我的站点
site_url: https://mydomain.org/mysite
theme:
  name: material

site_url 设置对于多个原因非常重要。默认情况下，MkDocs 会假设你的站点托管在你域的根目录。这在[发布到 GitHub 页面]时并非如此——除非你使用自定义域。另一个原因是某些插件要求设置 site_url，因此你应该始终这样做。

推荐：[配置验证和自动补全]

为了减少摩擦并提高生产力，Material for MkDocs 提供了自己的 schema.json¹ 用于 mkdocs.yml。如果你的编辑器支持 YAML 模式验证，强烈建议进行设置：

Visual Studio Code其他

安装 vscode-yaml 以支持 YAML 语言。

在用户或工作区的 settings.json 中的 yaml.schemas 键下添加模式：

{
  "yaml.schemas": {
    "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
  },
  "yaml.customTags": [ // (1)!
    "!ENV scalar",
    "!ENV sequence",
    "!relative scalar",
    "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
    "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
    "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format",
    "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
  ]
}

如果你计划使用[图标和表情符号]，此设置是必要的，否则 Visual Studio Code 会在某些行上显示错误。

确保你选择的编辑器支持 YAML 模式验证。

在 mkdocs.yml 的顶部添加以下行：

# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json

高级配置¶

Material for MkDocs 提供了许多配置选项。设置部分详细解释了如何配置和自定义颜色、字体、图标等：

[更改颜色]
[更改字体]
[更改语言]
[更改徽标和图标]
[确保数据隐私]
[设置导航]
[设置站点搜索]
[设置站点分析]
[设置社交卡片]
[设置博客]
[设置标签]
[设置版本控制]
[设置页眉]
[设置页脚]
[添加 git 仓库]
[添加评论系统]
[构建优化站点]
[构建离线使用]

此外，请查看与 Material for MkDocs 原生集成的支持的[Markdown 扩展]列表，以提供前所未有的低成本技术写作体验。

模板¶

如果你想快速启动一个新项目，可以使用我们不断增加的模板集合中的一个：

博客

创建一个博客
社交卡片

创建带有社交卡片的文档

写作时预览¶

MkDocs 包含一个实时预览服务器，因此你可以在编写文档时预览更改。服务器会在保存时自动重建站点。使用以下命令启动它：

mkdocs serve # (1)!

如果你有一个大型文档项目，MkDocs 可能需要几分钟才能重建所有页面供你预览。如果你只对当前页面感兴趣，使用 --dirtyreload 标志将使重建速度更快：
```
mkdocs serve --dirtyreload
```

如果你在 Docker 中运行 Material for MkDocs，请使用：

Unix, PowershellWindows

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

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

在浏览器中访问 localhost:8000，你应该会看到：

![创建你的站点]

构建你的站点¶

完成编辑后，你可以使用以下命令从 Markdown 文件构建静态站点：

mkdocs build

如果你在 Docker 中运行 Material for MkDocs，请使用：

Unix, PowershellWindows

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

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

该目录的内容构成你的项目文档。无需操作数据库或服务器，因为它是完全自包含的。该站点可以托管在 GitHub Pages、GitLab Pages、你选择的 CDN 或你的私有网络空间上。

如果你打算将文档分发为一组文件以便从本地文件系统读取，而不是从 Web 服务器读取（例如在一个 .zip 文件中），请阅读有关[离线使用构建]的说明。

如果你是 MkDocs 插件或 Markdown 扩展的作者，并且你的项目与 Material for MkDocs 兼容，非常欢迎你在 GitHub 提交拉取请求以贡献一个模式供你的[扩展]或[插件]使用。如果你已经定义了模式，或者希望自托管你的模式以减少重复，可以通过 $ref 添加。 ↩