Write Tabler Docs

Follow the current Tabler documentation schema. How far to go depends on how the skill was triggered — see section 1.

1. Scope and behavior

• Works for any docs page type under docs/content/** (components, utilities, forms, layout, plugins, base, getting started, emails, illustrations, icons, index pages). Pages are MDX: leaf pages foo.mdx, parents with sub-pages foo/index.mdx.
• Edit existing pages when the user asks to document new functionality in an existing component/page.
• Create new pages when needed.
• Use simple English in all prose.

Direct request vs. proactive suggestion

• If the user explicitly asked for docs (e.g. "document this", "write docs for X", "update the badge page"), write directly in the files — do not stop at draft mode.
• If this skill triggered on its own because something was built or changed without matching docs, don't start editing files unprompted. Point out what's missing in one or two sentences (which component/plugin, which page it would live under) and ask whether to write it. Proceed to write directly, per the rule above, only once the user says go.

2. Required language style (simple English)

• Use short sentences and common words.
• Keep one main idea per sentence when possible.
• Prefer direct verbs: Use, Add, Set, Show.
• Avoid buzzwords and marketing filler.
• Keep paragraphs short and easy to scan.

3. Frontmatter rules

Default frontmatter (required unless user asks otherwise):

---
title: ...
summary: ...
description: ...
---

Rules:

• Keep frontmatter static YAML only.
• No layout: key — docs/pages/[...slug].astro renders every page.
• By default, include only title, summary and description.
• Add extended keys only when the user explicitly asks for them or nearby pages in the same category use them. The full set is seoTitle, seoDescription, icon, order, related, docs-libs, css-plugins, hide-pagination, added-in — the collection schema in docs/content.config.ts is strict, so anything else fails the build.

4. Documentation schema to follow

Use this section order as the default structure:

1. ## Overview
2. ## Installation (optional)
3. ## Variants or ## Usage (choose one based on page type)
4. ## Examples (optional)
5. ## Accessibility
6. ## SCSS variables (optional)
7. ## Migration notes (optional)

Guidance by page type:

• Component-like pages: prefer Variants.
• Utility or workflow pages: prefer Usage.
• Library/package pages (for example icons, emails): keep Installation + Usage.
• Intro/index pages: may use concise overview sections, but keep hierarchy clear and consistent.

5. Example and snippet pattern

For visual examples, use the shared Example component (import after the frontmatter):

import Example from '@components/Example.astro';

<Example>
<button class="btn btn-primary">Primary button</button>
</Example>

• Add 1-2 short sentences before each preview block to explain what the preview shows.
• Use props when useful: hideCode, centered, vertical, raw, column, bg, height, codeOnly.
• For a cleaner displayed snippet than the rendered preview, pass code={...}.
• For icons and other shared components inside examples, import them from @ui/ (for example <Icon name="plus" />).
• Raw HTML in the Example slot is reserialized by MDX — keep markup lines attached to tags to avoid stray <p> wrapping.

6. Analyzing the component or plugin source

Prose and example markup are only as accurate as their source. Before writing examples, ground them in the actual implementation rather than in guesses or in what a similar-looking page happens to show — nearby .mdx pages are a good style reference but can drift out of sync with the code.

• UI components live at shared/ui/<ComponentName>.astro. Read its interface Props block: each field (and its JSDoc comment, when present) is the authoritative list of supported options, defaults, and edge cases — for example shared/ui/Badge.astro documents scale, light, icon, and personId this way.
• Plugins and utilities are often CSS-class-driven rather than a single Astro component. Check core/scss/**/_<name>.scss (or core/scss/tabler-<name>.scss) for the class variants that actually exist, and shared/data/<name>.json when the plugin is data-driven (e.g. flags, payments, social-icons).
• Real usage in preview/pages/** renders the finished HTML and often exercises more combinations in practice than the docs page does — a useful cross-check for realistic examples.
• Turn what you find into <Example> blocks that reflect real, valid prop/class combinations rather than invented markup.

7. Registering new pages in the docs menu

docs/content/** is not scanned automatically to build navigation — the sidebar tree is frozen in shared/data/docs.json (see the comment in docs/components/DocsMenu.astro). A new leaf page with no entry there exists but is unreachable from the docs site.

• Only touch docs.json for genuinely new pages. Editing an existing page needs no menu change.
• Find the matching section in the menu array by directory: docs/content/ui/components/* → the "Components" entry under "Tabler UI", docs/content/ui/plugins/* → "Plugins", docs/content/icons/libraries/* → "Libraries" under "Tabler Icons", and so on — the section title/url pairs mirror the docs/content/ui/* and docs/content/icons/* subdirectory names.
• Add { "title": "<Title Case name>", "url": "/<matching>/<slug>" } to that section's children, in the same alphabetical position its neighbors already follow.
• No trailing slash on url. The menu compares it against the page url, which never has one, so a trailing slash silently breaks the active-item highlight for that page.
• The title and url must match the new page's frontmatter title and its file path exactly, or the sidebar entry will point at the wrong place.

7a. Linking a new page from the demo page

Every component with a page in preview/pages/** shows a "Documentation" button in its page header, rendered by DocsLink. A new docs page is easy to forget here, and the demo page then looks undocumented even though the docs exist.

• After creating docs/content/ui/components/<name>.mdx (or a plugin page), open preview/pages/<name>.astro and add, as a direct child of <DefaultLayout>:

import DocsLink from '@ui/DocsLink.astro'
…
<DocsLink slot="page-header-actions" path="/ui/components/<name>" />

• path is the docs path without the extension, the same string as the url in docs.json.
• pnpm run check:docs-links resolves every DocsLink against docs/content/** and fails on a typo, so run it after adding one.
• When there is no demo page yet, say so — the demo-pages skill covers building one.

8. Workflow for each request

1. Identify target file(s) in docs/content/** (or determine none exist yet — see section 7).
2. Read the target page and 2-3 nearby pages in the same category to match tone and conventions.
3. Read the underlying component/plugin source per section 6 so examples are accurate, not guessed.
4. Apply the schema from section 4.
5. Write/update the page directly in file(s).
6. If the page is new, add its entry to shared/data/docs.json per section 7.
7. If the page is new, link it from the matching demo page in preview/pages/<name>.astro per section 7a.
8. Keep only required frontmatter by default.
9. Ensure prose is in simple English.
10. Verify heading hierarchy (## then ###) and snippet validity.

8a. Checking a page on the published site

Two hosts serve the docs, and they are not in sync:

Check a page's live url on docs-dev.tabler.io. Production still serves the pre-content-collection urls, so a page that exists in docs/content/** can return 404 there while being perfectly fine. A 404 on docs.tabler.io alone never justifies renaming a page or rewriting a link — confirm on docs-dev.tabler.io first.

9. Rules while updating existing docs

• Preserve valid existing content that is still correct.
• Add new functionality docs as focused new subsection(s), usually under Variants, Usage, or Examples.
• Remove or rewrite only conflicting or outdated text.
• Keep naming and terms consistent across the page.

10. Quality checklist before finishing

• Uses simple English.
• Examples reflect the real Props/classes found in the source (section 6), not guesses.
• Frontmatter uses static YAML.
• Default frontmatter contains only title, summary, description, layout (unless user requested extra keys).
• Follows schema and heading hierarchy.
• Examples use the Example component pattern where applicable.
• Accessibility section exists for interactive UI docs.
• New pages have a matching entry in shared/data/docs.json (section 7); edits to existing pages don't touch it.
• New pages are linked from their demo page with DocsLink (section 7a), and pnpm run check:docs-links passes.
• No mention of changeset reminders unless user asks.