nisabmohd/aria-docs / skills/ariadocs-mdx
ariadocs-mdx
VerifiedAdd MDX documentation pages to a React app with @ariadocs/mdx — read a folder of .mdx files, render pages (Server Components or client), frontmatter, table of contents, sidebar navigation from _meta.json, static paths, remark/rehype plugins, custom MDX components and untrusted MDX. Use when the user wants to set up docs pages, render MDX files or MDX from a CMS, build a docs sidebar or TOC, or migrate from @ariadocs/react. Covers Next.js (App and Pages Router), React Router (v7 and v8) and TanStack Start. For the UI (layout, sidebar, callouts) use the `ariadocs-components` skill; for API references use `ariadocs-openapi`.
@ariadocs/mdx
Turns a folder of MDX files into rendered pages, frontmatter, a table of contents, a sidebar tree and static paths. It is a library, not a framework: the app keeps its own routing and layout.
Related skills: ariadocs-components renders the page shell, sidebar and TOC, and has copy-paste Callout, Tabs, Steps and Cards. ariadocs-openapi adds an API reference. @ariadocs/core (shared NavItem/TocItem types) is installed automatically.
@ariadocs/react is the old name of @ariadocs/mdx. Never install it. To migrate, see references/migration.md.
Workflow
- Inspect the project. Find the framework and router (
nextwithapp/orpages/,react-routerwith@react-router/dev,@tanstack/react-start), the package manager (lockfile) and the path alias (@/,~/,#/). - Install
@ariadocs/mdx. Add@ariadocs/componentsfor the prebuilt UI (then follow theariadocs-componentsskill for styles). - Create one shared instance in
lib/docs.ts(below). - Add routes for the framework. Copy the matching recipe from references/frameworks.md.
- Add starter content:
content/docs/index.mdxand a_meta.json. - Verify: run the type check and build (or the dev server), and open
/docs.
Shared instance
import { createDocs } from "@ariadocs/mdx";
import {
remarkGfm,
rehypeSlug,
rehypeAutolinkHeadings,
rehypeCodeTitles,
rehypePrism,
rehypeCodeRaw,
} from "@ariadocs/mdx/plugins";
import { Pre } from "@ariadocs/components"; // only if @ariadocs/components is installed
export const docs = createDocs({
contentDir: "content/docs", // relative to process.cwd()
remarkPlugins: [remarkGfm],
// rehypeCodeRaw must come after rehypePrism
rehypePlugins: [rehypeSlug, rehypeAutolinkHeadings, rehypeCodeTitles, rehypePrism, rehypeCodeRaw],
components: { pre: Pre }, // code blocks with a copy button; add Callout, Tabs, ... here
});
docs methods: parse, serialize, read, getFrontmatter, getToc (each takes { slug }), getNavigation(), getPagePaths().
Rendering: server or client
- With React Server Components (Next.js App Router):
const { MDX, frontmatter, toc } = await docs.parse({ slug })and render{MDX}directly. - Without them (Pages Router, React Router, TanStack Start): call
docs.serialize({ slug })on the server (loader,getStaticProps, server function), then render<MdxClient serialized={serialized} components={...} />imported from@ariadocs/mdx/client.
Content and sidebar
content/docs/
_meta.json
index.mdx -> /
getting-started/
_meta.json
index.mdx -> /getting-started
installation.mdx -> /getting-started/installation
[
{ "slug": "index", "title": "Introduction" },
{ "slug": "getting-started", "title": "Getting started" },
{ "slug": "changelog", "nav": false }
]
- Files missing from
_meta.jsonare appended alphabetically. Entries for missing files are skipped. Invalid JSON throws. - Names starting with
_or.are hidden from the sidebar and fromgetPagePaths(). getPagePaths()returns["/", "/getting-started", ...]. Hrefs are relative to the docs route, so passbaseHref="/docs"toDocs.Nav.docs.getNavigation()returnsNavItem[], the same shape asopenapi.getNavigation(), so the two can be concatenated into one sidebar.- The ordered
NavItem[]tree is also what you flatten for previous/next links and breadcrumbs.
Full export list: references/api.md.
Rules and gotchas
- 404s:
docs.parse/serializethrow for missing pages and for slugs outsidecontentDir. Catch the error and checkisMdxNotFound(error), then return the framework's 404. Rethrow anything else, such asMDX_COMPILE_ERRORfor broken MDX, so the build fails. - Loader payloads: from a loader, server function or
getStaticProps, return{ serialized, frontmatter, toc }, not the wholeserialize()result.sourceandcontenthold the raw MDX and would double the payload. - Never import
@ariadocs/mdx(main entry) in client code. It reads files. Client code importsMdxClientfrom@ariadocs/mdx/client.MdxServeris also available from@ariadocs/mdx/server. - Next.js Pages Router props must be JSON.
- TanStack Start loaders also run in the browser, so file reads must go through
createServerFn. - Untrusted content: pass
blockJs: truetoparseMdx/createDocsfor MDX from a CMS or users. MDXimport/exportand JavaScript frontmatter are always disabled. - Custom MDX components: MDX files can't import, so pass components to
createDocs({ components })(or thecomponentsprop ofMdxServer/MdxClient). Keys that match HTML tags replace those tags. WithMdxClient, the components run in the browser and can't be async. Callout, Tabs, Steps and Cards are not in any package: copy them from theariadocs-componentsskill. - TOC items are
{ value, href, depth }. Headings needrehypeSlugfor the anchors to work. - Frontmatter typing:
docs.parse<{ title: string; description?: string }>({ slug }).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |