制作一个 MkDocs 个人网站¶

为了发 98 写的前言¶

一直在寻找一种合适的记录方式，备忘录，相册，朋友圈，每一种都能承载一部分生活，但又没有办法保存希望保存的一切。

在此之前见到的个人博客大多是以课程资源的呈现为主，比如拯救了数届学子的 savia的外装代脑，比如咸鱼暄的代码空间，但在看到 LadyGege 老师的网站之后我说，我也想要做一个这样的东西。虽然不知道是否能够像前辈们一样给读者带来如此大的意义，但至少可以以一种半私密的形式记录自己。

于是暑假在家无事，尝试了一下这件事情。欢迎关注我的网站。那么我觉得一定还有更多，不管是现在还是未来，正在犹豫着想要做这件事情的同学，所以结合 AI 的帮助写了这篇教程。

之前在看过不少 MkDocs 建站的教程，但大多是手动一步步建立文件结构、修改内容，并且默认读者已经有一定的计算机基础，环境配置、Git 操作、部署流程都是几笔带过，对于还不太熟悉电脑操作的同学非常不友好。

但好消息是，现在 AI 智能体的能力已经完全可以驾驭这个任务，所以这篇指南基本抛弃了全部代码内容，你只需要会复制粘贴、会点鼠标、会按提示确认，就能真正从零开始搭出一个属于自己的网站，并免费部署到互联网上。

这篇教程已经被至少两位朋友验证是可行的，欢迎大家成为新的验证者。

这篇指南在讲什么¶

我们要做的事情，是把一个 MkDocs 网站从零搭起来，并放到互联网上让所有人都能访问。整个流程分成五步走：

第 0 步：准备一点点 Markdown 基础（可选，但推荐）
第 1 步：拥有一个 AI 智能体（已经有了可以直接跳过）
第 2 步：网站初始化——让智能体在你的电脑上把网站搭出来，先本地预览
第 3 步：部署到 GitHub——把网站发布到互联网上
第 4 步（可选）：购买并绑定一个属于自己的域名

最后第 5 步会讲日常怎么手动改一些小东西、怎么推送更新。

一个重要的观念

这篇指南里，真正"动手"的是你的智能体。你的工作是：提出要求、复制提示词、检查结果。遇到任何看不懂的报错，把报错原样复制发给智能体，让它解决。

第 0 步：一点点 Markdown 基础¶

MkDocs 网站里的每一篇文章，都是用 Markdown 这种轻量标记语言写的（就是带一点 # 标题、- 列表、**加粗** 这类符号的纯文本）。

如果你完全没接触过，建议先花几分钟看一下这个教程，可以顺便把 Markdown 和 LaTeX 都了解一下，常用工具。

当然，现在 AI 的能力已经足够让我们用自然语言实现任何目的——你完全可以不学前置知识，直接对智能体说"帮我写一篇标题为 xxx 的文章"。但略微掌握一点 Markdown，能让你自己随手修改一些小地方时不用事事都麻烦智能体，会方便很多。

第 1 步：拥有一个 AI 智能体¶

智能体（Agent）就是一个能听你吩咐、直接在你电脑上干活的 AI：它能帮你安装软件、创建文件、运行命令、修改代码。常见的智能体有 Opencode、Claude Code、Codex、Kimi Code 等等，任选其一即可。

如果你已经能正常使用其中任意一个智能体，请直接跳到第 2 步：网站初始化。

如果还没有，展开下面的卡片，跟着做一遍（以 Opencode + DeepSeek API 为例，其他智能体和模型可以自行选择，思路完全一样）：

还没有智能体？手把手教你部署（以 Opencode + DeepSeek API 为例）

1. 先搞懂两个名词：API 和 API Key¶

API：你可以把它理解成"程序打电话的号码"。智能体本身没有大脑，它需要通过 API 去调用云端的大模型（比如 DeepSeek），大模型思考完把结果传回来。
API Key：相当于你打电话用的"账号密码"，是一串以 sk- 开头的字符。大模型厂商靠它识别你是谁、从你的余额里扣费。它只能你自己知道，不要发给任何人、不要贴到公开网站上。
费用：按用量计费，单位是 token（可以粗略理解为 1 个汉字 ≈ 1 个 token）。DeepSeek 非常便宜，百万 token 只要几元，新手充 20 元能玩很久。

