本页目录

第一个站点#

本页从零搭建一个小站点：一个首页、两个指南页面和一篇博客文章。

提示

想更快？sumi-starter 是一个现成的模板仓库，包含中英文两套内容和 GitHub Pages 部署流程，点 Use this template 即可开始。

创建项目
```
mkdocs new my-docs
cd my-docs
```
规划文件
- my-docs/
  - docs/
    index.md首页
    guide/
    index.md分区首页，侧边栏标题链接到这里
    install.md
    blog/
    posts/
    hello.mdblog/ 下的页面都是博客文章
  - mkdocs.yml站点配置

配置站点

mkdocs.yml

site_name: 我的文档
site_url: https://example.com/
repo_url: https://github.com/me/my-docs

theme:
  name: sumi
  locale: zh

plugins:
  - search
  - sumi

预览并构建

mkdocs serve        # 实时预览
mkdocs build        # 把静态文件写入 site/

导航如何生成#

顶层分区会成为页眉中的标签，当前标签内的页面显示在侧边栏中。如果一个分区的第一页是 index.md，它就是该分区的首页，点击分区标题会打开它。

提示

不写 nav: 时，MkDocs 会按文件夹结构生成导航。博客文章会自动从侧边栏中排除。

部署#

mkdocs build 会把纯 HTML、CSS 和 JavaScript 写入 site/。把这个文件夹上传到任意静态托管服务即可：GitHub Pages、Cloudflare Pages、Netlify、对象存储或 Nginx 服务器都行。部署后不需要运行任何程序。

mkdocs gh-deploy      # 构建并推送到 gh-pages 分支