使用教程

从零开始，一步步了解博客系统的每一个功能。即使你从未接触过 Markdown、GitHub 或数学公式，也能跟着本教程上手。

1. 启动博客

本博客有两种运行方式，选择适合你的场景。

方式一：GitHub Pages（推荐）

GitHub Pages 是最简单的发布方式——零依赖、开箱即用。把你的博客代码推送到 GitHub，几分钟后就能通过 https://你的用户名.github.io 访问。

设置步骤：

在 GitHub 上创建一个仓库（Repository，即代码仓库，用来存放你的博客文件）
将博客代码推送到这个仓库
进入仓库的 Settings（设置）→ Pages（页面）
在 Source（来源）中选择你的分支（通常是 main）和目录（通常是 /root）
点击 Save，等待几分钟后即可通过 URL 访问

获取 GitHub Token

Token（令牌）是一种访问凭证，类似于密码，但权限可以精确控制。编辑器需要 Token 来读写你仓库中的文章文件。

创建步骤：

登录 GitHub，点击右上角头像 → Settings
左侧菜单最下方 → Developer settings（开发者设置）
左侧 → Personal access tokens（个人访问令牌）→ Fine-grained tokens（细粒度令牌）
点击 Generate new token（生成新令牌）
Token name：随便起个名字，比如 "blog-editor"
Expiration（有效期）：建议选 90 天，到期后可以重新生成
Repository access（仓库访问权限）：选择 Only select repositories（仅选定仓库），然后选择你的博客仓库
在 Permissions（权限）区域，找到 Repository permissions → Contents（内容），设置为 Read and write（读写权限）
点击 Generate token，复制生成的 token（以 github_pat_ 开头的长字符串）

注意：Token 只会显示一次，请妥善保存。如果丢失，需要重新生成。

方式二：本地服务器

如果你只想在自己的电脑上写博客、不需要发布到互联网，用这种方式最简单。

前提条件：电脑上已安装 Python 3（macOS 和 Linux 通常自带，Windows 需要下载安装）。

# 打开终端（Terminal），进入博客目录
cd blog

# 启动服务器（默认 8080 端口）
python3 server.py

然后打开浏览器，访问 http://localhost:8080 即可看到博客首页。

密码保护

如果你的电脑在局域网内（比如公司 Wi-Fi），别人也可能通过 IP 地址访问你的管理页面。加上密码可以防止未授权访问：

# --password 后面跟你想设置的密码
python3 server.py --password mysecret

也可以自定义端口号（默认 8080）：

python3 server.py 3000

2. 写文章

打开编辑器页面（/editor/write.html），你会看到以下区域：

工具栏（Toolbar）— 页面上方的按钮栏，提供 Markdown、数学公式、图表的快捷插入，不需要记住语法
标题 — 文章的大标题，会自动生成 URL 路径（Slug，即网址中文章的唯一标识，例如 my-first-post）
标签（Tags）— 用逗号分隔的关键词，方便读者按分类浏览，例如 "教程, 入门"
摘要（Summary）— 一句话描述文章内容，会显示在首页的文章列表中
正文 — 文章的主要内容，使用 Markdown 语法编写

写完后点击发布（Publish）按钮，文章就会保存并出现在博客首页。

工具栏让你不需要记住 Markdown 和 LaTeX 语法，点击按钮就能插入模板：

Markdown 菜单：常用格式（标题、粗体、列表、链接等），选中文本后点击，自动包裹语法标记
数学公式菜单：常用数学符号和结构（分式、积分、矩阵等），点击后插入到光标位置
图表菜单：Mermaid 图表模板（流程图、时序图等），点击后插入代码框架，修改里面的文字即可

预览功能

点击预览（Preview）按钮，可以在发布前查看文章的最终渲染效果。预览支持所有功能：Markdown 格式、数学公式、Mermaid 图表、代码高亮都会正确显示。

图片上传

在编辑器中可以直接插入图片，不需要手动上传到服务器：

粘贴：截图后直接 Ctrl+V（macOS 为 Cmd+V）
拖拽：把图片文件从文件夹拖入正文编辑区域

图片会自动上传到服务器，并在正文中插入对应的 Markdown 图片语法（![描述](图片地址)）。

草稿功能

编辑器提供两种草稿保存方式：

自动保存 — 每 30 秒自动将你正在写的内容保存到浏览器的本地存储（localStorage）。如果你不小心关闭了页面，下次打开同一篇文章时会提示是否恢复草稿
手动存为草稿 — 点击编辑器底部的 存为草稿 按钮，可以将文章以草稿状态保存到服务器。草稿不会出现在博客首页，但可以在管理页面中看到

在管理页面中，每篇文章右侧有一个 草稿/发布 切换按钮，可以随时将已发布的文章切换为草稿，或将草稿发布上线。

