TeeDoc 快速启动指南

2025-07-07

简介

TeeDoc 是一个基于 Python 的静态文档生成器，可以将 Markdown 文档转换为美观的静态网站。本指南将帮助你快速启动 OpenEarable 2.0 项目的文档网站。

环境要求

  • Python 3.7 或更高版本
  • pip 包管理器

快速启动

方法一：使用启动脚本（推荐）

我们提供了自动化的启动脚本，可以一键完成环境配置和文档构建。

Windows 用户

# 双击运行或在命令行中执行
.\启动TeeDoc服务器.bat

Linux/macOS 用户

# 给脚本添加执行权限
chmod +x 启动TeeDoc服务器.sh

# 运行脚本
./启动TeeDoc服务器.sh

方法二：手动启动

如果你希望手动控制每个步骤，可以按照以下步骤操作：

  1. 创建虚拟环境

    python -m venv venv

  2. 激活虚拟环境

    # Windows
venv\Scripts\activate

# Linux/macOS
source venv/bin/activate

  3. 安装依赖包

    pip install -r requirements.txt

  4. 构建文档

    cd my_site
teedoc build

  5. 启动服务器

    teedoc serve

访问文档

启动成功后，在浏览器中访问：

!!! tip "小贴士"
首次启动可能需要几分钟时间安装依赖包，请耐心等待。

文档结构

my_site/
├── site_config.json    # 网站主配置文件
├── docs/               # 文档目录
│   ├── guide/         # 项目指南
│   │   ├── config.json
│   │   ├── sidebar.yaml
│   │   └── *.md
│   └── modules/       # 模块文档
│       ├── config.json
│       ├── sidebar.yaml
│       └── *.md
├── static/            # 静态资源
└── out/               # 构建输出目录

编辑文档

  1. 添加新文档：在对应目录下创建 .md 文件
  2. 修改导航：编辑 sidebar.yaml 文件
  3. 更新配置：修改 config.json 文件
  4. 重新构建：运行 teedoc build 命令

常见问题

启动失败

问题：提示 Python 未找到
解决：确保已安装 Python 3.7+ 并添加到系统 PATH

问题：端口被占用
解决：修改 site_config.json 中的端口配置

构建错误

问题：Markdown 语法错误
解决：检查 .md 文件的语法，特别是代码块和表格

问题：配置文件错误
解决：检查 config.json 和 sidebar.yaml 的 JSON/YAML 语法

更多功能

  • 搜索功能：支持全文搜索
  • 主题切换：支持暗色/亮色主题
  • 多语言：支持中英文切换
  • 响应式设计：适配移动设备

参考资源