步步图解

工作流

如何在本站写一篇新教程

站长自用说明：新建 Markdown 文件、插入截图和命令、本地预览、发布上线。

本站的每篇教程都是 content/guides/ 里的一个 Markdown 文件。文件名前面的数字决定排序。

STEP 01 / 06

新建教程文件

在项目根目录运行（把 slug 换成英文短名，它会成为网址的一部分）：

PowerShell
npm run new -- my-guide "我的教程标题"

这会生成一个草稿文件，draft: true 的教程不会出现在网站上。

STEP 02 / 06

填写开头信息

文件最上方两条 --- 之间是教程信息：

Frontmatter
title: 教程标题
summary: 一句话说明读者做完能得到什么
category: setup        # 对应 site.config.json 里的分类
tags: 标签一, 标签二
time: 15 分钟
level: 入门
updated: 2026-11-04

STEP 03 / 06

写步骤

每个 ## 二级标题 就是一个步骤，会自动编号并出现在目录里。步骤里可以用：

  • 普通段落、加粗、行内代码、链接
  • 三级标题 ###，用于步骤内部的小节
  • 列表和有序列表
  • 提示框：> [!TIP]、> [!NOTE]、> [!WARNING]、> [!DANGER]

代码块的语言后面可以跟一个标题，它会显示在复制按钮旁边：

写法示例
```powershell PowerShell
npm run build
```

STEP 04 / 06

插入截图

把图片放到 public/images/教程名/ 里，然后单独一行写：

写法示例
![图片说明，给读屏软件用](/images/my-guide/01.png "图注，显示在图片下方")

STEP 05 / 06

本地预览

PowerShell
npm run dev

打开 http://localhost:4321。修改文件后会自动重新构建，刷新浏览器就能看到。

STEP 06 / 06

发布上线

先构建：

PowerShell
npm run build

dist/ 文件夹就是完整的网站，可以部署到任意静态托管平台。以 Cloudflare Pages 为例：

PowerShell
npx wrangler pages deploy dist --project-name bubutujie

第一次运行会让你在浏览器里登录 Cloudflare。发布前记得把 site.config.json 里的 url 改成你的正式域名，这样 sitemap 和分享链接才正确。