编写文档

一篇清晰的文档，先说明解决什么问题，再给出可复现的步骤，最后写下结果和限制。

使用在线工作台

打开 文档管理，使用管理员账号登录，即可在线编辑和发布。

1. 从左侧选择文档，或点击“新建”。
2. 填写标题、文件路径和目录分组，在正文编辑器中编写 Markdown。新文件路径以 .md 结尾，例如 guide/my-document.md。
3. 使用正文预览检查排版，图片可以通过“上传图片”插入，单张不超过 3 MB。
4. 点击“保存草稿”。此时前台仍显示已发布版本。
5. 点击“发布更新”，工作台会自动构建页面和搜索索引。发布成功后，前台才会更新。

“目录管理”可以修改分组、目录名称和排序。目录保存后也需要发布。编辑已有文档时会保留历史版本，可在“历史版本”中加载旧内容，再保存并发布。

发布失败时

构建失败会保留当前线上版本。展开发布日志查看原因，修正文档后重新发布即可。

新建一篇文章

在 docs/guide/ 或 docs/projects/ 中创建一个 .md 文件。文件名决定访问路径，例如 docs/guide/example.md 对应 /guide/example。

---
title: 我的第一篇文档
description: 这篇文档解决什么问题。
---

# 我的第一篇文档

先介绍目标与适用场景。

## 准备工作

- 必要的软件
- 运行环境

## 操作步骤

1. 完成第一步。
2. 检查运行结果。

## 常见问题

记录遇到的问题和解决方法。

标题与链接

每篇文档保留一个一级标题，章节使用二级标题，必要时再使用三级标题。右侧目录会自动读取二级、三级标题。

## 安装
### 配置环境

[另一篇文章](./getting-started)

站内链接推荐使用相对路径，便于将内容整体移动到新的目录。

代码与高亮

在代码块开头标注语言，可以获得语法高亮。花括号可以指定强调的行。

const site = 'Alanco Wiki'
console.log(`Hello, ${site}!`)

查看代码块的写法

```ts {2}
const site = 'Alanco Wiki'
console.log(`Hello, ${site}!`)
```

提示与折叠内容

小提示

把最常见、最有用的信息放在正文，把较长的补充说明放进折叠区域。

操作前检查

涉及配置变更时，写清适用环境，并保留可回退的旧版本。

::: tip 小提示
这里填写提示内容。
:::

图片与附件

把公共图片放在 docs/public/images/ 下，再使用下面的语法引用：

![图片内容的简短说明](/images/example.webp)

发布前压缩图片，并填写有意义的替代文本。正文截图优先保证文字清晰，不必上传远超实际显示尺寸的原图。

添加到目录

通过在线工作台新建时，选择分组并勾选“显示在目录中”，保存后会自动加入目录。手工维护源码时，目录存放在 .vitepress/sidebar.json。详见 外观与导航。