Update to Redocly

{
  "description": "Use when writing or changing content in a Redocly project: adding, moving, or renaming pages, choosing file names and URLs, links and images, page titles and front matter, Markdoc tags such as admonitions, tabs, cards, code groups, and partials, the sidebar, navbar, and footer, or site settings in redocly.yaml. Not for API reference docs from OpenAPI, AsyncAPI, or GraphQL files (use redocly-api-docs).",
  "included_files": [],
  "name": "redocly-authoring",
  "skill_md_contents": "---\nname: redocly-authoring\ndescription: >-\n  Use when writing or changing content in a Redocly project: adding, moving, or renaming pages, choosing\n  file names and URLs, links and images, page titles and front matter, Markdoc tags such as admonitions,\n  tabs, cards, code groups, and partials, the sidebar, navbar, and footer, or site settings in redocly.yaml.\n  Not for API reference docs from OpenAPI, AsyncAPI, or GraphQL files (use redocly-api-docs).\n---\n\n# Write content for a Redocly project\n\n## The folder is the site\n\nRealm builds the site from the project folder.\nEvery content file is a page, and the path of the file is the URL of the page:\n\n| File | URL |\n| --- | --- |\n| `index.md` | `/` |\n| `guides/quickstart.md` | `/guides/quickstart` |\n| `guides/index.md` | `/guides` |\n| `apis/cafe-api.yaml` | `/apis/cafe-api` (API reference, see `redocly-api-docs`) |\n| `changelog.page.tsx` | `/changelog` (React page) |\n\nA file named `index` is the page of its folder.\nTo change a URL, move or rename the file, and add the old URL to `redirects` in `redocly.yaml` when the page was published.\n\nSome folders are not pages.\n`_partials/` (by default) holds reusable content, and files in `static/` are copied to the site root as they are: `static/robots.txt` is served at `/robots.txt`.\nRealm reserves `@theme/` (customizations), `@l10n/` (translations), `@api/`, and `@skills/`.\nAny other folder that starts with `@` is a content version.\nTwo files that resolve to the same URL, such as `payments.md` and `payments/index.md`, get numbered URLs, so avoid them.\n\nFull reference: https://redocly.com/docs/realm/content/project-structure.md\n\n## Before you write\n\nRead `redocly.yaml` and the nearest `sidebars.yaml` when they exist, as a project can have neither.\nRead two or three pages next to the one you add and match their file naming, heading style, and image location.\nDefault to kebab-case file names when the folder has no pattern.\nSearch for existing content before you add a page: the right change may be a new section or a link.\n\n## Pages\n\nA page is Markdown with optional YAML front matter.\nThe first H1 is the page title.\nFront matter holds the settings of one page, such as a search title that differs from the H1 or a description.\nOmit it when the defaults do:\n\n```markdown\n---\nseo:\n  title: Rate limits for the Acme API\n  description: Request limits, the 429 response, and how to retry.\n---\n\n# Rate limits\n```\n\n`slug: /custom-url` serves the page at a different URL.\nUse it only when the author wants the file to stay where it is.\nThe other page settings, such as `rbac`, `markdown.toc`, `feedback`, or `navbar.hide`, are in the front matter reference: https://redocly.com/docs/realm/config/front-matter-config.md\n\n## Links and images\n\nLink to files, with their extension, relative to the page: `[Quickstart](./quickstart.md)`, `[Cafe API](../apis/cafe-api.yaml)`, `[Install](../setup/index.md#install)`.\nA path that starts with `/` resolves from the project root.\nDo not link to built URLs of the same site.\nRealm resolves file links for locales and versions, and the preview reports a broken file link.\nAfter moving a file, fix the links to it and the relative links inside it.\n\nStore images where the project already stores them, otherwise in an `images/` folder next to the page.\nReference them with relative paths and alt text: `![Orders dashboard](./images/orders.png)`.\nFiles that need a fixed URL, such as `robots.txt`, go in `static/`.\n\nFull reference: https://redocly.com/docs/realm/content/links.md\n\n## Markdoc tags\n\nPages are Markdown, and Markdoc tags in `{% ... %}` add components when a page needs them.\nA tag with content has a closing tag, and a tag without content ends with `/%}`.\nPut block tags on their own lines.\n\n```markdoc\n{% admonition type=\"warning\" name=\"Rate limit\" %}\nRequests above 100 per minute get HTTP 429.\n{% /admonition %}\n```\n\nStrings are quoted, numbers and booleans are not: `columns=2`, `expanded=true`.\nChild tags work only inside their parent: `tab` in `tabs`, `card` in `cards`, `numbered-item` in `numbered-list`.\n\n| Tag | Use | Reference |\n| --- | --- | --- |\n| `admonition` | Callout. `type` is `info`, `warning`, `success`, `danger`, or `idea`, and the title attribute is `name` | https://redocly.com/docs/realm/content/markdoc-tags/admonition.md |\n| `tabs` / `tab` | Switchable panels, and each `tab` has `label` | https://redocly.com/docs/realm/content/markdoc-tags/tabs.md |\n| `code-group` | Fenced code blocks as tabs, named by the `title` fence attribute | https://redocly.com/docs/realm/content/markdoc-tags/code-group.md |\n| `cards` / `card` | Link tiles, and `card` has `title` and `to` | https://redocly.com/docs/realm/content/markdoc-tags/cards.md |\n| `accordion` | Collapsible section with a `title`, wrapped in `accordion-group` for an FAQ | https://redocly.com/docs/realm/content/markdoc-tags/accordion.md |\n| `table` | Table with rich content in cells, where a Markdown pipe table is enough for simple data | https://redocly.com/docs/realm/content/markdoc-tags/table.md |\n| `img` | Image with size, caption, lightbox, or one file per color mode | https://redocly.com/docs/realm/content/markdoc-tags/img.md |\n| `icon` | Inline Font Awesome icon: `{% icon name=\"solid check\" /%}` | https://redocly.com/docs/realm/content/markdoc-tags/icon.md |\n| `partial` | Insert a file from a partials folder: `{% partial file=\"/_partials/note.md\" /%}` | https://redocly.com/docs/realm/content/markdoc-tags/partial.md |\n| `code-snippet` | Code block from a file, or a range of its lines | https://redocly.com/docs/realm/content/markdoc-tags/code-snippet.md |\n| `if` / `else` | Conditional content with `equals`, `includes`, `and`, `or`, `not` on variables such as `$frontmatter` or `$rbac.teams` | https://redocly.com/docs/realm/content/markdoc-tags/if-else.md |\n| `numbered-list` / `numbered-item` | Procedure steps on a rail, each step a `numbered-item` | https://redocly.com/docs/realm/content/markdoc-tags/numbered-list.md |\n| `prompt` | An AI prompt that readers copy or open in Claude, ChatGPT, or Cursor with one click | https://redocly.com/docs/realm/content/markdoc-tags/prompt.md |\n| `connect-mcp` | A button that connects an AI client to the site's MCP server | https://redocly.com/docs/realm/content/markdoc-tags/connect-mcp.md |\n| `login-button` | A login button shown only to users who are not logged in | https://redocly.com/docs/realm/content/markdoc-tags/login-button.md |\n| `code-walkthrough` | Interactive tutorial: steps on the left, highlighted code on the right | https://redocly.com/docs/realm/content/markdoc-tags/code-walkthrough.md |\n| `inline-svg` | An SVG file rendered inline, so CSS can style it | https://redocly.com/docs/realm/content/markdoc-tags/inline-svg.md |\n| `markdoc-example` | Markdoc source next to its rendered result | https://redocly.com/docs/realm/content/markdoc-tags/markdoc-example.md |\n\nAll tags, with every attribute: https://redocly.com/docs/realm/content/markdoc-tags/tag-library.md\nTags that show an operation or schema from an API description are in the `redocly-api-docs` skill (https://redocly.com/.well-known/agent-skills/redocly-api-docs/SKILL.md).\nA project can define its own tags in `@theme/markdoc/schema.ts`, so read that file before using one.\n\nA fenced code block takes Markdoc attributes after the language, such as `{% title=\"redocly.yaml\" %}`.\nThe `treeview` language renders a folder tree, and `mermaid` renders a diagram.\nMarkdoc processes `{% ... %}` sequences inside a code block, and nothing else.\nAdd `{% process=false %}` to the fence to show them as text.\n\nFull reference: https://redocly.com/docs/realm/content/markdown.md\n\n## Navigation\n\nWithout a `sidebars.yaml`, Realm generates the sidebar from the folder structure.\nWith one, a page shows in the sidebar only when a sidebar file lists it, or lists its folder with `directory`.\n\n```yaml\n- page: index.md\n  label: Overview\n- group: Guides\n  page: guides/index.md\n  items:\n    - page: guides/quickstart.md\n    - page: guides/rate-limits.md\n    - directory: guides/advanced\n- page: apis/cafe-api.yaml\n  label: Cafe API\n- href: https://status.example.com\n  label: Status\n  external: true\n```\n\nPaths in a sidebar file are relative to that file.\nThe label defaults to the page title.\nLarge sites split into navigation tabs, one per section with its own sidebar.\nTabs are top-level `tab` entries of `sidebars.yaml`: https://redocly.com/docs/realm/navigation/navigation-tabs.md\nAnother option is one sidebar file per section, joined with `$ref` entries or linked from the navbar.\nLeave a page out of every sidebar file to show it without a sidebar, such as a landing page.\n\nSidebars: https://redocly.com/docs/realm/navigation/sidebars.md\n\nThe navbar and footer are the `navbar` and `footer` objects in `redocly.yaml`, each with an `items` list.\nThe items take the same `page`, `href`, `label`, `external`, and `group` keys as a sidebar, with paths relative to the project root:\n\n```yaml\nnavbar:\n  items:\n    - page: guides/index.md\n      label: Guides\n```\n\nNavbar: https://redocly.com/docs/realm/config/navbar.md and footer: https://redocly.com/docs/realm/config/footer.md\n\n## Site settings\n\n`redocly.yaml` in the project root configures the whole site.\nPaths in it are relative to the project root.\n\n```yaml\nseo:\n  projectTitle: Acme docs\n  siteUrl: https://docs.acme.example\nredirects:\n  '/old-guide/':\n    to: '/guides/quickstart/'\n```\n\nA redirect source and its `to` start with `/` and leave out `index`, and `*` is valid only as the last segment.\nRedirects: https://redocly.com/docs/realm/config/redirects.md\nCommon keys: `seo`, `redirects`, `logo`, `navbar`, `footer`, `search`, `banner`, `feedback`, `breadcrumbs`, `ignore`, `access` (login and role-based access), `analytics`, `l10n`, `products`, and `env`.\nValidate the file with `npx @redocly/cli check-config`, which names unknown keys.\n\nAll options: https://redocly.com/docs/realm/config.md\n\n## Beyond content\n\nThese exist, so load their page before changing them, and prefer the smallest change:\n\n- Styling: CSS variables in `@theme/styles.css`, the logo and favicon in `logo`, fonts in `links`. https://redocly.com/docs/realm/branding/customize-styles.md\n- Versioned content: one `@<version>` folder per version. https://redocly.com/docs/realm/content/versions.md\n- Translations: `@l10n/<locale>/` folders. https://redocly.com/docs/realm/content/localization/localize-content.md\n- Several products with a product picker: `products` in `redocly.yaml`. https://redocly.com/docs/realm/config/products.md\n- Page templates: a React layout applied to a set of Markdown pages. https://redocly.com/docs/realm/customization.md\n- Login and role-based access: `access` in `redocly.yaml`. https://redocly.com/docs/realm/config/access.md\n\nA React page is a `*.page.tsx` file.\nIts path is its URL, like a Markdown page, and it sets its front matter in code:\n\n```tsx\nimport React from 'react';\n\nexport const frontmatter = { seo: { title: 'About Acme' } };\n\nexport default function AboutPage() {\n  return <h1>About Acme</h1>;\n}\n```\n\nUse one for a layout that Markdown cannot express, such as a landing page, and import the theme components it needs from `@redocly/theme`: https://redocly.com/docs/realm/customization/create-react-page.md\n\nA project can define its own Markdoc tags: a tag name with typed attributes, declared in `@theme/markdoc/schema.ts`, rendered by a React component from `@theme/markdoc/components.tsx`.\nAuthors then write it like a built-in tag, for example `{% product-card name=\"Orders\" /%}`.\nBuild one when a block repeats across pages with varying data and a partial is not enough: https://redocly.com/docs/realm/customization/build-markdoc-tags.md\n\nEvery part of the site is a React component, and any of them can be ejected.\n`npx @redocly/cli eject component 'Footer/**'` copies the source into `@theme/components/`, and the copy replaces the original.\nFind a component's name in the `data-component-name` attribute in the browser developer tools.\nEject only when the structure or behavior has to change, because colors, fonts, and spacing are CSS variables.\nReference: https://redocly.com/docs/realm/customization/eject-components.md\n\n## Verify\n\nFollow Preview and verify in the `redocly` skill (https://redocly.com/.well-known/agent-skills/redocly/SKILL.md): run `TERM=dumb npx @redocly/cli preview` in the background, read its output, and open the page.\nThe output reports the Markdoc errors, such as an unknown tag or attribute, and the broken links.\nAfter a change to `redocly.yaml`, also run `npx @redocly/cli check-config`.\nIf `redocly.yaml` configures `recheck`, use the `recheck-lint` skill (https://redocly.com/.well-known/agent-skills/recheck-lint/SKILL.md) on the files you touched.\n\n## Common mistakes\n\n| Mistake | Correct approach |\n| --- | --- |\n| `title:` in the front matter | The H1 is the title, and `seo.title` overrides it |\n| A link without the extension, or to the built URL | Link to the file: `./quickstart.md` |\n| `{% admonition title=\"...\" %}` or `{% tab title=\"...\" %}` | `name` for admonitions, `label` for tabs |\n| `{% code %}` tags inside `code-group` | Fenced code blocks with a `title` attribute |\n| A new page expected in the sidebar automatically when a `sidebars.yaml` exists | Add it to `sidebars.yaml`, or use `directory` |\n| A page moved without a redirect | Add the old URL to `redirects` |\n| `colors` or `fonts` keys in `redocly.yaml` | CSS variables in `@theme/styles.css` |\n| An option name or attribute from memory | Fetch the reference page |\n"
}