创建您的站点

在安装了 MkDocs Material 之后，您可以使用mkdocs可执行文件创建项目文档。进入您希望项目位于其中的目录，并输入以下命令：

mkdocs new .

或者，如果您在 Docker 中运行 Material for MkDocs，请使用以下命令：

Unix、Powershell

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
└─ mkdocs.yml

配置

最小配置

只需将以下内容添加到mkdocs.yml中即可启用主题：

theme:
  name: material

推荐：配置验证和自动完成

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

Visual Studio Code

1. 安装vscode-yaml以获得YAML语言支持。

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

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

   1. 如果您计划使用图标和表情符号，则需要进行此设置，否则Visual Studio Code会在某些行上显示错误。

其他编辑器

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

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

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

高级配置

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

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

此外，还可以查看支持的[Markdown 扩展]列表，这些扩展与 Material for MkDocs 集成得很好，提供了无与伦比的轻松技术写作体验。

编写时预览

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

mkdocs serve # (1)!

1. 如果您有一个庞大的文档项目，可能需要几分钟才能重新构建所有页面以供预览。如果您只关注当前页面，--dirtyreload标志将加快重新构建速度：

mkdocs serve --dirtyreload

如果您在 Docker 中运行 Material for MkDocs，请使用以下命令：

Unix、Powershell

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

如果您在 Docker 中运行 Material for MkDocs，请使用以下命令：

Unix、Powershell

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

Windows

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

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

企业支持

如果您的组织正在使用Material for MkDocs，并且需要帮助，例如缩短构建时间、提高性能或确保合规性，请联系我们讨论我们的企业支持服务。我们乐意提供帮助！

---

1. 如果您是 MkDocs 插件或 Markdown 扩展的作者，并且您的项目与 Material for MkDocs 配合使用，我们非常欢迎您在 GitHub 上的拉取请求中贡献您的扩展或插件的模式。如果您已经定义了模式，或者希望自托管模式以减少重复，请使用$ref添加模式。 ↩