2. 安装 Node.js¶

Opencode 需要借助 Node.js 来安装，先装它：

打开 nodejs.org（打不开就搜"Node.js 中文官网"），点击大大的 LTS 版本下载按钮，得到一个 .msi 安装包。
双击安装，全程点 Next 就行——保持默认选项（其中 "Add to PATH" 默认是勾选的，不要取消）。
装完验证：按 Win + R，输入 powershell 回车，打开黑色窗口（这叫"终端"），输入下面这行并回车：
```
node -v
```
显示类似 v22.x.x 的版本号，再输入 npm -v 也显示版本号，就说明装好了。注意这里可能会出现报错，报错内容是“因为在该系统上禁止运行脚本”，如果出现此报错，先关闭当前的powershell窗口，然后在电脑自带的搜索栏搜索[powershell]，右键，[以管理员身份打开]，执行以下命令：
```
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
```
然后输入Y确认。确认后关闭这个窗口，重新按上述方法打开普通powershell窗口，重试指令。

3. 安装 Opencode¶

在同一个黑色终端窗口里，输入下面这行并回车：

npm install -g opencode-ai

等它跑完（看到 added x packages 之类的提示）。然后输入 opencode --version 回车，显示版本号就说明安装成功了。

可能遇到的小问题：

下载特别慢或卡住：先执行 npm config set registry https://registry.npmmirror.com（换成国内镜像源），再重新执行安装命令。

4. 获取 DeepSeek API Key¶

打开 platform.deepseek.com，用手机号/邮箱注册一个账号并登录。
在左侧菜单找到 API keys，点进去，点 创建 API key。
给它起个名字（随便起，比如 opencode），点创建。
页面会弹出一串以 sk- 开头的 Key——马上复制并保存到备忘录里，它只显示这一次，关掉就再也看不到了（丢了只能重新创建一个）。
回到左侧菜单，点充值：支持支付宝/微信，先充 10 元就够你玩很久。

5. 考虑一下 Coding Plan¶

除了上面这种"按量付费"的方式，各大模型厂商还提供 Coding Plan（编程套餐）：包月付费，额度很大，而且能用上各家最强的模型。比如智谱的 GLM Coding Plan、Kimi、Qwen 等都有类似套餐，一般几十元一个月起。

为什么推荐：模型越强，智能体干活越省心——少出错、少返工、少生气。如果你打算长期用智能体做事，买一个 coding plan 是性价比很高的投资。买好之后，配置方式和下面第 6 步类似，只是把 DeepSeek 换成对应厂商的 Key 和模型名，照着该厂商给的接入文档做即可（也可以直接问智能体："我买了 GLM Coding Plan，这是 Key，帮我配置好"）。

6. 把 DeepSeek 接到 Opencode¶

在终端输入 opencode 回车，会进入一个全屏的对话界面（这叫 TUI）。
输入 /connect 回车，在列表里找到 DeepSeek，按提示粘贴你刚才保存的 API Key。
输入 /models 回车，选择你想用的模型（比如 deepseek-v4-flash）。
如果有思考强度的选项，选择max就可以，

7. 确认自己成功了 + 基本用法¶

在对话框里随便发一句"你好，介绍一下你自己"，有回复就说明一切就绪，你拥有智能体了！

以后的使用姿势：

先进入项目文件夹再启动：在文件夹空白处右键 → "在终端中打开"（或在终端里用 cd 文件夹路径），然后输入 opencode。
输入 /init 让智能体分析当前项目，它会生成一个说明文件，之后干活更准。
按 Tab 键可以在 Plan（只做计划不动手）和 Build（直接动手改）两种模式间切换，拿不准时先让它出计划。
改错了别慌，输入 /undo 可以撤销。

第 2 步：网站初始化¶

提醒：现在你已经拥有 Agent 了，在之后的步骤中无论遇到什么问题，都可以语言描述或截图交由 Agent 解决，一般来说，它能解决绝大多数问题。

2.1 建一个文件夹¶

在电脑上选一个你找得到的位置（比如"文档"里，或者 D 盘根目录），新建一个文件夹，名字叫 my-website（建议用英文小写、不要带空格和中文，能避开很多莫名其妙的坑）。

然后在这个文件夹里启动智能体：打开文件夹，在空白处右键 → 在终端中打开，输入 opencode 回车。

2.2 把这段提示词发给智能体¶

把下面这一整段复制下来，粘贴给智能体，回车。注意先把方括号里的内容改成你自己的（板块名称、课程示例都可以按自己的需求修改——想叫"笔记""随笔"而不是"课程"，直接改提示词就行，想要加入更多板块可以同理添加）：

请帮我在当前文件夹从零搭建一个 MkDocs 个人网站，要求如下：

1. 环境：检查本机 Python，用 pip 安装 mkdocs 和 mkdocs-material 主题。
   如果遇到任何环境问题（比如没装 Python），请你自动解决，解决不了再一步步教我操作。
2. 创建这样的文件结构（文件夹名称可以根据【】内的内容进行调整）：
   - mkdocs.yml：网站名称为【我的网站名称】，使用 Material 主题，中文界面（language: zh）。
   - docs/index.md：【主页】，风格简洁纯白，页面中央用大字显示网站名称【我的网站名称】。
   - docs/course/index.md：【课程】板块首页，放一句话简介和文章列表。
   - docs/course/example.md：一篇示例课程文档，让我以后知道文章该按什么格式写。
   - docs/friends/index.md：【友链】板块，先放一两个示例链接占位。
   - docs/about/index.md：【关于】板块，放简单的自我介绍占位文字。
3. mkdocs.yml 里的 nav 导航依次是：主页、课程、友链、关于，分别指向上面的文件。
4. 全部创建好后，运行 mkdocs serve 启动本地预览，并告诉我应该在浏览器打开哪个网址。
5. 我完全不懂编程：过程中你每做一步，用通俗的语言告诉我做了什么；
   任何需要我手动操作的地方，请一步步教我点哪里、按什么。

智能体接到任务后会自己跑起来：装环境、建文件、写配置。期间它可能会问你问题或让你确认某个操作，照着回答/确认就行。

2.3 本地预览¶

智能体启动 mkdocs serve 后，会告诉你一个网址。用浏览器打开它——恭喜，你的网站已经在自己电脑上跑起来了！

这里有概率出现网址打不开的情况，如果有问题，让 Agent 帮你修。

现在随便逛逛，哪里不满意就直接用自然语言告诉智能体，比如"主页标题再大一点""导航栏换成蓝色"，它会改到你满意为止。预览看够了，回到终端按 Ctrl + C 可以停止预览。

2.4 认识一下文件结构（以后手动改要用）¶

让智能体干完活后，你的文件夹大概长这样（可能会因上面的微调有变化，但总体架构不变）：

my-website/
├── mkdocs.yml            ← 网站的"总配置"：网站名、导航目录、主题设置都在这
└── docs/                 ← 所有网页内容都在这个文件夹里
    ├── index.md          ← 主页
    ├── course/           ← 课程板块
    │   ├── index.md      ← 课程板块首页
    │   └── example.md    ← 示例课程文档
    ├── friends/
    │   └── index.md      ← 友链页
    └── about/
        └── index.md      ← 关于页

记住三个对应关系就够了：

想改文章内容 → 找到 docs/ 里对应的 .md 文件，用记事本或任何markdown编辑器打开改。
想加一篇文章 → 在对应板块文件夹里新建一个 .md 文件（文件名用英文小写加短横线，如 my-first-post.md），并且在 mkdocs.yml 的 nav: 里登记一行，否则导航里看不到它。
想改网站名 / 导航 → 改 mkdocs.yml。

第 3 步：部署到 GitHub（让网站上线）¶

本地预览只有你自己能看到。要让全世界都能访问，我们把网站免费托管到 GitHub Pages 上。

还没有 GitHub 账号？先展开这里注册

