Skip to content

nisabmohd/aria-docs / skills/ariadocs-mdx

ariadocs-mdx

Verified

Add 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`.

FileKindSize
SKILL.mdskill md5.8 KB
references/api.mdmarkdown1.6 KB
references/frameworks.mdmarkdown10.1 KB
references/migration.mdmarkdown1.8 KB

references/frameworks.md

View on GitHub
# Framework recipes: MDX docs

Each recipe assumes the shared `docs` instance from SKILL.md (`lib/docs.ts`). Change the import paths to match the project's alias. API reference routes are in the `ariadocs-openapi` skill.

## Next.js App Router

Server Components render `docs.parse()` output directly. The sidebar lives in `layout.tsx` and the TOC in `page.tsx`. The page returns `Docs.Content` and `Docs.Aside` **as a fragment**, so they stay direct children of the `Docs.Layout` grid. Don't build a custom grid.

```tsx title="app/docs/[[...slug]]/page.tsx"
import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { isMdxNotFound } from "@ariadocs/mdx";
import { Docs } from "@ariadocs/components";
import { docs } from "@/lib/docs";

type Frontmatter = { title: string; description?: string };
type Props = { params: Promise<{ slug?: string[] }> };

export default async function Page({ params }: Props) {
  const slug = (await params).slug?.join("/") ?? "";
  try {
    const { MDX, frontmatter, toc } = await docs.parse<Frontmatter>({ slug });
    return (
      <>
        <Docs.Content>
          <Docs.Page>
            <Docs.Page.Title>{frontmatter.title}</Docs.Page.Title>
            {frontmatter.description && <Docs.Page.Description>{frontmatter.description}</Docs.Page.Description>}
            <Docs.Page.Content>{MDX}</Docs.Page.Content>
          </Docs.Page>
        </Docs.Content>
        <Docs.Aside>
          <Docs.Toc items={toc} />
        </Docs.Aside>
      </>
    );
  } catch (error) {
    if (isMdxNotFound(error)) notFound();
    throw error;
  }
}

export async function generateStaticParams() {
  const paths = await docs.getPagePaths();
  return paths.map((path) => ({ slug: path.split("/").filter(Boolean) }));
}

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const slug = (await params).slug?.join("/") ?? "";
  try {
    const { title, description } = await docs.getFrontmatter<Frontmatter>({ slug });
    return { title, description };
  } catch {
    return {};
  }
}
```

```tsx title="app/docs/layout.tsx"
import { Docs } from "@ariadocs/components";
import { docs } from "@/lib/docs";
import { Sidebar } from "@/components/sidebar";

export default async function Layout({ children }: { children: React.ReactNode }) {
  const items = await docs.getNavigation();
  return (
    <>
      <header className="bg-background sticky top-0 z-40 flex h-14 items-center gap-2 border-b px-4">
        {/* Below lg, Docs.Sidebar is hidden: the drawer holds the same nav */}
        <Docs.MobileNav>
          <Sidebar items={items} baseHref="/docs" />
        </Docs.MobileNav>
      </header>
      <Docs.Layout>
        <Docs.Sidebar>
          <Sidebar items={items} baseHref="/docs" />
        </Docs.Sidebar>
        {children}
      </Docs.Layout>
    </>
  );
}
```

```tsx title="components/sidebar.tsx"
"use client";

import Link from "next/link";
import { usePathname } from "next/navigation";
import { Docs } from "@ariadocs/components";
import type { NavItem } from "@ariadocs/core";

export function Sidebar({ items, baseHref }: { items: NavItem[]; baseHref?: string }) {
  return <Docs.Nav items={items} baseHref={baseHref} activeHref={usePathname()} linkAs={Link} />;
}
```

`NavItem` is also exported from `@ariadocs/mdx` if `@ariadocs/core` is not a direct dependency.

## Next.js Pages Router

There are no Server Components, so serialize in `getStaticProps` and render with `MdxClient`.

```tsx title="pages/docs/[[...slug]].tsx"
import type { GetStaticPaths, GetStaticProps } from "next";
import Link from "next/link";
import { useRouter } from "next/router";
import { isMdxNotFound, type NavItem, type SerializeResult, type TocItem } from "@ariadocs/mdx";
import { MdxClient } from "@ariadocs/mdx/client";
import { Docs } from "@ariadocs/components";
import { docs } from "@/lib/docs";

type Props = { serialized: SerializeResult; title: string; toc: TocItem[]; nav: NavItem[] };

