OpenParable
Skip to content
← Back to skills

Writing Docs Pages

Documents
writing-docs-pages

Writing Docs Pages is an Agent Skill for documents published in the handsontable/handsontable repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when creating or editing documentation pages in docs/content/guides/ - covers YAML frontmatter, page structure, framework-specific example embedding, writing style, and sidebar registration

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/handsontable/handsontable/blob/HEAD/.claude/skills/writing-docs-pages/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/writing-docs-pages, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Writing Documentation Pages

This skill covers how to create and edit guide pages in docs/content/guides/.

1. Frontmatter (required)

Every .md file starts with 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
---

Set menuTag: new when you create a new page and menuTag: updated when you make a substantive content change to an existing page. Omit it for trivial fixes (typos, snippet/link corrections) and for changelog and migration-guide pages; leave any existing tag in place.

2. Page Structure

Follow this order consistently:

  1. No H1 in the Markdown body - Starlight renders the page heading from the title frontmatter field. Do not add # Title (or any other H1) after the frontmatter, or the title appears twice on the page.
  2. Overview - start with 1-2 sentences describing what the feature does and why it matters (first content after ---).
  3. [[toc]] - auto-generates a table of contents from headings.
  4. Progressive sections - use ## and below only, ordered from basic to advanced: Enable the feature, Basic usage, Configuration options, Advanced usage, Keyboard shortcuts, Known limitations, API reference links.

3. Framework-Specific Content

Wrap content that applies to only one framework:

::: only-for javascript

JavaScript-only content here.

:::

::: only-for react

React-only content here.

:::

Important: The ::: markers must be on their own lines with blank lines before and after the content block.

4. Example Embedding

Embed runnable code examples using this pattern. The --js 1 --ts 2 flags set tab order.

::: only-for javascript

::: example #example1 --js 1 --ts 2
@[code](@/content/guides/category/feature/javascript/example1.js)
@[code](@/content/guides/category/feature/javascript/example1.ts)
:::

:::

::: only-for react

::: example #example1 :react --tsx 1 --jsx 2
@[code](@/content/guides/category/feature/react/example1.tsx)
@[code](@/content/guides/category/feature/react/example1.jsx)
:::

:::

::: only-for vue

::: example #example1 :vue3

@[code](@/content/guides/category/feature/vue/example1.vue)

:::

:::

Vue 3: Embed a single TypeScript SFC (vue/example1.vue with <script setup lang="ts">). Use the :vue3 preset (or :vue3-languages, :vue3-vuex when the feature needs extra dependencies). Do not use --html / --js tabs for new Vue examples. See skill creating-docs-examples for the full Vue SFC pattern.

Angular: Use :angular with --ts 1 --html 2.

5. Writing Style

Full site voice and the words-to-avoid list are in docs/AGENTS.md §2.2 (the docs-site override of the monorepo standards in .ai/DOC-STANDARDS.md). Key points for pages:

  • Active voice, American English, short sentences.
  • Address the reader as "you", never "we". Use the Oxford comma.
  • No evaluative adjectives ("easy", "simple", "obvious").
  • Use hyphens (-) or double hyphens (--) to separate clauses, not en dashes — this is the docs-site convention (unlike JSDoc/changelog, which use en dashes).
  • Bold for UI elements: Add comment. Inline code for API names: comments.
  • Internal links: [text](@/path/to/file.md#anchor) syntax.
  • End every sentence with a full stop, including in lists.

6. Trademark Rules

Pages mentioning "Excel" must include the Microsoft/Excel trademark disclaimer at the bottom. Pages that also mention "Google Sheets" use the expanded disclaimer covering both trademarks.

7. Sidebar Registration

After creating a new page, add it to docs/content/guides/sidebar.js. Find the correct category array and insert an entry:

{ path: 'guides/category/feature-name/feature-name' }

Use onlyFor: ['react'] or onlyFor: ['angular'] if the page is framework-specific.

8. Code Example Generation

For JavaScript and React examples, edit the TypeScript source first (.ts or .tsx). Then generate the JavaScript variant from the docs/ directory:

cd docs && npm run docs:code-examples:generate-js -- <path-to-ts-file>

Use a path relative to docs/ (for example content/recipes/foo/javascript/example1.ts).

For Vue examples, write TypeScript directly in the .vue file (<script setup lang="ts">). There is no separate JS file to generate.

Reference

See docs/README-EDITING.md for the complete editing rules, including all frontmatter tags, container syntax, and content formatting details.