零基础也能写出漂亮文档：我的文档工具实战经验

大家好，我是阿哲，一名在大厂干了三年后端开发的程序员，同时也是B站上一个小小的技术UP主。经常有刚入门的小伙伴私信问我：“代码写完了，怎么写文档啊？”、“有没有简单好用的文档工具推荐？”——其实我当初学的时候也特别懵，光是看别人项目里那些排版精美、结构清晰的文档，就觉得自己差了一整个银河系。

但后来我发现，写文档不是玄学，而是一套可以快速上手的技能。今天这篇教程，就是专门给完全零基础的朋友准备的，我会用最通俗的语言，带你从零开始掌握现代文档工具的核心用法。无论你是学生、转行者，还是刚入职的新手，只要会打字，就能学会！

更重要的是，会写文档，不仅能让你的技术分享更专业，还能为你的个人运营加分。在B站做内容这几年，我深刻体会到：技术强是基础，但能把技术讲清楚、写明白，才是让人记住你的关键。

---

一、文档工具到底是什么？为什么你需要它？

简单说，文档工具就是帮你把文字、代码、图片等内容自动排版成美观网页或PDF的“魔法盒子”。

想象一下：

• 你写了一个Python小工具，想教别人怎么用
• 你在公司负责一个内部系统，新同事需要快速上手
• 你想在GitHub上开源项目，吸引别人参与

这些场景都需要文档。但如果你只是用Word或纯文本写，不仅格式乱，还很难维护。而用专业的文档工具（比如 Docusaurus、VuePress、MkDocs），你只需要写简单的 Markdown 文件，它就能自动生成带导航栏、搜索框、响应式布局的专业网站！

✅ 好处总结：

• 写一次，多端展示（网页、PDF、移动端都适配）
• 支持代码高亮、目录自动生成
• 可以部署到 GitHub Pages 免费公开访问
• 团队协作时，直接提交 .md 文件就行，超方便！

---

二、环境准备：5分钟搭建你的第一个文档站点

我们选 Docusaurus 作为入门工具。它是 Facebook（现 Meta）开源的静态网站生成器，对新手极其友好，社区活跃，插件丰富。

步骤 1：安装 Node.js

Docusaurus 依赖 Node.js。打开 https://nodejs.org，下载 LTS 版本（长期支持版），一路默认安装即可。

安装完成后，打开终端（Windows 用 PowerShell 或 CMD，Mac 用 Terminal），输入：

node -v
npm -v

如果看到类似 v18.17.0 和 9.6.7 的版本号，说明安装成功！

步骤 2：创建你的文档项目

在终端中执行以下命令（一行一行复制粘贴）：

npx create-docusaurus@latest my-docs classic
cd my-docs
npm start

💡 解释：

• npx 是 Node.js 自带的工具，不用全局安装
• my-docs 是你的项目文件夹名，可改成你喜欢的
• classic 表示使用经典模板（含博客+文档）

执行完后，浏览器会自动打开 http://localhost:3000，你会看到一个默认的 Docusaurus 主页！恭喜，你的文档站点已经跑起来了！

步骤 3：了解项目结构

打开 my-docs 文件夹，重点看这几个目录：

my-docs/
├── docs/          ← 所有文档放这里！
├── src/pages/     ← 首页等特殊页面
├── docusaurus.config.js ← 全局配置文件
└── package.json   ← 依赖和脚本

所有你要写的文档，都放在 docs/ 目录下，文件后缀是 .md（Markdown）。

---

三、核心概念：用最简单的语言讲清楚

1. Markdown 是什么？

Markdown 是一种轻量级标记语言，用简单符号代替复杂排版。比如：

# 一级标题
## 二级标题

- 列表项1
- 列表项2

`console.log('hello')`  ← 行内代码

```js
// 代码块
function greet() {
  return "Hi!";
}

你不需要记太多语法，常用的就是标题、列表、代码块、链接。大部分编辑器（如 VS Code）都有实时预览插件。

### 2. 文档的“元信息”（Front Matter）

每个文档开头可以加一段 YAML 配置，告诉系统这个页面叫什么、属于哪个分类：

```md
---
id: getting-started
title: 快速开始
sidebar_label: 快速开始
slug: /start
---

这是文档正文...

• id：唯一标识，用于链接跳转
• title：网页标题
• sidebar_label：侧边栏显示的名字
• slug：URL 路径（比如 /start）

🚫 新手常见错误：YAML 块必须用 --- 包裹，且不能有空格缩进错误！

3. 侧边栏（Sidebar）怎么配置？

Docusaurus 默认会按文件顺序生成侧边栏，但我们可以自定义。

打开 sidebars.js（在项目根目录），你会看到：

module.exports = {
  tutorialSidebar: [
    'intro',
    'getting-started',
    // 可以按分类组织
    {
      type: 'category',
      label: '进阶指南',
      items: ['advanced/config', 'advanced/deploy'],
    },
  ],
};

• 字符串 'intro' 表示 docs/intro.md
• type: 'category' 创建一个折叠菜单

这样你的文档就能分门别类，不再杂乱！

---

四、实战：5分钟打造你的第一份技术文档

现在，我们来做一个真实的例子：写一份“天气查询工具”的使用说明。

第 1 步：新建文档文件

在 docs/ 目录下新建文件 weather-tool.md，内容如下：

---
id: weather-tool
title: 天气查询工具使用指南
sidebar_label: 天气工具
---

## 功能介绍

这是一个用 Python 编写的命令行天气查询工具，支持全国城市。

## 安装方法

```bash
pip install weather-cli

使用示例

查询北京天气：

weather-cli --city 北京

输出：

北京当前温度：25°C，晴

参数说明

参数	说明	是否必填
--city	城市名称	是
--unit	温度单位（c/f）	否，默认 c

### 第 2 步：更新侧边栏

打开 `sidebars.js`，在数组里加上 `'weather-tool'`：

```js
module.exports = {
  tutorialSidebar: [
    'intro',
    'getting-started',
    'weather-tool', // ← 新增这一行
  ],
};

保存后，刷新浏览器，侧边栏就会出现“天气工具”！

第 3 步：添加代码高亮（可选）

Docusaurus 默认支持多种语言高亮。上面的 bash 和 python 代码块会自动着色，无需额外配置。

💡 小技巧：在代码块开头写 ```py 或 ```json，能获得更精准的高亮。

---

五、新手常踩的坑 & 解决方案

问题	原因	解决办法
修改文档后页面没更新	浏览器缓存	强制刷新（Ctrl+F5）或重启 npm start
侧边栏不显示新文档	没在 sidebars.js 中注册	确保文件名（不含 .md）已加入数组
中文显示乱码	文件编码非 UTF-8	用 VS Code 打开，右下角点“UTF-8”确保正确
部署后图片不显示	图片路径错误	所有图片放 static/img/，引用时用 /img/xxx.png
标题层级错乱	Markdown 标题跳级（如 # 直接到 ###）	按顺序使用 #、##、###

🔥 我当初学的时候，就因为没加 Front Matter，导致页面 404，折腾了半小时！记住：每个 .md 文件最好都加上 --- 开头的元信息。

---

六、如何用文档助力你的技术分享与个人运营？

很多新人以为“写文档=完成任务”，但其实它是技术影响力放大器。

场景 1：GitHub 开源项目

• 一份清晰的 README + 完整文档 = 更多人 star 和贡献
• 示例：https://docusaurus.io 本身就是用 Docusaurus 写的

场景 2：B站/知乎技术分享

• 在视频描述里附上文档链接，观众可随时查阅
• 把文档当作“文字版教程”，扩大内容覆盖面

场景 3：求职作品集

• 把你做的小工具配上专业文档，打包成作品集网站
• 面试官一看：“这人不仅会写代码，还会沟通！”

🌟 我的建议：从第一个小项目开始就写文档。哪怕只有一页，也是习惯的开始。

---

七、下一步学习建议

你现在已经有能力搭建和维护基础文档了！接下来可以：

1. 美化主题：修改 docusaurus.config.js 中的 themeConfig，换 logo、改颜色
2. 添加搜索：集成 Algolia（免费！），让用户快速找内容
3. 多语言支持：用 i18n 功能做中英文切换
4. 自动化部署：配置 GitHub Actions，每次 push 自动发布到线上

📚 推荐资源：

• Docusaurus 官方中文文档：https://docusaurus.io/zh-CN
• 我的 B 站视频：《10分钟搭建个人技术文档站》
• Markdown 速查表：https://www.markdownguide.org/cheat-sheet/

---

最后的话

写文档不是负担，而是对自己思考的梳理，对他人时间的尊重。我见过太多优秀的代码，因为缺乏文档而无人问津；也见过平平无奇的小工具，因为文档写得清晰易懂，收获上千 star。

希望这篇教程能帮你迈出第一步。记住：每一个大神，都是从写好第一行文档开始的。

如果你觉得有帮助，欢迎去 B 站搜“阿哲学编程”，那里有更多零基础友好的实战教程。也欢迎在评论区留言你的问题——技术分享的路上，我们一起成长！