图文教程

图文教程：用图文形式发布 ToCodex 教程

图文教程适合讲解需要“看步骤、照着做”的 ToCodex 使用场景，例如安装配置、创建模式、运行任务、排查问题或展示某个完整工作流。好的图文教程应当让读者在不反复猜测界面位置的情况下，按顺序完成操作。

适用场景

你可以在以下内容中使用图文教程形式：

• 新手入门：例如安装 ToCodex、完成首次配置。
• 功能演示：例如使用浏览器任务、计划任务、代码模式或调试模式。
• 工作流说明：例如从需求分析到代码修改再到验证结果。
• 问题排查：例如定位报错、查看日志、修复配置。
• 最佳实践：例如如何组织提示词、如何保存任务记录。

图片放置规范

建议将教程图片放在文档站点的静态资源目录中，并按教程主题分组。

推荐结构：

tocodex-starlight/
├─ public/
│  └─ images/
│     └─ tutorials/
│        └─ image-text/
│           ├─ 01-open-tocodex.png
│           ├─ 02-select-mode.png
│           ├─ 03-enter-prompt.png
│           └─ 04-review-result.png
└─ src/
   └─ content/
      └─ docs/
         └─ tutorials/
            └─ image-text.mdx

在 MDX 中引用图片时，可以使用以 / 开头的公开路径：

![打开 ToCodex 面板](/images/tutorials/image-text/01-open-tocodex.png)

为了方便长期维护，建议图片文件名使用“序号 + 动作说明”的形式，例如：

01-open-tocodex.png
02-select-code-mode.png
03-run-command.png
04-check-result.png

这样即使后续补充步骤，也能快速判断每张图片对应的教程位置。

步骤截图写法

每个步骤建议包含四部分：目标、操作、截图、结果说明。

示例：

## 步骤 1：打开 ToCodex

目标：进入 ToCodex 面板，准备创建一个新的任务。

操作：在 VS Code 侧边栏中点击 ToCodex 图标。

![打开 ToCodex 面板](/images/tutorials/image-text/01-open-tocodex.png)

完成后，你应该能看到模式选择区域和输入框。

编写步骤截图时，请注意：

• 一张截图只表达一个关键动作，避免把多个复杂步骤放在同一张图中。
• 截图中应尽量保留与操作相关的区域，裁掉无关窗口。
• 如果界面中包含隐私信息、密钥、邮箱、服务器地址，请先打码。
• 截图说明要写清楚“读者应该看到什么”，不要只写“如下图”。
• 步骤标题应使用动词开头，例如“选择代码模式”“输入任务说明”“检查修改结果”。

插入代码片段

当教程涉及提示词、命令、配置或代码时，应使用 fenced code block，并标注语言类型。

提示词示例

请帮我为当前项目新增一个登录页面，要求使用现有样式体系，并在完成后运行构建检查。

命令示例

npm run build

配置示例

{
  "mode": "code",
  "verify": true,
  "docs": "tocodex-docs/"
}

MDX 示例

## 步骤 2：选择代码模式

在模式列表中选择“代码模式”，用于修改项目文件。

![选择代码模式](/images/tutorials/image-text/02-select-code-mode.png)

然后输入任务说明：

```text
创建一个新的帮助文档页面，说明如何使用计划任务。
```

代码片段应尽量短小、可复制、可直接运行。如果代码较长，可以只展示关键部分，并说明完整文件位置。

注意事项

发布图文教程前，建议检查以下事项：

1. 图片路径是否正确：本地预览时确认所有图片都能正常显示。
2. 截图是否清晰：避免使用过小、模糊或压缩严重的截图。
3. 步骤是否连续：读者按照顺序操作时，不应跳过必要前置条件。
4. 代码是否可复制：命令、配置和提示词应避免混入不可见字符。
5. 敏感信息是否隐藏：不要展示 API Key、Token、内部域名、私人路径等内容。
6. 标题层级是否合理：页面只保留一个一级标题，主要步骤使用二级标题。
7. 结果是否可验证：每个教程末尾应告诉读者如何确认操作成功。

示例教程结构

下面是一个完整的 ToCodex 图文教程结构示例：

---
title: 使用 ToCodex 创建文档页面
description: 通过图文步骤演示如何让 ToCodex 创建并验证一个文档页面。
---

# 使用 ToCodex 创建文档页面

本教程将演示如何使用 ToCodex 创建一个新的文档页面，并通过本地构建确认页面可用。

## 准备工作

- 已安装 ToCodex。
- 已打开目标项目。
- 项目中已有文档站点目录。

## 步骤 1：打开 ToCodex

![打开 ToCodex](/images/tutorials/create-doc/01-open-tocodex.png)

在 VS Code 侧边栏中打开 ToCodex 面板。

## 步骤 2：选择代码模式

![选择代码模式](/images/tutorials/create-doc/02-select-code-mode.png)

选择“代码模式”，用于创建和修改项目文件。

## 步骤 3：输入任务说明

```text
创建 src/content/docs/tutorials/new-page.mdx，内容为中文教程，包含标题、步骤和验证方式。

步骤 4：检查生成结果

确认文件内容符合预期，并检查是否只修改了目标文件。

步骤 5：运行验证命令

npm run build

如果构建通过，说明页面语法和引用路径基本正常。

常见问题

图片不显示怎么办？

检查图片是否放在 public/images/ 目录下，并确认 MDX 中的引用路径以 /images/ 开头。

教程步骤太长怎么办？

可以拆分为多个小节，每个小节只讲一个目标动作。

总结

通过清晰的步骤、截图和代码片段，读者可以更快理解 ToCodex 的实际使用流程。

## 发布前检查清单

发布前可以按下面的清单快速自检：

- [ ] 页面 frontmatter 包含 `title` 和 `description`。
- [ ] 图片文件已放入正确目录。
- [ ] 所有图片路径都能在本地预览中打开。
- [ ] 每个步骤都有明确的操作说明。
- [ ] 代码片段标注了合适的语言类型。
- [ ] 敏感信息已打码或移除。
- [ ] 教程末尾包含验证方式或预期结果。

## 总结

图文教程的核心是让读者“看得懂、照着做、能验证”。在编写 ToCodex 教程时，请优先保证步骤顺序清晰、截图目标明确、代码片段可复制，并在最后提供检查清单或验证命令，帮助读者确认任务已经完成。