GitHub 是全球最大的代码托管网站，我们的网站文件就存在它那里。访问 GitHub 一般需要科学上网；如果你还不会，可以到 CC98上搜相关教程，有很多详细的新手帖。如果仍有困难，可参考科学上网的具体步骤：找到一个平台（ikuuu、GW树洞等），注册，登录，选择套餐并充值，下载客户端，打开客户端并登录，选择节点并连接。连接后，没有特殊情况的话，在你对网站进行搭建/修改的时候，可以长期保持“规则”模式连接。

Github注册步骤：

打开 github.com，点右上角 Sign up。
输入邮箱 → 设置密码 → 设置用户名。
用户名会出现在你将来的网址里（用户名.github.io），建议起一个好记、好看的英文ID。
按提示完成人机验证和邮箱验证，免费账号即可，注册完成！

电脑还没有安装 git ？先展开这里安装

如果不确定自己有没有安装：先打开一个powershell窗口，输入

git --version

如果出现类似 git version 2.52.x.windows.1 的字样，则说明曾经安装过，可以先进行下一步，如果出现问题再根据Agent的指令解决。

如果之前没有安装过，参照以下步骤安装（此步骤交给Agent有案例表明可能会报错较多，还是推荐手动操作，且它并不十分麻烦，相信自己，已经马上就要完成了）：

完成科学上网步骤，保持【规则】状态连接。
复制链接 https://git-scm.com/install/windows 到浏览器打开（以windows电脑为例，mac可以咨询Agent有哪些相应变化）。
点击图中红色框选区域下载到任意位置，路径尽量不要包含中文，没有特殊情况可以保持默认。
找到刚才下载的位置，双击打开安装包。许可协议next，安装路径next，选择组件（Select Components）如果Add a Git Bash Profile to Windows Terminal没有默认勾选的话把它勾上，其他不用动next，Choosing the default editor直接next，Adjusting the name of the initial branch 这个选择第二个Override the default branch name for new repositories，并在框内填入main，Adjusting your PATH environment选择有recommended的中间项，Configuring the line ending conversions选第一个Checkout Windows-style, commit Unix-style line endings，后面一路next到底，最后install。
接下来我们需要配置环境，告诉git我们是谁。在开始菜单搜索 Git Bash 并单击打开。
在黑色的窗口里，依次输入以下命令（注意空格，每次复制一行，把引号里的内容换成你的，注意git bash里面有可能会出现部分敏感信息不显示的情况，只要保证自己复制/输入上了就果断回车就可以。还有一个小技巧：git bash、Powershell等命令行工具中大多可以采用鼠标右键粘贴）：

# 配置用户名git config --global user.name "你刚才设置的github用户名"
# 配置邮箱git config --global user.email "你刚才注册github所用的邮箱"

输入以下命令检查是否成功：

git config --global --list

如果你看到了刚才输入的 user.name 和 user.email，说明配置成功！

最终验证：打开一个Powershell界面，输入

git --version

如果出现类似 git version 2.52.x.windows.1 的字样，恭喜你！Git 安装成功，且环境变量配置正确。

接下来我们保持科学上网工具连接状态，打开登录好的 github，点击右上边栏加号-new repository，仓库命名为【你刚刚注册 github 设置的用户名.github.io】，其他全部保持默认即可，点击创建。

剩下的事依然可以交给智能体。把下面这段发给它（记得把方括号里的内容换成你刚刚设置的用户名）：

请帮我把这个网站部署到 GitHub Pages，步骤如下：

1. 在当前文件夹初始化 git 仓库并提交全部文件；创建 .gitignore，
   把 site/ 和 __pycache__/ 加进去（它们是自动生成的产物，不用上传）。
2. 创建 .github/workflows/ci.yml：一个 GitHub Actions 工作流，
   效果是每次 push 到 main 分支，就自动安装 mkdocs-material、
   运行 mkdocs build 并把构建结果发布到 gh-pages 分支。
3. 推送后告诉我：如何在仓库的 Settings → Pages 里把 Source 设为
   从 gh-pages 分支发布（如果工作流用的是官方 Pages 部署方式，则帮我确认对应设置）。
