尧图网站建设 
Handsontable 文档指南页编写规范Frontmatter、框架示例嵌入与 Sidebar 注册全解析【免费下载链接】handsontableJavaScript Data Grid / Data Table with a Spreadsheet Look Feel. Works with React, Angular, and Vue. Supported by the Handsontable team ⚡项目地址: https://gitcode.com/gh_mirrors/ha/handsontable本文基于 Handsontable 官方文档仓库中的.claude/skills/writing-docs-pages/SKILL.md技能说明结合docs/目录下的真实页面如 installation.md、README-EDITING.md 编辑指南、AGENTS.md 文档标准以及src/plugins/下的预处理插件源码系统讲解如何为 Handsontable 文档站点编写、编辑和注册指南页面。读完本文你将掌握 YAML frontmatter 的完整字段语义、四类 Diátaxis 页面结构、::: only-for框架条件内容、::: example可运行示例容器的全部选项、写作风格红线、sidebar 注册流程以及 TypeScript 示例到 JavaScript 的自动化生成命令。Handsontable 文档站点构建在 Astro Starlight 之上同时保留了大量 VuePress 风格的 Markdown 语法::: only-for、::: example、[[toc]]等这些语法由自定义插件在构建期转换。因此理解写什么与底层如何解析同等重要——前者保证页面符合规范后者帮助你排查为什么我的页面没按预期渲染。1. Frontmatter每个.md文件的强制起点按照 SKILL.md 的约定docs/content/guides/下每个指南页面的.md文件都必须以 YAML frontmatter 开头--- title: Feature Name metaTitle: Feature Name - JavaScript Data Grid | Handsontable description: Short SEO description under 160 characters. permalink: /feature-name canonicalUrl: /feature-name tags: - keyword1 - keyword2 react: metaTitle: Feature Name - React Data Grid | Handsontable searchCategory: Guides category: Cell features # Must match a sidebar category exactly menuTag: new | updated # Optional; sidebar badge ---其中menuTag: new用于新建页面menuTag: updated用于对已有页面做实质性内容修改纯小修错别字、代码片段/链接修正以及 changelog、迁移指南页面则省略该字段且不要动已存在的标签。1.1 字段语义与默认值README-EDITING.md 给出了每个字段的完整语义标签含义默认值title页面标题渲染为 H1未设置时由父级页面标题生成permalink页面的唯一URL未设置时由 Markdown 文件名生成canonicalUrl页面最新版的 canonical URL无非必需metaTitle页面的 SEO meta 标题无非必需description页面的 SEO meta 描述无非必需tags文档搜索引擎使用的搜索标签无非必需react/angular仅作用于对应框架版本的替代 frontmatter 集合无非必需searchCategory搜索结果的分类默认归入 Guides 分类menuTag侧边栏菜单中页面标题旁的徽标无非必需category页面所属内容分类用于组织页面无非必需1.2 按框架差异化 frontmatter同一页面在不同框架版本下可以有不同的 meta 信息。例如 installation.md 的真实 frontmatter--- type: how-to title: Installation metaTitle: Installation - JavaScript Data Grid | Handsontable description: Install Handsontable through your preferred package manager, or import Handsontables assets directly from a CDN. permalink: /installation canonicalUrl: /installation tags: - quick start react: metaTitle: Installation - React Data Grid | Handsontable angular: metaTitle: Installation - Angular Data Grid | Handsontable vue: metaTitle: Installation - Vue Data Grid | Handsontable searchCategory: Guides category: Getting started ---可用的框架键为react和angularSKILL.md 所列不过实际页面中vue键也被使用。框架键下不仅可以覆盖metaTitle、description还能定义自定义值这些值可在模板中消费且仅对对应框架生效。1.3 必须声明的type字段AGENTS.md 要求每个页面必须在 frontmatter 中声明 Diátaxis 内容类型type: tutorial | how-to | reference | explanation四种类型对应读者不同的诉求Tutorial教学、How-to guide任务达成、Reference信息查阅、Explanation原理理解。如果一页内容横跨两种类型应拆分为独立页面。目录结构本身也隐含了类型预期guides/getting-started/为 How-toapi/为 Referencerecipes/为 Tutorial。2. 页面结构无 H1、Overview、TOC 与渐进式小节SKILL.md 明确了指南页的固定结构顺序正文中不写 H1——Starlight 会用 frontmatter 的title字段渲染页面标题。如果在 frontmatter 之后再写# Title或其他 H1页面上会出现重复标题。Overview 概述——---之后的第一段内容用 1-2 句话说明该功能是什么、为什么重要。[[toc]]——自动根据各级标题生成目录。这一宏由vuepress-preprocessor.mjs在构建期移除Starlight 本身会自动渲染目录见 vuepress-preprocessor.mjs// 2. Remove [[toc]] (Starlight renders a ToC automatically) result result.replace(/^\s*\[\[\s*toc\s*\]\]\s*$/gm, );渐进式小节——只使用##及以下层级按启用功能 → 基本用法 → 配置选项 → 高级用法 → 键盘快捷键 → 已知限制 → API 参考链接的顺序组织。2.1 分类型模板AGENTS.md 为四种 Diátaxis 类型分别提供了模板。以 How-to 为例其骨架为Prerequisites前置条件→ Steps有序步骤列表→ Result → Related。## Steps下的有序列表会自动被渲染为 Starlight 步骤列表rehype-migration-steps.mjs插件为紧随该标题的ol添加classsl-steps rolelist因此直接写普通 Markdown 有序列表即可无需手工添加任何标记。3. 框架特定内容::: only-for条件块指南页需要同时服务 JavaScript、React、Angular、Vue 四种框架。用::: only-for容器包裹只适用于某个框架的内容::: only-for javascript JavaScript-only content here. ::: ::: only-for react React-only content here. :::关键约定:::标记必须独占一行且内容块前后都要有空白行。3.1 底层实现该语法由 vuepress-preprocessor.mjs 中的filterOnlyForBlocks()实现且必须最先执行。它维护一个栈结构逐行扫描遇到::: only-for frameworks开启标记时判断当前框架是否在列表中遇到内部嵌套的其他:::容器如::: example、::: tip时递增innerDepth遇到裸:::闭合标记时递减。只有所有外层 only-for 帧都命中当前框架的内容行才会被保留输出其他框架的内容被整体移除。构建期框架解析的另一层证据在 framework-loader.mjs自定义 Astro 内容加载器会为每个content/下的.md文件生成 4 个条目JavaScript/React/Angular/Vue 各一并附带框架前缀例如react-data-grid/guides/getting-started/introduction。因此同一个源文件最终会渲染出四个框架版本。4. 示例嵌入::: example容器与[code]指令指南页最重要的能力是嵌入可运行的代码示例带实时预览。SKILL.md 给出的标准模式如下。JavaScript / TypeScript 示例--js 1 --ts 2设置标签页顺序::: only-for javascript ::: example #example1 --js 1 --ts 2 [code](https://link.gitcode.com/i/f8cd9ce504e4cd3aaef8b07f47db7ae3) [code](https://link.gitcode.com/i/3dced1c300e75843bada41ef967e7d76) ::: ::: ::: only-for react ::: example #example1 :react --tsx 1 --jsx 2 [code](https://link.gitcode.com/i/c32da7355ef2f182f8e8adb5ccf7153e) [code](https://link.gitcode.com/i/790e1b1f34dbc15ed836ef294f40cf32) ::: ::: ::: only-for vue ::: example #example1 :vue3 [code](https://link.gitcode.com/i/b586f7b92de6d1a60456b06fdd588212) ::: :::规则要点Vue 3嵌入单个 TypeScript SFCvue/example1.vue使用script setup langts使用:vue3预设功能需要额外依赖时可用:vue3-languages、:vue3-vuex。不要为新 Vue 示例使用--html/--js标签页。Angular使用:angular预设配合--ts 1 --html 2。4.1 容器选项完整参考README-EDITING.md 给出了example容器的完整选项表选项必需示例可选值用途#exampleId否#example1字符串容器唯一 ID.class否.new-class字符串容器自定义 CSS 类:preset否:hot:hot|:hot-lang|:hot-numbro|:react|:react-languages|:react-numbro|:react-redux|:react-advanced|:angular|:angular-languages|:angular-numbro|:vue3|:vue3-numbro|:vue3-languages|:vue3-vuex设定代码依赖--js pos否--js 1正整数默认1设置 JS 代码片段在容器中的位置--html pos否--html 2正整数默认0设置 HTML 代码片段位置0禁用 HTML 标签页--css pos否--css 2正整数默认0设置 CSS 代码片段位置0禁用 CSS 标签页--no-edit否--no-edit--no-edit移除Edit按钮--tab tab否--tab previewcode|html|css|preview设置默认打开的标签页4.2 真实页面中的用法以 installation.md 为例JavaScript 部分嵌入示例::: example #example1 --js 1 --ts 2 [code](https://link.gitcode.com/i/f8cd9ce504e4cd3aaef8b07f47db7ae3) [code](https://link.gitcode.com/i/3dced1c300e75843bada41ef967e7d76) :::对应的示例源文件为 example1.ts 与 example1.js——注意它们都包含了licenseKey: non-commercial-and-evaluation非商业用途许可这是文档代码示例的强制要求。4.3 底层渲染原理framework-loader.mjs 中的processExampleBlocks()在only-for过滤之后处理这些容器解析#exampleId、CSS 类、--code-only标志收集块内的code引用然后调用buildExampleHtml()生成最终输出。buildExampleHtml()framework-loader.mjs会依据目录路径/angular/、/react/、/vue/而非扩展名判断框架避免 JS 示例携带的.ts变体被误判为 Angular为可执行示例生成带 loading 骨架屏的实时预览区、Source code切换按钮、Edit in sandbox与See on GitHub链接将 JSTS或 JSXTSX脚本归入同一个 JavaScript 标签页支持语言下拉切换HTML、CSS 作为独立标签页对无运行入口的服务端代码PHP、Python、Ruby 等退化为纯代码围栏展示。5. 写作风格Voice 与 Style 红线写作风格细则完整收录于 AGENTS.md文档站点专用覆盖了 monorepo 级规范.ai/DOC-STANDARDS.md中与之冲突的部分。SKILL.md 提炼的关键点主动语态、美式英语、短句。以 you 称呼读者绝不使用 we三个及以上并列项使用 Oxford comma牛津逗号。禁用评价性形容词easy、simple、obvious。用连字符-或双连字符--分隔从句不用 en dash——这是文档站点约定与 JSDoc/changelog 使用 en dash 不同。UI 元素加粗如Add commentAPI 名称用行内代码如comments。内部链接使用text语法。每个句子包括列表项以句号结尾。AGENTS.md 补充的禁用词表simply、just、easy、straightforward、note that、please、allows you to改用 lets you 或主动改写、in order to改用 to、utilize改用 use。标题与 frontmattertitle一律使用句首大写sentence case只大写首词、专有名词、产品名、API 标识符与缩略词例如Use a cell renderer而非Use a Cell Renderer。只使用直引号和禁用弯引号。6. 商标规则凡页面提到 Excel必须在页面底部包含 Microsoft/Excel 商标免责声明同时提到 Google Sheets 的页面使用同时覆盖两个商标的扩展版免责声明。免责声明以 callout 或脚注形式放在页面底部详见 AGENTS.md。7. 内部链接与模板变量7.1/链接语法README-EDITING.md 规定内部链接禁止使用绝对链接或相对 URL统一采用/前缀text规则细节后跟目标文件相对当前版本根目录的路径如[Clipboard](https://link.gitcode.com/i/982e12cdaa72855756623caf50420dc2)目标文件名必须带.md扩展名如Autofill需要定位小节时使用锚点如Core跨框架链接在后加框架名[React methods](https://link.gitcode.com/i/db6b3d7e432276592f8d23137f2ea49e)目标文件必须定义了permalinkfrontmatter若生成 URL 失败输出为相对链接兜底未指定框架时链接指向当前浏览的框架版本。链接中的/前缀由预处理插件统一转换为绝对路径见 vuepress-preprocessor.mjs。7.2 模板变量AGENTS.md 规定了五个构建期解析的模板变量用于避免在文档中硬编码 GitHub 分支名所有变量在 template-variables.mjs 中声明与替换变量生产构建其他构建用途{{$examplesBranch}}prod-examples/majormasterhandsontable/examples启动模板源码{{$currentMinorVersion}}prod-docs/major.minordevelophandsontable/handsontable源码链接{{$currentVersion}}package.json 版本0.0.0-next-sha-date版本字符串、runner 链接{{$latestChangelogVersion}}最新changelog-N主版本相同最新 changelog 页链接{{$basePath}}根相对资源路径硬编码tree/master链接会让旧版本文档的读者跳转到与版本不匹配的模板AGENTS.md 中的 DEV-2214因此必须使用模板变量。唯一例外是server-side-*recipes 保留tree/master/server-examples/...。8. Sidebar 注册让新页面出现在导航中创建新页面后必须将其加入 sidebar.js。在正确的分类数组中插入条目{ path: guides/category/feature-name/feature-name }若页面仅面向特定框架使用onlyFor{ path: guides/getting-started/react-methods/react-methods, onlyFor: [react] }, { path: guides/getting-started/angular-hot-instance/angular-hot-instance, onlyFor: [angular] }, { path: guides/getting-started/vue3-hot-reference/vue3-hot-reference, onlyFor: [vue] },未在 sidebar.js 中注册的页面不会出现在导航中AGENTS.md。注意页面的categoryfrontmatter 必须与 sidebar 的分类标题精确匹配。侧边栏的New / Updated徽标由menuTag字段驱动与 sidebar.js 无关。9. 代码示例生成与质量校验9.1 TypeScript 优先JavaScript 自动生成SKILL.md 规定JavaScript 和 React 示例先编辑 TypeScript 源文件.ts或.tsx再从docs/目录生成 JavaScript 变体cd docs npm run docs:code-examples:generate-js -- path-to-ts-file路径相对于docs/例如content/recipes/foo/javascript/example1.ts。该命令对应 package.json 中的docs:code-examples:generate-js实际由 transpile-doc-example.mjs 执行。Vue 示例则直接在.vue文件中编写 TypeScriptscript setup langts没有单独的 JS 文件需要生成。9.2 示例质量规则AGENTS.md 对示例代码提出了硬性要求所有代码块必须带语言标签javascript、typescript、html、css、shell、json、yaml禁止无标签代码块使用const和let禁用varnew Handsontable(...)调用必须包含licenseKey: non-commercial-and-evaluation发布示例中禁止行内// TODO或// ...注释示例控制在 25-60 行之间超出则改为链接到在线沙箱禁止占位数据foo、bar、A1、Column1、test等必须使用领域真实数据财务、HR、库存、分析、项目管理、科学等领域且至少 5 行数据以便功能可见Angular 示例必须使用standalone: true模式CSS 走--css槽位JIT 无法在运行时解析styleUrls、模板内联、构造函数禁止注入服务改用inject()、Hooks 放进gridSettings而非模板事件绑定、使用for/if/switch内置控制流。9.3 相关校验命令命令用途npm run docs:code-examples:generate-js -- path由 TS 生成 JS 示例npm run docs:test:plugins运行预处理插件单元测试npm run docs:lintESLint 检查src与contentnpm run docs:validate-changelog-links校验 changelog 中的/api/链接npm run build依次执行docs:api、docs:validate-highlights、astro build与层序校验npm run dev本地开发服务器.md与示例源文件支持热重载10. 提交前的自查清单AGENTS.md 提供了文档 PR 的标准检查清单关键条目包括frontmatter 已添加type:字段tutorial | how-to | reference | explanation且使用了对应类型的 Diátaxis 模板标题符合类型命名约定How-to 以 How to ... 开头Explanation 以 Understanding ... 开头无禁用占位数据、所有示例数据领域真实且前后一致所有代码块带语言标签、无var、示例含licenseKey标题层级无跳级如 H2 → H4、标题与title:使用句首大写全文主动语态 第二人称无禁用词Tutorial / How-to 含 PrerequisitesTutorial 含 What you learned 与 Next stepsHow-to 含 Result新页面已注册到 sidebar.js新页面设menuTag: new、实质性修改设menuTag: updated提及 Excel 时包含 Microsoft 商标免责声明TypeScript 示例已存在JS 通过npm run docs:code-examples:generate-js生成。另外需要注意docs/content/**下存在由生成器维护的内容块以!-- option-levels:start --/!-- option-levels:end --标记包裹编辑任何指南页面前应先搜索:start --标记避免在生成块内手改导致下次生成时被覆盖详见 AGENTS.md。深入阅读技能原文.claude/skills/writing-docs-pages/SKILL.md完整编辑规则docs/README-EDITING.md文档标准与风格指南docs/AGENTS.md真实指南页范例docs/content/guides/getting-started/installation/installation.mdSidebar 注册docs/content/guides/sidebar.js语法预处理实现docs/src/plugins/vuepress-preprocessor.mjs内容加载与示例渲染实现docs/src/plugins/framework-loader.mjs示例生成脚本docs/scripts/transpile-doc-example.mjs脚本入口docs/package.json【免费下载链接】handsontableJavaScript Data Grid / Data Table with a Spreadsheet Look Feel. Works with React, Angular, and Vue. Supported by the Handsontable team ⚡项目地址: https://gitcode.com/gh_mirrors/ha/handsontable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Handsontable 文档指南页编写规范：Frontmatter、框架示例嵌入与 Sidebar 注册全解析
Handsontable 文档指南页编写规范Frontmatter、框架示例嵌入与 Sidebar 注册全解析【免费下载链接】handsontableJavaScript Data Grid / Data Table with a Spreadsheet Look Feel. Works with React, Angular, and Vue. Supported by the Handsontable team ⚡项目地址: https://gitcode.com/gh_mirrors/ha/handsontable本文基于 Handsontable 官方文档仓库中的.claude/skills/writing-docs-pages/SKILL.md技能说明结合docs/目录下的真实页面如 installation.md、README-EDITING.md 编辑指南、AGENTS.md 文档标准以及src/plugins/下的预处理插件源码系统讲解如何为 Handsontable 文档站点编写、编辑和注册指南页面。读完本文你将掌握 YAML frontmatter 的完整字段语义、四类 Diátaxis 页面结构、::: only-for框架条件内容、::: example可运行示例容器的全部选项、写作风格红线、sidebar 注册流程以及 TypeScript 示例到 JavaScript 的自动化生成命令。Handsontable 文档站点构建在 Astro Starlight 之上同时保留了大量 VuePress 风格的 Markdown 语法::: only-for、::: example、[[toc]]等这些语法由自定义插件在构建期转换。因此理解写什么与底层如何解析同等重要——前者保证页面符合规范后者帮助你排查为什么我的页面没按预期渲染。1. Frontmatter每个.md文件的强制起点按照 SKILL.md 的约定docs/content/guides/下每个指南页面的.md文件都必须以 YAML frontmatter 开头--- title: Feature Name metaTitle: Feature Name - JavaScript Data Grid | Handsontable description: Short SEO description under 160 characters. permalink: /feature-name canonicalUrl: /feature-name tags: - keyword1 - keyword2 react: metaTitle: Feature Name - React Data Grid | Handsontable searchCategory: Guides category: Cell features # Must match a sidebar category exactly menuTag: new | updated # Optional; sidebar badge ---其中menuTag: new用于新建页面menuTag: updated用于对已有页面做实质性内容修改纯小修错别字、代码片段/链接修正以及 changelog、迁移指南页面则省略该字段且不要动已存在的标签。1.1 字段语义与默认值README-EDITING.md 给出了每个字段的完整语义标签含义默认值title页面标题渲染为 H1未设置时由父级页面标题生成permalink页面的唯一URL未设置时由 Markdown 文件名生成canonicalUrl页面最新版的 canonical URL无非必需metaTitle页面的 SEO meta 标题无非必需description页面的 SEO meta 描述无非必需tags文档搜索引擎使用的搜索标签无非必需react/angular仅作用于对应框架版本的替代 frontmatter 集合无非必需searchCategory搜索结果的分类默认归入 Guides 分类menuTag侧边栏菜单中页面标题旁的徽标无非必需category页面所属内容分类用于组织页面无非必需1.2 按框架差异化 frontmatter同一页面在不同框架版本下可以有不同的 meta 信息。例如 installation.md 的真实 frontmatter--- type: how-to title: Installation metaTitle: Installation - JavaScript Data Grid | Handsontable description: Install Handsontable through your preferred package manager, or import Handsontables assets directly from a CDN. permalink: /installation canonicalUrl: /installation tags: - quick start react: metaTitle: Installation - React Data Grid | Handsontable angular: metaTitle: Installation - Angular Data Grid | Handsontable vue: metaTitle: Installation - Vue Data Grid | Handsontable searchCategory: Guides category: Getting started ---可用的框架键为react和angularSKILL.md 所列不过实际页面中vue键也被使用。框架键下不仅可以覆盖metaTitle、description还能定义自定义值这些值可在模板中消费且仅对对应框架生效。1.3 必须声明的type字段AGENTS.md 要求每个页面必须在 frontmatter 中声明 Diátaxis 内容类型type: tutorial | how-to | reference | explanation四种类型对应读者不同的诉求Tutorial教学、How-to guide任务达成、Reference信息查阅、Explanation原理理解。如果一页内容横跨两种类型应拆分为独立页面。目录结构本身也隐含了类型预期guides/getting-started/为 How-toapi/为 Referencerecipes/为 Tutorial。2. 页面结构无 H1、Overview、TOC 与渐进式小节SKILL.md 明确了指南页的固定结构顺序正文中不写 H1——Starlight 会用 frontmatter 的title字段渲染页面标题。如果在 frontmatter 之后再写# Title或其他 H1页面上会出现重复标题。Overview 概述——---之后的第一段内容用 1-2 句话说明该功能是什么、为什么重要。[[toc]]——自动根据各级标题生成目录。这一宏由vuepress-preprocessor.mjs在构建期移除Starlight 本身会自动渲染目录见 vuepress-preprocessor.mjs// 2. Remove [[toc]] (Starlight renders a ToC automatically) result result.replace(/^\s*\[\[\s*toc\s*\]\]\s*$/gm, );渐进式小节——只使用##及以下层级按启用功能 → 基本用法 → 配置选项 → 高级用法 → 键盘快捷键 → 已知限制 → API 参考链接的顺序组织。2.1 分类型模板AGENTS.md 为四种 Diátaxis 类型分别提供了模板。以 How-to 为例其骨架为Prerequisites前置条件→ Steps有序步骤列表→ Result → Related。## Steps下的有序列表会自动被渲染为 Starlight 步骤列表rehype-migration-steps.mjs插件为紧随该标题的ol添加classsl-steps rolelist因此直接写普通 Markdown 有序列表即可无需手工添加任何标记。3. 框架特定内容::: only-for条件块指南页需要同时服务 JavaScript、React、Angular、Vue 四种框架。用::: only-for容器包裹只适用于某个框架的内容::: only-for javascript JavaScript-only content here. ::: ::: only-for react React-only content here. :::关键约定:::标记必须独占一行且内容块前后都要有空白行。3.1 底层实现该语法由 vuepress-preprocessor.mjs 中的filterOnlyForBlocks()实现且必须最先执行。它维护一个栈结构逐行扫描遇到::: only-for frameworks开启标记时判断当前框架是否在列表中遇到内部嵌套的其他:::容器如::: example、::: tip时递增innerDepth遇到裸:::闭合标记时递减。只有所有外层 only-for 帧都命中当前框架的内容行才会被保留输出其他框架的内容被整体移除。构建期框架解析的另一层证据在 framework-loader.mjs自定义 Astro 内容加载器会为每个content/下的.md文件生成 4 个条目JavaScript/React/Angular/Vue 各一并附带框架前缀例如react-data-grid/guides/getting-started/introduction。因此同一个源文件最终会渲染出四个框架版本。4. 示例嵌入::: example容器与[code]指令指南页最重要的能力是嵌入可运行的代码示例带实时预览。SKILL.md 给出的标准模式如下。JavaScript / TypeScript 示例--js 1 --ts 2设置标签页顺序::: only-for javascript ::: example #example1 --js 1 --ts 2 [code](https://link.gitcode.com/i/f8cd9ce504e4cd3aaef8b07f47db7ae3) [code](https://link.gitcode.com/i/3dced1c300e75843bada41ef967e7d76) ::: ::: ::: only-for react ::: example #example1 :react --tsx 1 --jsx 2 [code](https://link.gitcode.com/i/c32da7355ef2f182f8e8adb5ccf7153e) [code](https://link.gitcode.com/i/790e1b1f34dbc15ed836ef294f40cf32) ::: ::: ::: only-for vue ::: example #example1 :vue3 [code](https://link.gitcode.com/i/b586f7b92de6d1a60456b06fdd588212) ::: :::规则要点Vue 3嵌入单个 TypeScript SFCvue/example1.vue使用script setup langts使用:vue3预设功能需要额外依赖时可用:vue3-languages、:vue3-vuex。不要为新 Vue 示例使用--html/--js标签页。Angular使用:angular预设配合--ts 1 --html 2。4.1 容器选项完整参考README-EDITING.md 给出了example容器的完整选项表选项必需示例可选值用途#exampleId否#example1字符串容器唯一 ID.class否.new-class字符串容器自定义 CSS 类:preset否:hot:hot|:hot-lang|:hot-numbro|:react|:react-languages|:react-numbro|:react-redux|:react-advanced|:angular|:angular-languages|:angular-numbro|:vue3|:vue3-numbro|:vue3-languages|:vue3-vuex设定代码依赖--js pos否--js 1正整数默认1设置 JS 代码片段在容器中的位置--html pos否--html 2正整数默认0设置 HTML 代码片段位置0禁用 HTML 标签页--css pos否--css 2正整数默认0设置 CSS 代码片段位置0禁用 CSS 标签页--no-edit否--no-edit--no-edit移除Edit按钮--tab tab否--tab previewcode|html|css|preview设置默认打开的标签页4.2 真实页面中的用法以 installation.md 为例JavaScript 部分嵌入示例::: example #example1 --js 1 --ts 2 [code](https://link.gitcode.com/i/f8cd9ce504e4cd3aaef8b07f47db7ae3) [code](https://link.gitcode.com/i/3dced1c300e75843bada41ef967e7d76) :::对应的示例源文件为 example1.ts 与 example1.js——注意它们都包含了licenseKey: non-commercial-and-evaluation非商业用途许可这是文档代码示例的强制要求。4.3 底层渲染原理framework-loader.mjs 中的processExampleBlocks()在only-for过滤之后处理这些容器解析#exampleId、CSS 类、--code-only标志收集块内的code引用然后调用buildExampleHtml()生成最终输出。buildExampleHtml()framework-loader.mjs会依据目录路径/angular/、/react/、/vue/而非扩展名判断框架避免 JS 示例携带的.ts变体被误判为 Angular为可执行示例生成带 loading 骨架屏的实时预览区、Source code切换按钮、Edit in sandbox与See on GitHub链接将 JSTS或 JSXTSX脚本归入同一个 JavaScript 标签页支持语言下拉切换HTML、CSS 作为独立标签页对无运行入口的服务端代码PHP、Python、Ruby 等退化为纯代码围栏展示。5. 写作风格Voice 与 Style 红线写作风格细则完整收录于 AGENTS.md文档站点专用覆盖了 monorepo 级规范.ai/DOC-STANDARDS.md中与之冲突的部分。SKILL.md 提炼的关键点主动语态、美式英语、短句。以 you 称呼读者绝不使用 we三个及以上并列项使用 Oxford comma牛津逗号。禁用评价性形容词easy、simple、obvious。用连字符-或双连字符--分隔从句不用 en dash——这是文档站点约定与 JSDoc/changelog 使用 en dash 不同。UI 元素加粗如Add commentAPI 名称用行内代码如comments。内部链接使用text语法。每个句子包括列表项以句号结尾。AGENTS.md 补充的禁用词表simply、just、easy、straightforward、note that、please、allows you to改用 lets you 或主动改写、in order to改用 to、utilize改用 use。标题与 frontmattertitle一律使用句首大写sentence case只大写首词、专有名词、产品名、API 标识符与缩略词例如Use a cell renderer而非Use a Cell Renderer。只使用直引号和禁用弯引号。6. 商标规则凡页面提到 Excel必须在页面底部包含 Microsoft/Excel 商标免责声明同时提到 Google Sheets 的页面使用同时覆盖两个商标的扩展版免责声明。免责声明以 callout 或脚注形式放在页面底部详见 AGENTS.md。7. 内部链接与模板变量7.1/链接语法README-EDITING.md 规定内部链接禁止使用绝对链接或相对 URL统一采用/前缀text规则细节后跟目标文件相对当前版本根目录的路径如[Clipboard](https://link.gitcode.com/i/982e12cdaa72855756623caf50420dc2)目标文件名必须带.md扩展名如Autofill需要定位小节时使用锚点如Core跨框架链接在后加框架名[React methods](https://link.gitcode.com/i/db6b3d7e432276592f8d23137f2ea49e)目标文件必须定义了permalinkfrontmatter若生成 URL 失败输出为相对链接兜底未指定框架时链接指向当前浏览的框架版本。链接中的/前缀由预处理插件统一转换为绝对路径见 vuepress-preprocessor.mjs。7.2 模板变量AGENTS.md 规定了五个构建期解析的模板变量用于避免在文档中硬编码 GitHub 分支名所有变量在 template-variables.mjs 中声明与替换变量生产构建其他构建用途{{$examplesBranch}}prod-examples/majormasterhandsontable/examples启动模板源码{{$currentMinorVersion}}prod-docs/major.minordevelophandsontable/handsontable源码链接{{$currentVersion}}package.json 版本0.0.0-next-sha-date版本字符串、runner 链接{{$latestChangelogVersion}}最新changelog-N主版本相同最新 changelog 页链接{{$basePath}}根相对资源路径硬编码tree/master链接会让旧版本文档的读者跳转到与版本不匹配的模板AGENTS.md 中的 DEV-2214因此必须使用模板变量。唯一例外是server-side-*recipes 保留tree/master/server-examples/...。8. Sidebar 注册让新页面出现在导航中创建新页面后必须将其加入 sidebar.js。在正确的分类数组中插入条目{ path: guides/category/feature-name/feature-name }若页面仅面向特定框架使用onlyFor{ path: guides/getting-started/react-methods/react-methods, onlyFor: [react] }, { path: guides/getting-started/angular-hot-instance/angular-hot-instance, onlyFor: [angular] }, { path: guides/getting-started/vue3-hot-reference/vue3-hot-reference, onlyFor: [vue] },未在 sidebar.js 中注册的页面不会出现在导航中AGENTS.md。注意页面的categoryfrontmatter 必须与 sidebar 的分类标题精确匹配。侧边栏的New / Updated徽标由menuTag字段驱动与 sidebar.js 无关。9. 代码示例生成与质量校验9.1 TypeScript 优先JavaScript 自动生成SKILL.md 规定JavaScript 和 React 示例先编辑 TypeScript 源文件.ts或.tsx再从docs/目录生成 JavaScript 变体cd docs npm run docs:code-examples:generate-js -- path-to-ts-file路径相对于docs/例如content/recipes/foo/javascript/example1.ts。该命令对应 package.json 中的docs:code-examples:generate-js实际由 transpile-doc-example.mjs 执行。Vue 示例则直接在.vue文件中编写 TypeScriptscript setup langts没有单独的 JS 文件需要生成。9.2 示例质量规则AGENTS.md 对示例代码提出了硬性要求所有代码块必须带语言标签javascript、typescript、html、css、shell、json、yaml禁止无标签代码块使用const和let禁用varnew Handsontable(...)调用必须包含licenseKey: non-commercial-and-evaluation发布示例中禁止行内// TODO或// ...注释示例控制在 25-60 行之间超出则改为链接到在线沙箱禁止占位数据foo、bar、A1、Column1、test等必须使用领域真实数据财务、HR、库存、分析、项目管理、科学等领域且至少 5 行数据以便功能可见Angular 示例必须使用standalone: true模式CSS 走--css槽位JIT 无法在运行时解析styleUrls、模板内联、构造函数禁止注入服务改用inject()、Hooks 放进gridSettings而非模板事件绑定、使用for/if/switch内置控制流。9.3 相关校验命令命令用途npm run docs:code-examples:generate-js -- path由 TS 生成 JS 示例npm run docs:test:plugins运行预处理插件单元测试npm run docs:lintESLint 检查src与contentnpm run docs:validate-changelog-links校验 changelog 中的/api/链接npm run build依次执行docs:api、docs:validate-highlights、astro build与层序校验npm run dev本地开发服务器.md与示例源文件支持热重载10. 提交前的自查清单AGENTS.md 提供了文档 PR 的标准检查清单关键条目包括frontmatter 已添加type:字段tutorial | how-to | reference | explanation且使用了对应类型的 Diátaxis 模板标题符合类型命名约定How-to 以 How to ... 开头Explanation 以 Understanding ... 开头无禁用占位数据、所有示例数据领域真实且前后一致所有代码块带语言标签、无var、示例含licenseKey标题层级无跳级如 H2 → H4、标题与title:使用句首大写全文主动语态 第二人称无禁用词Tutorial / How-to 含 PrerequisitesTutorial 含 What you learned 与 Next stepsHow-to 含 Result新页面已注册到 sidebar.js新页面设menuTag: new、实质性修改设menuTag: updated提及 Excel 时包含 Microsoft 商标免责声明TypeScript 示例已存在JS 通过npm run docs:code-examples:generate-js生成。另外需要注意docs/content/**下存在由生成器维护的内容块以!-- option-levels:start --/!-- option-levels:end --标记包裹编辑任何指南页面前应先搜索:start --标记避免在生成块内手改导致下次生成时被覆盖详见 AGENTS.md。深入阅读技能原文.claude/skills/writing-docs-pages/SKILL.md完整编辑规则docs/README-EDITING.md文档标准与风格指南docs/AGENTS.md真实指南页范例docs/content/guides/getting-started/installation/installation.mdSidebar 注册docs/content/guides/sidebar.js语法预处理实现docs/src/plugins/vuepress-preprocessor.mjs内容加载与示例渲染实现docs/src/plugins/framework-loader.mjs示例生成脚本docs/scripts/transpile-doc-example.mjs脚本入口docs/package.json【免费下载链接】handsontableJavaScript Data Grid / Data Table with a Spreadsheet Look Feel. Works with React, Angular, and Vue. Supported by the Handsontable team ⚡项目地址: https://gitcode.com/gh_mirrors/ha/handsontable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考