用途
write-user-guide 是 posit-dev/great-docs 提供的一项技能，用于在 Great Docs 文档站点中撰写和维护叙述型用户指南页面。用户指南提供教程、概念解释和任务演示等内容，与自动生成的 API 参考互补。
主要能力
- 创建新指南页：在
docs/user_guide/下新建NN-topic.qmd文件。 - 控制侧边栏排序：文件名使用两位数数字前缀，如
00-introduction.qmd；构建时前缀会被去掉，生成干净 URL（user-guide/introduction.html）。 - 分组显示：通过 frontmatter 中的
guide-section把页面归入可折叠的侧边栏分组；未设置则显示在顶层。 - 页面元信息：
title为必填项；可选guide-section、tags、bread-crumbs（设为 false 隐藏面包屑）、status（experimental、new、stable 状态徽章）。 - 提示块：使用
:::{.callout-tip}、:::{.callout-note}、:::{.callout-warning}等 Quarto callout，可用类型包括 note、tip、warning、caution、important。 - 可执行代码：
{python}单元在构建时经 Jupyter 执行并捕获输出；{.python}仅做语法高亮、不执行。支持#| eval: false仅显示代码、#| echo: false仅显示输出。 - 表格组件：静态数据文件用
{{< tbl-preview file=... >}}或{{< tbl-explorer file=... >}}短代码；DataFrame 用tbl_preview()与tbl_explorer()，支持 Pandas、Polars 及 CSV、TSV、Parquet、Arrow、JSONL 文件路径。 - 跨页链接：使用相对路径链接其他页面，如
[Configuration](../user-guide/configuration.qmd)。 - 图片资源：放在
docs/assets/，构建时自动复制。
使用方式
快速开始示例（来自资料）：
mkdir -p docs/user_guide
cat > docs/user_guide/00-introduction.qmd << 'EOF'
---
title: "Introduction"
guide-section: "Getting Started"
tags: [Getting Started]
---
# Introduction
Welcome to the project. This guide walks you through...
EOF
great-docs build
页面正文结构建议：以与 title 一致的一级标题开头，用 ## 表示主要章节、### 表示子章节，层级尽量扁平；每节先写一句引导语，段落保持简短；结尾可加总结或“下一步”。
新增页面流程：选取下一个数字前缀 → 编写 frontmatter → 按结构写正文 → 运行 great-docs build && great-docs preview 检查排序与渲染。
重排页面：重命名文件调整前缀、修改 guide-section 重新分组、重新构建、检查失效的跨页链接。
将 README 转为指南页：复制内容到新 .qmd 文件、补充 frontmatter、把 GitHub 风格 Markdown 扩展替换为 Quarto 等价写法（如 > [!NOTE] 改为 :::{.callout-note}）、重新构建验证。
适用场景
适用于需要在 Great Docs 站点中编写教程、概念说明和任务演示等叙述性文档的开发者与文档维护者。
限制与注意事项
- 所有页面必须直接位于
docs/user_guide/，不要嵌套子目录。 guide-section区分大小写，不同大小写会生成不同分组。- 文件名用连字符而非下划线（URL 中下划线会转为连字符）。
- 数字前缀缺省时按字母排序；也可以在 great-docs.yml 中显式定义页面顺序。
- title 应与正文 # 标题一致，否则侧边栏与页面标题不一致。
- 列表前需空行，否则 Quarto 不将其解析为列表。
- 重命名页面会改变 URL，需同步更新跨页链接。
- 资料中未提供该技能的具体安装方式、价格与平台限制等信息。