4. 最后告诉我大概等多久、访问哪个网址就能看到网站。

过程中有两件事可能需要你亲自动手：

登录授权：第一次推送时，电脑可能弹出浏览器让你登录 GitHub 授权，按提示登录即可。
打开 Pages 设置：推送成功后，到仓库页面的 Settings → Pages 确认发布来源已设置正确。

一切顺利的话，等 1~3 分钟，打开 https://你的用户名.github.io 就能看到你的网站了！（以后每次更新，线上也是延迟 1~3 分钟刷新；浏览器里按 Ctrl + Shift + R 强制刷新可立即看到最新内容。）

如果部署失败：到仓库页面的 Actions 标签页，能看到每次自动构建的记录，失败的那次点进去有红色报错——把报错复制发给智能体，让它修。

第 4 步（可选）：买一个自己的域名¶

买不买域名？区别 + 阿里云购买与绑定全流程

买和不买有什么区别¶

不买：你的网址是 你的用户名.github.io，免费、完全够用，功能上没有任何区别。
买：网址变成你自己挑的名字（比如 alight404.top），更好看、更像"自己的网站"。便宜的后缀一年只要十几元。

不想买的话跳过这步即可，什么时候想买再回来。

在阿里云购买域名（或腾讯云，或其他可行渠道，此处以阿里云为例）¶

打开阿里云域名服务（wanwang.aliyun.com），注册/登录阿里云账号。
在搜索框输入你想要的名字，挑一个后缀：.top 通常较便宜（首年常常只要 10 元上下），.com 更经典但一般比较贵。
点 加入清单 → 立即结算。
结算前需要创建一个 域名信息模板（域名持有人信息）：个人用户填真实姓名、身份证号、邮箱，然后按提示完成实名认证（信息模板审核官方说 1~5 个工作日，通常很快）。
实名通过后完成支付。价格参考：我的 .top 域名首年 14 元，续费 39 元/年，.top 算是很便宜的后缀了。

把域名和 GitHub 挂钩¶

分两头配置，相当于"双方同意"：

第一头：阿里云这边做解析（界面可能与此处不同，不懂如何操作就截图问智能体）

进入阿里云控制台 → 域名 → 找到你买的域名 → 点解析。
点 添加记录，添加一条：
记录类型：CNAME
主机记录：@
记录值：你的用户名.github.io
点 添加记录，添加 4 条 A 记录，记录值分别填 GitHub 的四个 IP：185.199.108.153、185.199.109.153、185.199.110.153、185.199.111.153。

第二头：GitHub 这边认领域名

打开你的仓库 → Settings → Pages。
在 Custom domain 里填入你的域名（如 alight404.top），点 Save。
等下面的 DNS 检查变绿后，勾选 Enforce HTTPS（强制加密访问）。

解析生效需要几分钟到几小时不等，之后访问你的域名就能看到网站了！

第 5 步：日常维护——手动小改 + 推送¶

网站上线后，日常无非是两类事：

自己动手改小东西¶

对照第 2.4 节的文件结构，常见的三种修改：

改/写文章：用编辑器打开 docs/ 里对应的 .md 文件直接改。
新增文章：在对应板块文件夹新建 .md 文件（英文小写+短横线命名），并在 mkdocs.yml 的 nav: 里登记一行。
改网站名/导航/配色：都在 mkdocs.yml 里。

改完之后，把更新推送到线上——在网站文件夹里打开终端，依次执行这三条（俗称"推送三件套"）：

git add -A
git commit -m "这里用一句话写你改了什么"
git push

推送成功后等 1~3 分钟，到你的网站刷新，就能看到最新内容。

当然如果你像我一样懒完全可以直接告诉 Agent，我想要改什么，如何改，最后把我的修改推送到 github。

拓展功能？交给你的智能体¶

想要留言板、背景图、首页动效、暗色模式……不需要自己研究，直接用自然语言告诉智能体你想要什么，让它去实现、你负责验收就行。

祝建站愉快 🎉

感谢 CuteJigglypuff、zhizhi 等在该教程修订中提供的灵感。