使用指南

这份指南介绍如何使用 Doc 网站。你可以把它当作个人知识库，持续整理德语、吉他与 PCB Layout 的学习和实践记录。

1. 启动网站

在 Codex 终端或 PowerShell 中进入项目目录：

cd F:\doc
npm run dev

打开终端显示的地址，默认是 http://localhost:4321/。开发服务运行时，保存文章后可以在浏览器中查看更新；需要停止服务时，在运行它的终端按 Ctrl+C。

本站项目使用 Node.js 24.x，与 Vercel 构建环境保持一致。当前电脑的系统版本为 24.22.1。如果在其他电脑上安装项目，先准备 Node.js 24，再运行：

npm install
npm run dev

若再次出现 Node.js 版本不支持的提示，用 node -v 检查终端实际使用的版本。当前电脑也保留了备用启动命令 .\npm-local.cmd run dev。

2. 找到要编辑的位置

网站文章位于 src/content/docs/：

src/content/docs/
├── index.mdx                  # 首页
├── guides/
│   └── getting-started.md      # 本使用指南
├── examples/
│   ├── markdown.md            # Markdown 写法演示
│   └── mdx.mdx                # MDX 组件演示
├── german/
│   └── index.md               # 德语学习总览
├── guitar/
│   └── index.md               # 吉他学习总览
└── pcb-layout/
    └── index.md               # PCB Layout 设计总览

修改已有文章时，直接编辑对应文件。左侧侧边栏用于切换栏目，右侧目录用于跳转到当前文章的章节，顶部搜索用于查找内容。

3. 新建第一篇笔记

例如，在 src/content/docs/german/ 中新建 first-note.md，填入以下内容：

---
title: 我的第一篇德语笔记
description: 记录今天学习的一句德语和需要复习的问题。
sidebar:
  order: 10
---

## 今天学了什么

Ich lerne Deutsch. —— 我正在学习德语。

## 自己的练习

写下自己的例句，或记录一次朗读。

## 下一次复习

- [ ] 不看笔记说出这句话
- [ ] 检查读音和拼写

保存后，访问 /german/first-note/ 查看文章。文件顶部两条 --- 之间的内容叫 frontmatter，用来设置标题、摘要和导航顺序；title 必须填写。sidebar.order 可省略，数字较小的文章优先显示。

三个专题栏目已按目录自动生成导航。 新文件放进 german/、guitar/ 或 pcb-layout/ 后，会出现在对应侧边栏中。文件名决定路径，使用简短的英文小写字母、数字与连字符，标题可以使用中文。

4. 编写常用 Markdown

文章标题由 frontmatter 中的 title 显示，正文通常从二级标题 ## 开始：

## 学习主题

普通段落中可以写 **重点**、*强调* 和 `术语`。

- 一个知识点
- 一个待解决的问题

1. 准备材料
2. 开始练习
3. 记录结果

- [ ] 尚未完成
- [x] 已经完成

[返回德语学习](/german/)

> 引用、摘录或给自己的提醒。

表格适合整理词汇、练习进度和设计参数。引用他人材料时，在记录附近写明作者或来源链接，方便回查。

更多语法及其实际效果见 Markdown 演示。

5. 需要组件时使用 MDX

普通笔记使用 .md 即可。需要在正文中使用组件时，新建 .mdx 文件。本站已经配置 MDX，首页就是一个实际示例。

下面的示例可以保存为 src/content/docs/guitar/practice-card.mdx：

---
title: 今日练习卡
description: 用组件整理一次吉他练习。
---

import { Card, CardGrid } from '@astrojs/starlight/components';

<CardGrid>
  <Card title="练习目标">
    完成一个片段，并记录需要调整的位置。
  </Card>
  <Card title="复盘结果">
    写下本次观察到的问题和下一次练习的重点。
  </Card>
</CardGrid>

导入组件的 import 语句写在 frontmatter 之后。组件名称和标签大小写需要保持一致。

卡片、选项卡和表达式的完整效果见 MDX 演示。

6. 调整标题与侧边栏

站点名称、界面语言和栏目导航位于项目根目录的 astro.config.mjs。例如，德语栏目使用：

{
  label: '德语学习',
  items: [{ autogenerate: { directory: 'german' } }],
}

只新增文章时，通常不需要修改这里。需要增加新的一级栏目时，再创建内容目录，并在 sidebar 数组中加入相应分组。

如果只想改变某篇文章在侧边栏里的名称或顺序，可以设置文章自己的 frontmatter：

sidebar:
  label: 常用表达
  order: 20

7. 检查内容与构建

保存后，先在浏览器检查标题、表格、代码块和链接，再运行：

npm run build
npm run preview

build 将网站生成到 dist/；preview 用于在本地查看构建结果，访问地址以终端输出为准。内置搜索会在构建时生成索引，验证搜索时使用构建后的预览站点。

如果构建失败，先查看终端指出的文件和行号，重点检查 frontmatter 的缩进、MDX 标签是否闭合、组件是否正确导入。

当前项目没有单独的单元测试脚本。执行 npm run build 后，仍需要实际打开新增页面，检查内容和导航是否符合预期。

8. 让记录方便复习

每篇记录可以只回答四个问题：目标是什么、做了什么、结果如何、下一步是什么。不必一次把整个栏目填满，先记录一个可以复现的例句、片段或设计决策。

完成后，可以从这些入口继续：