跳转至

创建您的网站

installed Material for MkDocs后，您可以引导您的项目 使用mkdocs可执行文件的文档。转到所需的目录 您的项目将被定位并输入：

mkdocs new .

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

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: My site
site_url: https://mydomain.org/mysite
theme:
  name: material

site_url设置很重要，原因有很多。 默认情况下，MkDocs将假设您的网站托管在 您的域名。例如，当publishing to GitHub pages时，情况并非如此 页面-除非您使用自定义域。另一个原因是，一些 插件需要设置site_url，所以你应该始终这样做。

建议: configuration validation and auto-complete

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

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

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

    {
  "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"
  ]
}
    1. 如果您计划使用[图标和表情符号]，则此设置是必要的， 或者Visual Studio代码将在某些行上显示错误。
  1. 确保您选择的编辑器支持YAML模式验证。

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

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

高级配置

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

此外，请参阅本机支持的Markdown extensions列表 与Material for MkDocs集成，实现了前所未有的低成本 技术写作经验。

模板

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

写作时预览

MkDocs包括一个实时预览服务器，因此您可以在使用时预览您的更改 写你的文件。服务器将在以下情况下自动重建站点 储蓄。从以下内容开始：

mkdocs serve # (1)!

  1. 如果您有一个大型文档项目，可能需要几分钟的时间，直到 MkDocs已重建所有页面供您预览。如果你只感兴趣 在当前页面中，[--dirtyreload][--dirtyleroad]标志将使 重建速度更快：

    mkdocs serve --dirtyreload

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

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，您应该看到：

Creating your site

构建您的网站

编辑完成后，您可以从Markdown构建一个静态网站 文件包含：

mkdocs build

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

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文件），请阅读以下注意事项building for offline usage.

  1. 如果你是MkDocs插件或Markdown扩展的作者，并且你的项目 与MkDocs的Material合作，我们诚挚地邀请您贡献 作为GitHub上pull请求的一部分，您的extension或plugin的模式。 如果您已经定义了架构，或者希望将架构自托管到 减少重复，您可以通过$ref添加它。 ↩