武汉子格教育科技有限公司

一、制作作使用 MkDocs

MkDocs 是个网一个轻量级、易用的步骤静态网站生成器，专为文档网站设计，网站文档支持 Markdown 编写和多种主题。何制

1. 安装与创建项目

安装：通过 pip 安装

```bash

pip install mkdocs

```

创建项目：在终端执行

```bash

mkdocs new my_docs

```

生成 `my_docs` 目录，制作作包含 `mkdocs.yml` 配置文件和 `docs` 存放文档的个网文件夹。

2. 配置与内容编辑

基础配置：编辑 `mkdocs.yml` 设置站点名称、步骤URL、网站文档导航菜单等。何制

编写文档：在 `docs` 目录下创建 `.md` 文件，制作作如 `index.md` 作为首页。个网

本地预览：运行 `mkdocs serve` 启动本地服务器，步骤访问 `http://127.0.0.1:8000` 查看效果。网站文档

3. 自定义与扩展

主题切换：支持 Material、何制Read the Docs 等主题，通过配置文件修改。

插件扩展：可添加搜索、国际化等功能模块。

二、使用 Docusaurus

Docusaurus 是由 Facebook 开发的文档网站生成器，基于 React 开发，支持 Markdown 和组件化开发。

1. 安装与项目创建

环境要求：需 Node.js （≥14 或 16.14） 和 npm。

创建项目：执行

```bash

npx create-docusaurus@latest my-website classic

```

使用 `classic` 模板生成基础项目结构。

2. 配置与内容管理

基础配置：编辑 `docusaurus.config.js` 设置标题、组织信息等。

添加内容：在 `docs` 目录创建 `.md` 文件，或通过 `src` 目录添加组件。

本地预览：运行 `npm start` 启动开发服务器，访问 `http://localhost:3000`。

3. 高级功能

搜索与国际化：内置搜索功能，支持多语言文档。

部署：支持部署到 GitHub Pages 或 Vercel，生成静态文件。

三、注意事项

文档类型选择：

单页文档推荐使用 MkDocs；

多页面/组件化文档建议使用 Docusaurus。

主题与扩展：

优先选择官方主题（如 Material、Read the Docs），便于维护和更新。

通过插件扩展功能，如搜索、版本控制等。

部署方案：

GitHub Pages：免费且易配置，适合个人项目或开源文档；

Vercel/Docusaurus：支持自动化部署和持续集成。

通过以上工具和方法，您可以高效地构建专业化的文档网站。根据项目需求选择合适工具，并结合 Markdown 的简洁性和静态网站的高性能特点，提升文档展示效果。