🔧 安装配置指南

详细说明 My Docs 的安装和配置过程。

系统要求

最低配置

操作系统: Windows 10 / macOS 10.15+ / Ubuntu 18.04+
内存: 4GB RAM
存储: 2GB 可用空间
网络: 稳定的互联网连接

环境准备

Python 环境

# 检查 Python 版本
python --version
# Python 3.8+

# 安装 pip（如未安装）
python -m ensurepip --upgrade

Node.js 环境（可选，用于 Vercel 部署）

# 检查 Node.js 版本
node --version
# Node.js 16+

# 检查 npm 版本
npm --version

安装步骤

方法一：使用 pip 安装

# 创建虚拟环境（推荐）
python -m venv mydocs-env

# 激活虚拟环境
# Windows
mydocs-env\Scripts\activate
# macOS/Linux
source mydocs-env/bin/activate

# 安装依赖
pip install -r requirements.txt

方法二：使用 conda 安装

# 创建 conda 环境
conda create -n mydocs python=3.9
conda activate mydocs

# 安装依赖
pip install -r requirements.txt

配置说明

基本配置

编辑 mkdocs.yml：

site_name: "我的项目文档"
site_description: "项目详细文档说明"
site_author: "您的姓名"
site_url: "https://your-domain.com"

主题配置

theme:
  name: material
  palette:
    - scheme: default
      primary: blue
      accent: blue
  features:
    - navigation.tabs
    - navigation.sections
    - toc.integrate

插件配置

plugins:
  - search
  - mkdocs-jupyter
  - redirects:
      redirect_maps:
        'old-page.md': 'new-page.md'

本地开发

启动开发服务器

# 在项目根目录执行
mkdocs serve

# 指定端口
mkdocs serve --dev-addr=localhost:8080

实时预览

访问 http://localhost:8000 查看实时效果。修改文档后会自动刷新。

构建部署

构建静态文件

# 生成静态文件到 site/ 目录
mkdocs build

# 清理构建缓存
mkdocs build --clean

部署到 Vercel

# 安装 Vercel CLI
npm install -g vercel

# 部署
vercel --prod

部署到 GitHub Pages

# 配置 GitHub Pages
mkdocs gh-deploy --force

高级配置

自定义 CSS

创建 src/styles/extra.css：

:root {
  --md-primary-fg-color: #0066cc;
  --md-accent-fg-color: #00aaff;
}

/* 自定义样式 */
.my-custom-class {
  border: 1px solid #ccc;
  padding: 1rem;
}

自定义 JavaScript

创建 src/js/custom.js：

// 自定义脚本
document.addEventListener('DOMContentLoaded', function() {
  console.log('My Docs 已加载');
});

故障排除

常见问题

问题: mkdocs serve 报错解决: 检查 Python 版本和依赖安装

问题: 页面样式异常解决: 清理浏览器缓存，重新构建

问题: 搜索功能不工作解决: 检查 search 插件配置

调试模式

# 启用详细日志
mkdocs serve --verbose

# 调试构建过程
mkdocs build --verbose

性能优化

构建优化

# 启用并行构建
mkdocs build --parallel

# 禁用缓存
mkdocs build --no-cache

部署优化

启用 Gzip 压缩
配置 CDN 缓存
优化图片资源

后续步骤

完成安装配置后，您可以： - 学习基础使用 - 探索高级功能 - 查看实战示例

需要帮助？查看故障排除