section-intro-guide

核心任务

生成符合初学者需求的入门指南类教程 (.rmd/.qmd)，强调 "概念 → 流程 → 代码 → 解释" 结构，确保 70% 文字 + 30% 代码比例。

快速启动 (Quick Start)

1. 确定主题: 如 "R 语言数据结构 (Data Structures)"。
2. 加载模板: 阅读 content-structure.md 获取 YAML 和标题结构。
3. 生成内容: 遵循 "目标 -> 路线 -> 概念 -> 实践 -> 错误纠偏" 流程。
4. 视觉设计: 参考 visual-templates.md 生成封面图和学习路径图。
5. 质量检查: 验证文字比例与导航更新。

完整工作流程

步骤1: 生成教程内容与封面

按 content-structure.md 结构生成文件。

• 必须包含: ## 教程目标与适用场景 到 ## 进阶扩展 的标准结构。
• 文字比例: 必须确保文字解释占 70% 以上，假设读者是零基础。
• 封面图 (MANDATORY): 必须生成 doc/images/00[number]-[topic]-cover.svg。
• 原理图: 复杂逻辑，结构图，代码不好展现的，必须AI生图生成 doc/images/diagrams/stat-*.svg（或者png），由AI直接生成，比如一些思维导图，可视化内容，使用md语法在文章内引用

步骤2: 验证渲染 (CRITICAL)

在提交前必须进行本地渲染验证，确保代码可运行且格式正确。

# 渲染单文件验证内容
quarto render doc/00[number]-[topic].rmd

# 确保无报错、包缺失或格式问题

步骤3: 更新导航系统 (CRITICAL)

必须执行以下步骤，否则新文章无法在网站侧边栏和分类页显示。

1. 更新 doc/_quarto.yml:

   • 找到 sidebar -> contents -> 入门指南 部分。
   • 添加新条目，注意缩进:
     yamlCopy

               - text: "文章标题"
                 href: "00xx-filename.rmd"
     

2. 更新 doc/0001-guide.rmd:

   • 在对应分类的表格中添加一行：
     markdownCopy

     | [主题名] | [文章标题](00xx-filename.html) | [简短说明] |
     

3. 运行自动生成脚本 (MANDATORY):

   • 此脚本会根据 _quarto.yml 更新 sections/guide.qmd 等分类索引页。
   bashCopy

   # 在项目根目录下运行
   workdir="doc" Rscript doc/generate_sections.R
   

4. 更新 README.md:

   • 在 🧭 内容导航 -> 🏗️ 开发环境 或相关折叠块中添加链接。

步骤4: 最终渲染与提交

1. 重新渲染受影响页面:

   bashCopy

   quarto render doc/sections/guide.qmd
   quarto render doc/index.qmd
   

2. 提交代码:

   bashCopy

   git add doc/00xx-*.rmd doc/images/00xx-*-cover.svg
   git add doc/_quarto.yml doc/0001-guide.rmd README.md doc/sections/guide.qmd
   git commit -m "feat(guide): 新增[教程标题]入门教程"
   

写作规范

• 内容标准:
  • 详细度: 内容必须详尽，起到深入教程的作用。
  • 篇幅: 不少于 300 行 (Not less than 300 lines)。
  • 比例: 文字说明约占 70%，代码约占 30% (70% text, 30% code)。
  • 结构: 必须提前构建全面的内容框架，然后根据框架填充详细内容。
• 语言: 客观、科学、结构清晰，以段落叙述为主。
• 代码: 优先使用 pkg::fn()；随机过程设置 set.seed(2026)。
• 标题: 使用中文标题，层级清晰（一级到三级）。

参考资源

• content-structure.md: 详细内容模板与标题规范。
• visual-templates.md: SVG 封面与示意图模板库。
• learning-roadmap.md: R 语言学习路线参考。