快速开始¶

本指南将帮助您快速创建第一个 MkDocs 站点。

创建新项目¶

1. 初始化项目¶

使用 mkdocs new 命令创建新项目：

mkdocs new my-project
cd my-project

这将创建以下结构：

my-project/
├── docs/
│   └── index.md
└── mkdocs.yml

2. 配置 Material 主题¶

编辑 mkdocs.yml 文件，添加 Material 主题配置：

site_name: 我的文档站点

theme:
  name: material
  language: zh
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: 切换到深色模式
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: 切换到浅色模式

3. 启动开发服务器¶

运行以下命令启动本地开发服务器：

mkdocs serve

成功！

打开浏览器访问 http://127.0.0.1:8000 查看您的站点。

编写内容¶

添加新页面¶

在 docs/ 目录下创建新的 Markdown 文件：

echo "# 关于我们" > docs/about.md

配置导航¶

在 mkdocs.yml 中添加导航配置：

nav:
  - 首页: index.md
  - 关于: about.md

使用 Markdown 扩展¶

启用常用的 Markdown 扩展：

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.tabbed:
      alternate_style: true

常用功能示例¶

代码块¶

使用三个反引号创建代码块：

```python
def hello():
    print("Hello, World!")
```

提示框¶

使用 !!! 语法创建提示框：

!!! note "标题"
    这是提示框的内容。

选项卡¶

创建选项卡内容：

=== "Python"
    ```python
    print("Hello")
    ```

=== "JavaScript"
    ```javascript
    console.log("Hello");
    ```

表格¶

创建表格：

| 列 1 | 列 2 | 列 3 |
|-----|-----|-----|
| A   | B   | C   |
| D   | E   | F   |

构建站点¶

本地构建¶

构建静态站点文件：

mkdocs build

这将在 site/ 目录下生成静态 HTML 文件。

清理构建

使用 --clean 标志清理旧文件：

mkdocs build --clean

部署到 GitHub Pages¶

MkDocs 提供了一键部署到 GitHub Pages 的命令：

mkdocs gh-deploy

注意

确保您的项目已经是一个 Git 仓库，并且已经推送到 GitHub。

开发工作流¶

推荐的开发工作流程：

graph TD
    A[编辑 Markdown 文件] --> B[保存文件]
    B --> C[自动重新加载]
    C --> D[在浏览器中预览]
    D --> E{满意?}
    E -->|否| A
    E -->|是| F[构建站点]
    F --> G[部署]

常用命令¶

命令	说明
`mkdocs new [dir]`	创建新项目
`mkdocs serve`	启动开发服务器
`mkdocs build`	构建站点
`mkdocs gh-deploy`	部署到 GitHub Pages
`mkdocs --help`	查看帮助

下一步¶

现在您已经掌握了基础知识，可以：