自动保存的草稿只保存在当前浏览器中，不会同步到其他设备。手动保存的草稿会同步到服务器（本地服务器或 GitHub）。

3. 数学公式

博客使用 KaTeX（一个快速的数学公式渲染引擎，类似 LaTeX 的语法）来显示数学公式。你不需要安装任何东西，直接在正文中写公式语法即可。

行内公式

行内公式（Inline）嵌入在文字中间，用一对美元符号 $...$ 包裹：

写法： $E = mc^2$

效果：爱因斯坦的质能方程 $E = mc^2$ 是物理学中最著名的公式之一。

块级公式

块级公式（Display）单独占一行，更醒目，适合复杂公式。用两对美元符号 $$...$$ 包裹：

$$\int_{0}^{\infty} e^{-x^2} \, \mathrm{d}x = \frac{\sqrt{\pi}}{2}$$

渲染效果：

$$\int_{0}^{\infty} e^{-x^2} \, \mathrm{d}x = \frac{\sqrt{\pi}}{2}$$

常用语法速查

语法	含义	效果
`\frac{a}{b}`	分式	$\frac{a}{b}$
`\sqrt{x}`	平方根	$\sqrt{x}$
`\sum_{i=1}^{n}`	求和符号	$\sum_{i=1}^{n}$
`\int_{a}^{b}`	积分符号	$\int_{a}^{b}$
`\vec{F}`	向量箭头	$\vec{F}$
`\alpha, \beta, \gamma`	希腊字母	$\alpha, \beta, \gamma$
`x^{2}`	上标	$x^{2}$
`x_{i}`	下标	$x_{i}$
`\pm`	正负号	$\pm$
`\times, \div`	乘号、除号	$\times, \div$
`\leq, \geq, \neq`	小于等于、大于等于、不等于	$\leq, \geq, \neq$
`\infty`	无穷大	$\infty$

你也可以使用工具栏中的数学公式菜单来插入这些模板，不需要记住语法。

4. Mermaid 图表

Mermaid 是一个用文字描述来生成图表的工具。你只需要写一段简单的文本定义，Mermaid 就会自动将其渲染为图形。不需要手动画图。

在正文中使用三个反引号加 mermaid 关键字来创建图表代码块：

流程图（Flowchart）

用来表示步骤之间的顺序关系。语法说明：graph LR 表示从左到右排列，--> 表示箭头，{} 表示判断节点，[] 表示普通步骤。

```mermaid
graph LR
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]
```

渲染效果：

graph LR
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]

时序图（Sequence Diagram）

用来表示多个对象之间的交互顺序。participant 定义参与者，->> 表示请求，-->> 表示响应。

```mermaid
sequenceDiagram
    participant U as 用户
    participant S as 服务器
    U->>S: 请求
    S-->>U: 响应
```

渲染效果：

sequenceDiagram
    participant U as 用户
    participant S as 服务器
    U->>S: 请求
    S-->>U: 响应

也可以通过工具栏的图表菜单快速插入这些模板。

5. 代码高亮

用三个反引号（反引号是键盘左上角 ` 键）包裹代码块，并在开头指定语言名称，就能获得语法高亮（Syntax Highlighting，即根据编程语言的规则为代码中的关键字、字符串等添加不同颜色）。

def hello():
    print("Hello, Blog!")

支持的常用语言：python、javascript、c、cpp、bash 等。语言名称写在三个反引号后面即可，例如 ```python。

6. 主题切换

点击页面右上角的主题按钮（一个圆形图标），会弹出主题选择菜单。选择后立即生效，刷新页面也会保持你的选择。

可用的主题：

🌙 暗色（Dark）— 默认的深色主题，适合夜间或低光环境
☀️ 亮色（Light）— 浅色背景，适合白天使用
🌿 护眼绿（Green）— 柔和的绿色调，减少视觉疲劳
🦄 紫悦（Twilight）— 紫色主题
🌈 云宝（Rainbow）— 青蓝色主题
🦋 柔柔（Fluttershy）— 粉色主题
💎 珍奇（Rarity）— 淡紫色主题

7. RSS 订阅

RSS（Really Simple Syndication，简易信息聚合）是一种标准格式，让读者可以通过 RSS 阅读器（如 Feedly、Inoreader）订阅你的博客，自动接收新文章通知，而不需要每次都打开网页查看。

博客自动生成 rss.xml 文件。读者只需要在 RSS 阅读器中输入你的博客地址，就能自动发现并订阅这个 RSS 源。

8. 文章管理

打开管理页面（/editor/index.html），可以看到所有文章列表（包括草稿）。在这里你可以：

编辑 — 跳转到编辑器修改文章内容
草稿/发布 — 切换文章的草稿状态。草稿不会显示在博客首页
删除 — 删除不需要的文章
写文章 — 快速跳转到编辑器创建新文章
刷新 — 重新加载文章列表

← Use Cases 查看文章 →