@developerhub/dh-skills 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeveloperHub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @developerhub/dh-skills
+
+Agent Skills that teach AI coding agents how to author
+**[DeveloperHub](https://developerhub.io) Markdoc** — the exact, round-trip-safe
+syntax for every content block.
+
+DeveloperHub pages are stored as Markdoc. When an agent edits a page from an IDE,
+a Git-synced repo, or a docs-as-code pipeline, it needs to emit the *canonical*
+dialect DeveloperHub round-trips — not generic Markdown or a look-alike. Emit the
+wrong shape and the edit churns on the first save or silently drops content. This
+skill gives the agent that ground truth.
+
+## What's inside
+
+| Skill | Teaches |
+|---|---|
+| [`write-markdoc`](skills/write-markdoc/SKILL.md) | Every DeveloperHub Markdoc block and inline mark, with the exact syntax, attributes, and the dialect rules that keep an edit round-trip-safe. |
+
+Detailed per-block reference: [`skills/write-markdoc/references/blocks.md`](skills/write-markdoc/references/blocks.md).
+
+## Install
+
+Install straight from this repo with the [`skills` CLI](https://www.npmjs.com/package/skills):
+
+```bash
+npx skills add developerhub-io/dh-skills
+```
+
+Or copy the `skills/write-markdoc` folder into your agent's skills directory
+(`.claude/skills/`, `.cursor/skills/`, …). `SKILL.md` uses the portable Agent
+Skills format (Markdown with YAML frontmatter), so it works across Claude Code,
+Cursor, Codex, and other compatible agents.
+
+It is also published to npm as `@developerhub/dh-skills`, for anyone who prefers to
+vendor the files as a dependency (`npm install @developerhub/dh-skills`).
+
+## Contributing
+
+This package is published and maintained by DeveloperHub. Spotted an error, or
+want a block documented differently? Please [open an issue](https://github.com/developerhub-io/dh-skills/issues).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@developerhub/dh-skills",
+  "version": "1.0.2",
+  "description": "Agent Skills that teach AI coding agents to author DeveloperHub Markdoc — the exact syntax for every content block.",
+  "keywords": [
+    "developerhub",
+    "markdoc",
+    "documentation",
+    "agent-skills",
+    "claude",
+    "ai",
+    "docs-as-code"
+  ],
+  "homepage": "https://developerhub.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerhub-io/dh-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/developerhub-io/dh-skills/issues"
+  },
+  "license": "MIT",
+  "author": "DeveloperHub <hello@developerhub.io> (https://developerhub.io)",
+  "files": [
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/write-markdoc/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: write-markdoc
+metadata:
+  version: "1.0"
+description: >-
+  Write, author, edit, and format DeveloperHub documentation pages in the correct
+  Markdoc syntax. Use whenever a task involves creating or editing a DeveloperHub
+  docs page; writing page frontmatter; inserting or formatting a callout, code
+  block, table, image, tabs, accordion, cards, video, badge, icon, or any other
+  Markdoc block or inline tag; or when you need the exact syntax, attributes,
+  defaults, or allowed values for a DeveloperHub Markdoc tag.
+---
+
+# Writing DeveloperHub Markdoc
+
+DeveloperHub pages are authored in **Markdoc** — a superset of Markdown with a set
+of typed custom tags. The same format is used when editing a page through the
+editor, an API/AI edit, or a Git-synced repository: what you write is parsed into
+the editor's document model, and what the editor produces is serialised back to
+this exact syntax. Getting the shape right keeps that round-trip **lossless** —
+emit a non-canonical shape and the edit churns on the first save or silently drops
+content.
+
+This skill is the ground truth for the syntax. For the full per-tag reference
+(every attribute, default, and allowed value), read
+[`references/blocks.md`](references/blocks.md).
+
+## Core dialect rules
+
+These hold for every tag. Break one and the round-trip breaks.
+
+1. **Block tags sit on their own lines.** The open tag, the body, and the close
+   tag are each on separate lines. Content on the same line as `{% tag %}`
+   silently downgrades the tag to a plain paragraph.
+   ```markdoc
+   {% callout title="Note" %}
+   Body goes here.
+   {% /callout %}
+   ```
+2. **Inline tags are self-closing:** `{% icon classes="fas fa-star" /%}`.
+3. **Booleans are bare, never quoted.** `open=true`, `showLineNumbers=false`. A
+   quoted boolean (`open="false"`) becomes the truthy *string* `"false"` and
+   silently inverts the setting.
+4. **Numbers are bare too:** `width=357`, `colspan=2`. Strings are quoted:
+   `title="Warning"`.
+5. **Omit any attribute that equals its default.** The serialiser drops them, so
+   adding them back only makes diffs noisier. The defaults are listed per tag in
+   `references/blocks.md`. It is never *wrong* to include one; just match the
+   surrounding page.
+6. **Internal links carry real text:** `[Getting started](/support-center/start)`.
+   A text-less link round-trips to nothing.
+7. **Asset references stay verbatim.** An image `url="asset:zvlxyph4f37t"` is kept
+   as-is; never resolve it to a URL. (Full `https://uploads.developerhub.io/…`
+   URLs are also valid — use whichever the surrounding pages use.)
+8. **Reserve `#` (H1) for the page title.** Body headings start at `##`.
+
+## Standard Markdown
+
+Plain Markdown works and is preferred wherever a custom tag is not needed:
+
+- Headings `##` … `######`
+- `**bold**`, `*italic*`, `~~strikethrough~~`, `` `inline code` ``
+- `[links](/support-center/slug)` — root-relative for internal links
+- Bullet (`-`) and ordered (`1.`) lists, including nested
+- `> blockquote`
+- `---` horizontal rule
+- Fenced code blocks (see the reference)
+
+Two things have no Markdown equivalent, so they are tags:
+
+- **Underline:** `{% u %}underlined{% /u %}`
+- **A link whose URL contains spaces or parentheses:**
+  `{% link href="https://x.com/a (b)" %}text{% /link %}`
+
+## The blocks at a glance
+
+| Tag | Form | Purpose |
+|---|---|---|
+| `callout` | block | Coloured note / warning box |
+| `code` + fences | block | Multi-language code tabs |
+| ` ```lang ` fence | fence | A single code block |
+| `code-steps` | block | Stepped code walkthrough |
+| `table` / `row` / `cell` | block | Rich table (spans, alignment, backgrounds) |
+| `image` | block | Image, with optional caption |
+| `video` | block | Embedded / raw video |
+| `tabs` / `tab` | block | Tabbed content |
+| `accordion-group` / `accordion` | block | Collapsible sections |
+| `cards` / `card` | block | Card grid or list |
+| `conditional` | block | Audience-gated content |
+| `html` | block | Raw custom HTML |
+| `github-code` | block | Code pulled live from a GitHub URL |
+| `index-list` | block | Auto index of child pages |
+| `synced` | block | Reusable synced block, by id |
+| `badge` | inline | Small coloured label |
+| `key` | inline | Keyboard key |
+| `icon` | inline | Font Awesome icon |
+| `glossary` | inline | Glossary term |
+| `inline-image` | inline | Inline image |
+| `%KEY%` | inline | Variable placeholder |
+
+## Cheat sheet
+
+One of (almost) every block. Full attribute lists in
+[`references/blocks.md`](references/blocks.md).
+
+````markdoc
+## A heading
+
+A paragraph with **bold**, *italic*, and a [link](/support-center/blocks).
+
+{% callout type="warning" title="Heads up" %}
+A coloured note box. `type` is one of info, warning, success, error.
+{% /callout %}
+
+{% code %}
+```php {% title="PHP" %}
+echo 'first tab';
+```
+
+```javascript {% title="JS" %}
+console.log('second tab');
+```
+{% /code %}
+
+```js {% showLineNumbers=true title="Example" %}
+const ready = true;
+```
+
+{% table layout="auto" %}
+{% row %}
+{% cell header=true %}
+Header
+{% /cell %}
+{% cell header=true %}
+Header
+{% /cell %}
+{% /row %}
+{% row %}
+{% cell %}
+Cell
+{% /cell %}
+{% cell %}
+Cell
+{% /cell %}
+{% /row %}
+{% /table %}
+
+{% image url="asset:zvlxyph4f37t" width=357 %}
+Optional caption.
+{% /image %}
+
+{% video provider="raw" videoId="https://uploads.developerhub.io/example.mp4" /%}
+
+{% tabs %}
+{% tab title="Android" %}
+Android content.
+{% /tab %}
+{% tab title="iOS" %}
+iOS content.
+{% /tab %}
+{% /tabs %}
+
+{% accordion-group %}
+{% accordion title="Getting started" open=true %}
+Collapsible content. Add `open=true` to expand it on load.
+{% /accordion %}
+{% accordion title="Advanced" %}
+Second section.
+{% /accordion %}
+{% /accordion-group %}
+
+{% cards %}
+{% card title="Card 1" text="Description" link="/support-center/videos" /%}
+{% card title="Card 2" text="Description" link="/support-center/callouts" /%}
+{% /cards %}
+
+{% conditional audience="enterprise" %}
+Shown only to the enterprise audience.
+{% /conditional %}
+
+{% github-code url="https://github.com/acme/repo/blob/main/Makefile" /%}
+
+{% index-list /%}
+
+{% synced id="open-block-menu" /%}
+
+{% html %}
+<div style="background:red; height:50px">Custom widget</div>
+{% /html %}
+
+---
+
+Inline: %product% and {% glossary term="coding" /%} and
+{% badge text="Done" type="success" /%} and {% icon classes="fas fa-adjust" /%}
+and {% key key="F1" /%} and {% inline-image url="asset:02grc2jqacve" width=14 /%}.
+````
+
+## When to use which block
+
+| You want to… | Use | Not |
+|---|---|---|
+| Highlight a note, tip, or warning | `callout` (`type=`) | bold text |
+| Show the same code in several languages | `code` with fenced tabs | one fence with mixed code |
+| Walk through code step by step | `code-steps` | a numbered list of fences |
+| A table with spans, alignment, or cell colours | `table` / `row` / `cell` | a GFM pipe table (it is rewritten) |
+| Group alternative content the reader switches between | `tabs` / `tab` | headings |
+| Collapse optional / long detail | `accordion-group` / `accordion` | `tabs` |
+| A grid of navigation links | `cards` / `card` | a bullet list of links |
+| Content for one audience only | `conditional` (`audience=`) | duplicating the page |
+| A reusable snippet shared across pages | `synced` (`id=`) | copy-paste |
+
+## Round-trip gotchas
+
+These follow from the two-way sync. Ignoring them drops or mangles content on the
+next save.
+
+- **Keep block open/close tags on their own lines** (rule 1). This is the most
+  common mistake.
+- **Tables are `row` / `cell` trees**, not Markdown pipes. A pipe table is
+  accepted on input but rewritten into the `{% table %}` form on the next save,
+  so don't be surprised when your pipe grid comes back expanded.
+- **Multi-language code is `{% code %}` wrapping bare fences**, each annotated with
+  `{% title="…" %}`. There is **no** `{% tab %}` inside `{% code %}` — that tag is
+  only for generic content tabs.
+- **Line-number / wrap settings ride on the `{% code %}` open tag**, once, shared
+  by every tab — not per fence.
+- **Accordions collapse by default.** Add a bare `open=true` to expand one on load.
+- **An intentionally empty paragraph** serialises as `{% p /%}`. You rarely write
+  this by hand.
+- **Custom HTML is best kept to a single logical line.** Multi-line *indented* HTML
+  in `{% html %}` can lose its indentation on round-trip.
+- **`conditional audience="…"` must name a real project audience.** Omit the
+  attribute for public / all-audiences content.
+
+## Page frontmatter
+
+A page stored as a `.md` file (a Git-synced repo, or an export) opens with a YAML
+`--- … ---` block, then a blank line, then the Markdoc body. The field set is
+**fixed** — the same keys on every page, not project-specific — so keep the block
+intact and edit the values in place; put the Markdoc body after it.
+
+```yaml
+---
+type: page
+title: Getting started
+listed: true
+slug: getting-started
+description:
+index_title: Getting started
+hidden:
+keywords:
+tags:
+---
+```
+
+| Field | Meaning |
+|---|---|
+| `type` | `page` for a content page. An index entry may instead be `category`, `label`, `separator`, or `link`; those carry fewer fields (`category`/`label` → `type` + `title`; `separator` → `type`; `link` → `type` + `title` + `url`). |
+| `title` | The page title (its `#` H1). |
+| `listed` | `true` / `false` — whether the page appears in navigation. Defaults to `true` when omitted. |
+| `slug` | URL slug. For a Git-synced page the file path *is* the slug, so this field is informational; renaming the file is what changes the URL. |
+| `description` | Meta / SEO description. Left empty when unset. |
+| `index_title` | Overrides the title shown in the sidebar / index; falls back to `title`. |
+| `hidden` | `true` / `false` — hide the page from the auto-generated index. Defaults to `false`. |
+| `keywords` | Comma-separated search keywords. |
+| `tags` | Comma-separated page tags. |
+
+**Preserve every key, even when its value is empty** — the format writes them all.
+This skill covers the body; leave the frontmatter block in place and change only the
+values you mean to change.

package/skills/write-markdoc/references/blocks.md

@@ -0,0 +1,467 @@
+# DeveloperHub Markdoc — full block & tag reference
+
+Every DeveloperHub Markdoc tag, its form, attributes, defaults, and allowed
+values. Read [`../SKILL.md`](../SKILL.md) first for the core dialect rules.
+
+**Conventions used below**
+
+- **Form** — `block` (`{% x %}…{% /x %}`), `inline` (`{% x /%}`, self-closing), or
+  `fence` (a fenced code block with `{% … %}` annotations).
+- **Default** — omit the attribute when its value equals this; the serialiser does.
+- Booleans are **bare** (`open=true`); numbers are bare (`width=357`); strings are
+  quoted (`title="Note"`).
+
+---
+
+## Text & inline marks
+
+Prefer plain Markdown for all of these.
+
+| Construct | Syntax |
+|---|---|
+| Bold | `**bold**` |
+| Italic | `*italic*` |
+| Strikethrough | `~~struck~~` |
+| Inline code | `` `code` `` |
+| Underline | `{% u %}underlined{% /u %}` (no Markdown equivalent) |
+| Link | `[text](/support-center/slug)` |
+| Link with spaces/parens in URL | `{% link href="https://x.com/a (b)" %}text{% /link %}` |
+| Heading | `##` … `######` (reserve `#` for the page title) |
+| Bullet list | `- item` (nest by indenting) |
+| Ordered list | `1. item` |
+| Blockquote | `> quoted` |
+| Horizontal rule | `---` |
+| Empty paragraph | `{% p /%}` (rarely authored by hand) |
+
+Links must carry real text — a text-less link round-trips to nothing.
+
+---
+
+## Blocks
+
+### `callout`
+
+Coloured note / warning box. Body holds arbitrary block content.
+
+```markdoc
+{% callout type="warning" title="Changing hosting settings" %}
+Redirect any external links if you change hosting after publishing.
+{% /callout %}
+```
+
+| Attr | Type | Default | Values |
+|---|---|---|---|
+| `type` | enum | `info` | `info`, `warning`, `success`, `error` |
+| `title` | string | `""` | rendered as a header row when set |
+
+> The type for a red/error box is **`error`**, not "danger".
+
+### `code` (multi-language tabs)
+
+Wraps one or more **bare fenced blocks**, each a language tab. There is **no**
+`{% tab %}` inside `{% code %}`. Line-number and wrap settings ride on the open
+tag, once, shared by every tab.
+
+````markdoc
+{% code showLineNumbers=true %}
+```javascript {% title="JavaScript" %}
+console.log("hi");
+```
+
+```python {% title="Python" %}
+print("hi")
+```
+{% /code %}
+````
+
+| Attr | Type | Default | Notes |
+|---|---|---|---|
+| `showLineNumbers` | boolean | `false` | shared by all tabs |
+| `wrapLine` | boolean | `true` | shared by all tabs |
+
+Content model: **only** bare code fences.
+
+### Fenced code block (single)
+
+A single code block. Language on the info string; annotations in `{% … %}` after
+it.
+
+````markdoc
+```javascript {% title="fibonacci.js" showLineNumbers=true highlightLines="2,4-6" %}
+function fibonacci(num) {
+  return num <= 1 ? 1 : fibonacci(num - 1) + fibonacci(num - 2);
+}
+```
+````
+
+| Annotation | Type | Default | Notes |
+|---|---|---|---|
+| `title` | string | `Code` | shown in the block header |
+| `showLineNumbers` | boolean | `false` | omit inside `{% code %}` (set it there) |
+| `wrapLine` | boolean | `true` | omit inside `{% code %}` |
+| `highlightLines` | string | `""` | e.g. `"1,3-5"` |
+| `id` | string | — | only inside `code-steps` (see below) |
+
+The language comes from the fence token itself (` ```js `); default `plaintext`.
+
+### `code-steps`
+
+A stepped walkthrough: a lead description, then `{% step %}` tags, then one fenced
+language block per step. Each fence carries an `id` that a step's `codeId` points
+at.
+
+````markdoc
+{% code-steps title="Set up the client" %}
+Intro prose describing the walkthrough.
+
+{% step title="Install" codeId="install" %}
+Install the package.
+{% /step %}
+
+```bash {% id="install" title="Terminal" %}
+npm install @acme/sdk
+```
+{% /code-steps %}
+````
+
+`code-steps` attrs:
+
+| Attr | Type | Default |
+|---|---|---|
+| `title` | string | `Code Steps` |
+
+`step` attrs:
+
+| Attr | Type | Default | Notes |
+|---|---|---|---|
+| `title` | string | `""` | |
+| `codeId` | string | `""` | matches a fence `id` in this block |
+| `highlightLines` | string | `""` | |
+
+Inside `code-steps`, a language fence's `showLineNumbers` defaults to `true`.
+
+### `table` / `row` / `cell`
+
+An explicit `row` / `cell` tree. Each cell body is itself block content. Use this
+(not a pipe table) whenever you need cell spans, alignment, backgrounds, or the
+fluid `auto` layout.
+
+```markdoc
+{% table layout="auto" %}
+{% row %}
+{% cell header=true %}
+Parameter
+{% /cell %}
+{% cell header=true align="right" %}
+Type
+{% /cell %}
+{% /row %}
+{% row %}
+{% cell %}
+user_id
+{% /cell %}
+{% cell %}
+int
+{% /cell %}
+{% /row %}
+{% /table %}
+```
+
+`table` attrs:
+
+| Attr | Type | Default | Values |
+|---|---|---|---|
+| `layout` | enum | `fixed` | `fixed`, `auto` (last column fluid) |
+
+`row` — no attributes; contains `cell` children only.
+
+`cell` attrs:
+
+| Attr | Type | Default | Values |
+|---|---|---|---|
+| `header` | boolean | `false` | `true` renders as a header cell |
+| `align` | enum | (none) | `left`, `center`, `right` |
+| `bg` | string | (none) | CSS colour, e.g. `#f6f6f6` |
+| `colspan` | number | `1` | |
+| `rowspan` | number | `1` | |
+| `colwidth` | number | (none) | column width in px |
+
+> A plain GFM pipe table is accepted on input but is rewritten into this
+> `{% table %}` form on the next save. Don't be surprised when it comes back
+> expanded.
+
+### `image`
+
+Block image. Self-closing when there is no caption; body form when there is one
+(the body is the caption, inline content only).
+
+```markdoc
+{% image url="asset:zvlxyph4f37t" width=357 /%}
+```
+
+```markdoc
+{% image url="https://uploads.developerhub.io/prod/02/example.png" %}
+A caption sits in the body.
+{% /image %}
+```
+
+| Attr | Type | Default | Values |
+|---|---|---|---|
+| `url` | string | `""` | `asset:<id>` (kept verbatim) or a full upload URL |
+| `width` | number | `0` | px; `0` = natural/full width |
+| `align` | enum | `center` | `left`, `center`, `right` |
+
+### `video`
+
+Embedded or raw video. Self-closing.
+
+```markdoc
+{% video provider="loom" videoId="e5b8c04bca094dd8a5507925ab887002" /%}
+{% video provider="raw" videoId="https://uploads.developerhub.io/example.mp4" /%}
+```
+
+| Attr | Type | Default | Values |
+|---|---|---|---|
+| `provider` | enum | `youtube` | `youtube`, `vimeo`, `loom`, `raw` |
+| `videoId` | string | `""` | the id for embeds; the full URL for `raw` (mp4/webm/ogg) |
+| `params` | string | `""` | e.g. `start=30` |
+
+### `tabs` / `tab`
+
+Generic tabbed content the reader switches between. Distinct from `{% code %}`.
+
+```markdoc
+{% tabs %}
+{% tab title="Android" %}
+Android content.
+{% /tab %}
+{% tab title="iOS" %}
+iOS content.
+{% /tab %}
+{% /tabs %}
+```
+
+`tabs` — no attributes; contains `tab` children only.
+
+`tab` attrs:
+
+| Attr | Type | Default |
+|---|---|---|
+| `title` | string | `Tab` |
+
+### `accordion-group` / `accordion`
+
+Collapsible sections. Each section is **collapsed on load** by default; add a bare
+`open=true` to expand it initially.
+
+```markdoc
+{% accordion-group %}
+{% accordion title="Getting started" open=true %}
+Any block content can go inside an accordion.
+{% /accordion %}
+{% accordion title="Advanced features" %}
+Second section.
+{% /accordion %}
+{% /accordion-group %}
+```
+
+`accordion-group` — no attributes; contains `accordion` children only.
+
+`accordion` attrs:
+
+| Attr | Type | Default | Notes |
+|---|---|---|---|
+| `title` | string | `Accordion` | |
+| `open` | boolean | `false` | `open=true` = expanded on page load |
+
+### `cards` / `card`
+
+A grid (default) or list of link cards. Each card is a self-closing `{% card /%}`.
+
+```markdoc
+{% cards view="grid" %}
+{% card title="Getting Started" text="Set up your first project." link="/support-center/getting-started" /%}
+{% card title="Hosting" text="Custom domains and SSL." link="/support-center/hosting" /%}
+{% /cards %}
+```
+
+`cards` attrs:
+
+| Attr | Type | Default | Values |
+|---|---|---|---|
+| `view` | enum | `grid` | `grid`, `list` |
+
+`card` attrs:
+
+| Attr | Type | Default |
+|---|---|---|
+| `title` | string | `""` |
+| `text` | string | `""` |
+| `link` | string | `/` |
+
+### `conditional`
+
+Wraps content shown only to a given audience (personalised / private docs).
+Resolved server-side.
+
+```markdoc
+{% conditional audience="beta-users" %}
+Content only beta users see.
+{% /conditional %}
+```
+
+| Attr | Type | Default | Notes |
+|---|---|---|---|
+| `audience` | string | `""` | a real project audience id; omit for public content |
+
+### `html`
+
+Raw custom HTML. The HTML is the body, not an attribute. Keep it to a single
+logical line where practical — multi-line indented HTML can lose indentation on
+round-trip.
+
+```markdoc
+{% html %}
+<div class="promo">Custom widget</div>
+{% /html %}
+```
+
+No attributes.
+
+### `github-code`
+
+Embeds code straight from a GitHub file URL (optionally a line range in the
+fragment). Self-closing.
+
+```markdoc
+{% github-code url="https://github.com/torvalds/linux/blob/master/kernel/signal.c#L152-L170" /%}
+```
+
+| Attr | Type | Default |
+|---|---|---|
+| `url` | string | `""` |
+
+### `index-list`
+
+Auto-generates an index of the current page's children. Self-closing, no
+attributes.
+
+```markdoc
+{% index-list /%}
+```
+
+### `synced`
+
+Inserts a reusable synced block by its id (managed in the project, not in the
+file). Self-closing.
+
+```markdoc
+{% synced id="open-block-menu" /%}
+```
+
+| Attr | Type | Default |
+|---|---|---|
+| `id` | string | `welcome` |
+
+---
+
+## Inline tags
+
+All self-closing, all sit inside a line of text.
+
+### `badge`
+
+Small coloured label.
+
+```markdoc
+{% badge text="Done" type="success" /%}
+```
+
+| Attr | Type | Default | Values |
+|---|---|---|---|
+| `text` | string | `OK` | the label |
+| `type` | enum | `info` | `info`, `success`, `warning`, `error`, `primary`, `custom` |
+
+### `key`
+
+A keyboard key. Multi-key strings like `cmd shift k` are prettified to glyphs
+(`⌘ ⇧ k`) on render.
+
+```markdoc
+{% key key="F1" /%}  {% key key="⌘" /%}
+```
+
+| Attr | Type | Default |
+|---|---|---|
+| `key` | string | `Esc` |
+
+### `icon`
+
+A Font Awesome icon.
+
+```markdoc
+{% icon classes="fas fa-adjust" /%}
+```
+
+| Attr | Type | Default |
+|---|---|---|
+| `classes` | string | `fas fa-star` |
+
+### `glossary`
+
+Links a word to its glossary entry (the definition is resolved live from the
+project glossary).
+
+```markdoc
+{% glossary term="coding" /%}
+```
+
+| Attr | Type | Default |
+|---|---|---|
+| `term` | string | `term` |
+
+### `inline-image`
+
+An image sized to sit inline with text.
+
+```markdoc
+{% inline-image url="asset:02grc2jqacve" width=14 /%}
+```
+
+| Attr | Type | Default | Values |
+|---|---|---|---|
+| `url` | string | `""` | `asset:<id>` (verbatim) or a full URL |
+| `width` | number | `0` | px; applies in `resizable` mode |
+| `mode` | enum | `resizable` | `resizable`, `w100` (fit width), `fit` |
+
+---
+
+## Variables
+
+Variables are written in **percent form**, not as a tag:
+
+```markdoc
+%product%      renders the project product name (e.g. "DeveloperHub")
+%user.name%    dotted keys resolve into nested values
+```
+
+- Keys are dotted identifiers (`api.base`).
+- Never echo `%product%` back to a user as literal text, and never replace it in
+  source.
+- A `%…%` inside inline code or a code fence stays literal.
+- An undefined key renders as `{{key}}`.
+
+---
+
+## Nesting rules
+
+- `accordion-group` → `accordion` only; `accordion` → any block.
+- `tabs` → `tab` only; `tab` → any block.
+- `code` → bare code fences only (no `{% tab %}`).
+- `code-steps` → lead blocks, then `step` tags, then language fences.
+- `table` → `row` → `cell`; a `cell` holds any block content.
+- `callout`, `conditional` → any block (they can nest tabs, callouts, etc.).
+- `image` body → caption (inline content only).
+- `video`, `cards`, `github-code`, `index-list`, `synced`, `html` → no children.
+- Inline tags (`badge`, `glossary`, `icon`, `key`, `inline-image`) and `%KEY%`
+  variables live inside a line of text.