============================================================

# ============================================================
# 网站基本信息
# ============================================================

# 网站名称，必填
site_name: 我的文档

# 网站描述和作者，可选
site_description: 项目文档
site_author: Your Name

# 部署后的正式网址
# GitHub Project Pages 通常为：
# https://用户名.github.io/仓库名/
site_url: https://example.github.io/my-project/

# 页脚版权信息，可选
copyright: Copyright © 2026 Your Name

# ============================================================
# GitHub 仓库信息
# ============================================================

# Material 主题会在页面中显示仓库链接
repo_name: username/my-project
repo_url: https://github.com/username/my-project

# ============================================================
# 网站导航
# 路径相对于 docs/ 目录
# ============================================================

nav:
  - 首页: index.md
  - 使用指南:
      - 快速开始: guide/getting-started.md
      - 基本用法: guide/usage.md
  - 关于: about.md

# ============================================================
# 主题
# ============================================================

theme:
  # 使用 Material for MkDocs
  name: material

  # 主题界面使用简体中文
  language: zh

  # 常用功能
  features:
    # 页面切换时避免完整刷新
    - navigation.instant

    # 搜索建议
    - search.suggest

    # 搜索结果关键词高亮
    - search.highlight

# ============================================================
# Markdown 扩展
# ============================================================

markdown_extensions:
  # 支持 !!! note 等提示框
  - admonition

  # 支持 ??? note 等可折叠提示框
  - pymdownx.details

  # 增强代码块
  - pymdownx.superfences

  # 支持给 Markdown 元素添加属性
  - attr_list

  # 标题生成永久链接
  - toc:
      permalink: true

# ============================================================
# 插件
# ============================================================

plugins:
  # 全文搜索
  - search

项目结构

my-project/
├── mkdocs.yml
└── docs/
    ├── index.md
    ├── about.md
    └── guide/
        ├── getting-started.md
        └── usage.md

安装 material 主题

pip install mkdocs-material