export default function Page({ serialized, title, toc, nav }: Props) {
  const { asPath } = useRouter();
  return (
    <Docs.Layout>
      <Docs.Sidebar>
        <Docs.Nav items={nav} baseHref="/docs" activeHref={asPath.split(/[?#]/)[0]} linkAs={Link} />
      </Docs.Sidebar>
      <Docs.Content>
        <Docs.Page>
          <Docs.Page.Title>{title}</Docs.Page.Title>
          <Docs.Page.Content>
            <MdxClient serialized={serialized} />
          </Docs.Page.Content>
        </Docs.Page>
      </Docs.Content>
      <Docs.Aside>
        <Docs.Toc items={toc} />
      </Docs.Aside>
    </Docs.Layout>
  );
}

export const getStaticProps: GetStaticProps<Props> = async ({ params }) => {
  const slug = ((params?.slug as string[] | undefined) ?? []).join("/");
  try {
    const [{ serialized, frontmatter, toc }, nav] = await Promise.all([
      docs.serialize<{ title: string }>({ slug }),
      docs.getNavigation(),
    ]);
    return { props: { serialized, title: frontmatter.title, toc, nav } };
  } catch (error) {
    if (isMdxNotFound(error)) return { notFound: true };
    throw error;
  }
};

export const getStaticPaths: GetStaticPaths = async () => {
  const paths = await docs.getPagePaths();
  return {
    paths: paths.map((path) => ({ params: { slug: path.split("/").filter(Boolean) } })),
    fallback: false,
  };
};
```

Only type imports come from the main `@ariadocs/mdx` entry in the component. Next removes the `getStaticProps` code from the client bundle.

The global CSS import (`@ariadocs/components/styles.css`) goes in `pages/_app.tsx`.

## React Router v7 and v8 (framework mode)

```ts title="app/routes.ts"
import { type RouteConfig, index, route } from "@react-router/dev/routes";

export default [index("routes/home.tsx"), route("docs/*", "routes/docs.tsx")] satisfies RouteConfig;
```

```tsx title="app/routes/docs.tsx"
import { useLoaderData, useLocation, Link } from "react-router";
import { isMdxNotFound } from "@ariadocs/mdx";
import { MdxClient } from "@ariadocs/mdx/client";
import { Docs, type LinkComponentProps } from "@ariadocs/components";
import type { Route } from "./+types/docs";
import { docs } from "../docs";

export async function loader({ params }: Route.LoaderArgs) {
  try {
    const [{ serialized, frontmatter, toc }, nav] = await Promise.all([
      docs.serialize<{ title: string }>({ slug: params["*"] ?? "" }),
      docs.getNavigation(),
    ]);
    // Return only what the page renders: `source` and `content` would send the raw MDX too.
    return { serialized, frontmatter, toc, nav };
  } catch (error) {
    if (isMdxNotFound(error)) throw new Response("Not found", { status: 404 });
    throw error;
  }
}

export default function DocsPage() {
  const { serialized, frontmatter, toc, nav } = useLoaderData<typeof loader>();
  const { pathname } = useLocation();
  return (
    <Docs.Layout>
      <Docs.Sidebar>
        <Docs.Nav items={nav} baseHref="/docs" activeHref={pathname} linkAs={DocLink} />
      </Docs.Sidebar>
      <Docs.Content>
        <Docs.Page>
          <Docs.Page.Title>{frontmatter.title}</Docs.Page.Title>
          <Docs.Page.Content>
            <MdxClient serialized={serialized} />
          </Docs.Page.Content>
        </Docs.Page>
      </Docs.Content>
      <Docs.Aside>
        <Docs.Toc items={toc} />
      </Docs.Aside>
    </Docs.Layout>
  );
}

function DocLink({ href, ...props }: LinkComponentProps) {
  return <Link to={href} {...props} />;
}
```

```ts title="react-router.config.ts"
import type { Config } from "@react-router/dev/config";
import { docs } from "./app/docs";

export default {
  ssr: true,
  async prerender() {
    const paths = await docs.getPagePaths();
    return paths.map((path) => `/docs${path === "/" ? "" : path}`);
  },
} satisfies Config;
```

The CSS import goes in `app/root.tsx` (or `app/app.css` via `@import`).

## TanStack Start

Loaders also run in the browser during client navigation, so anything that reads files goes through `createServerFn`.

```tsx title="src/routes/docs/$.tsx"
import { Link, createFileRoute, notFound, useLocation } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { isMdxNotFound } from "@ariadocs/mdx";
import { MdxClient } from "@ariadocs/mdx/client";
import { Docs, type LinkComponentProps } from "@ariadocs/components";
import { docs } from "../../docs";

const getPage = createServerFn({ method: "GET" })
  .inputValidator((slug: string) => slug)
  .handler(async ({ data: slug }) => {
    try {
      const [{ serialized, frontmatter, toc }, nav] = await Promise.all([
        docs.serialize<{ title: string }>({ slug }),
        docs.getNavigation(),
      ]);
      // Return only what the page renders: `source` and `content` would send the raw MDX too.
      return { serialized, frontmatter, toc, nav };
    } catch (error) {
      if (isMdxNotFound(error)) throw notFound();
      throw error;
    }
  });

export const Route = createFileRoute("/docs/$")({
  loader: ({ params }) => getPage({ data: params._splat ?? "" }),
  component: DocsPage,
});

function DocsPage() {
  const { serialized, frontmatter, toc, nav } = Route.useLoaderData();
  const { pathname } = useLocation();
  return (
    <Docs.Layout>
      <Docs.Sidebar>
        <Docs.Nav items={nav} baseHref="/docs" activeHref={pathname} linkAs={DocLink} />
      </Docs.Sidebar>
      <Docs.Content>
        <Docs.Page>
          <Docs.Page.Title>{frontmatter.title}</Docs.Page.Title>
          <Docs.Page.Content>
            <MdxClient serialized={serialized} />
          </Docs.Page.Content>
        </Docs.Page>
      </Docs.Content>
      <Docs.Aside>
        <Docs.Toc items={toc} />
      </Docs.Aside>
    </Docs.Layout>
  );
}

function DocLink({ href, ...props }: LinkComponentProps) {
  // exact: otherwise TanStack also marks parent pages like /docs as current.
  return <Link to={href} activeOptions={{ exact: true }} {...props} />;
}
```

The CSS import goes in `src/routes/__root.tsx`.

## MDX from a string (CMS, database)

```ts
import { parseMdx, serializeMdx } from "@ariadocs/mdx";

const { MDX, frontmatter, toc } = await parseMdx({ source: text, blockJs: true, rehypePlugins: [...] });
const { serialized } = await serializeMdx({ source: text, blockJs: true });
```
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall