@ariadocs/react

A documentation-building library for React and Next.js. Render MDX content, organize docs with _meta.json, and build modern documentation sites with minimal setup.

🌐 Website: ariadocs.vercel.app

Installation

npm install @ariadocs/react
# or
pnpm add @ariadocs/react
# or
yarn add @ariadocs/react

Quick Start

1. Create a Docs Instance (Recommended)

Use createDocs() to avoid repeating configuration:

import { createDocs } from "@ariadocs/react";
import {
  remarkGfm,
  rehypePrism,
  rehypeSlug,
  rehypeAutolinkHeadings,
  rehypeCodeTitles,
} from "@ariadocs/react/plugins";

// Create once, use everywhere
export const docs = createDocs({
  contentDir: "contents/docs",
  rehypePlugins: [
    rehypeSlug,
    rehypeAutolinkHeadings,
    rehypeCodeTitles,
    rehypePrism,
  ],
  remarkPlugins: [remarkGfm],
});

2. Parse and Render MDX

import { docs } from "./docs";

export default async function DocPage({
  params,
}: {
  params: { path?: string[] };
}) {
  const slug = params.path?.join("/") ?? "index";

  // Just pass the slug - config is already set!
  const { MDX, frontmatter, toc } = await docs.parse({ slug });

  return (
    <article>
      <h1>{frontmatter.title}</h1>
      <nav>
        {toc.map((item) => (
          <a key={item.id} href={`#${item.id}`}>
            {item.value}
          </a>
        ))}
      </nav>
      {MDX}
    </article>
  );
}

3. Build Navigation Sidebar

import { docs, type NavItem } from "@ariadocs/react";

export default async function Sidebar() {
  // No need to pass contentDir - it's already configured!
  const navItems = await docs.getNavItems();
  return <NavList items={navItems} />;
}

function NavList({ items }: { items: NavItem[] }) {
  return (
    <ul>
      {items
        .filter((item) => item.nav)
        .map((item) => (
          <li key={item.href}>
            <a href={item.href}>{item.title}</a>
            {item.items.length > 0 && <NavList items={item.items} />}
          </li>
        ))}
    </ul>
  );
}

API Reference

createDocs(config) (Recommended)

Create a docs instance with pre-configured options. Eliminates repetitive configuration.

import { createDocs } from "@ariadocs/react";
import {
  remarkGfm,
  rehypePrism,
  rehypeSlug,
  rehypeAutolinkHeadings,
  rehypeCodeTitles,
} from "@ariadocs/react/plugins";

const docs = createDocs({
  contentDir: "contents/docs",
  remarkPlugins: [remarkGfm],
  rehypePlugins: [
    rehypeSlug,
    rehypeAutolinkHeadings,
    rehypeCodeTitles,
    rehypePrism,
  ],
  mdxComponents: {}, // Optional
});

// All methods share the config
await docs.parse({ slug: "intro" }); // Parse for server
await docs.serialize({ slug: "intro" }); // Serialize for client
await docs.getFrontmatter({ slug: "intro" }); // Get frontmatter only
await docs.getToc({ slug: "intro" }); // Get TOC only
await docs.readMdx({ slug: "intro" }); // Read raw content
await docs.getNavItems(); // Get navigation tree
await docs.getPagePaths(); // Get all page paths
docs.config; // Access the original config (readonly)

Override Options Per-Call

const docs = createDocs({
  contentDir: "contents/docs",
  rehypePlugins: defaultPlugins,
});

// Override plugins for a specific call
await docs.parse({
  slug: "special",
  rehypePlugins: customPlugins, // Uses customPlugins instead
});

Standalone Functions

Use these when you need one-off operations without creating an instance.

parseMdx(options)

Parse a local MDX file for server-side rendering.

const { raw, content, frontmatter, toc, MDX } = await parseMdx({
  contentDir: "contents/docs", // Required: path to content directory
  slug: "getting-started", // Required: file path without .mdx
  remarkPlugins: [], // Optional: remark plugins
  rehypePlugins: [], // Optional: rehype plugins
  mdxComponents: {}, // Optional: custom MDX components
});

serializeMdx(options)

Serialize MDX for client-side rendering with MdxClient.

// Server component
const { serialized, frontmatter, toc } = await serializeMdx({
  contentDir: "contents/docs",
  slug: "getting-started",
  rehypePlugins: [],
});

// Pass to client component
<DocClient serialized={serialized} />;

readMdx(options)

Read raw MDX file content.

const raw = await readMdx({
  contentDir: "contents/docs",
  slug: "getting-started",
});

getFrontmatter(options)

Get only the frontmatter from an MDX file.

const frontmatter = await getFrontmatter({
  contentDir: "contents/docs",
  slug: "getting-started",
});

getToc(options)

Get only the table of contents.

const toc = await getToc({
  contentDir: "contents/docs",
  slug: "getting-started",
});

Remote MDX Functions

For MDX content from APIs, CMS, or GitHub:

import {
  parseMdxRemote,
  serializeMdxRemote,
  getFrontmatterRemote,
  getTocRemote,
} from "@ariadocs/react";

// Get frontmatter from remote content
const frontmatter = await getFrontmatterRemote({ raw: mdxContentString });

// Get TOC from remote content
const toc = await getTocRemote({ raw: mdxContentString });

// Parse remote MDX
const { MDX, frontmatter, toc } = await parseMdxRemote({
  raw: mdxContentString,
  rehypePlugins: [],
});

// Serialize for client
const { serialized } = await serializeMdxRemote({
  raw: mdxContentString,
  rehypePlugins: [],
});

Navigation Functions

getNavItems(options)

Build navigation tree from content directory structure and _meta.json files.

const navItems = await getNavItems({
  contentDir: "contents/docs",
});

getPagePaths(options)

Get all page paths for static generation.

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

slugToTitle(slug)

Convert a slug string to a title.

slugToTitle("getting-started"); // "Getting Started"
slugToTitle("api-reference"); // "Api Reference"

Components

<MdxServer />

Server component for rendering MDX.

import { MdxServer } from "@ariadocs/react";
// or
import { MdxServer } from "@ariadocs/react/server";

<MdxServer
  raw={mdxContent}
  options={{
    remarkPlugins: [],
    rehypePlugins: [],
  }}
  components={
    {
      // Custom components
    }
  }
/>;

<MdxClient />

Client component for rendering serialized MDX.

"use client";
import { MdxClient } from "@ariadocs/react";
// or
import { MdxClient } from "@ariadocs/react/client";

<MdxClient serialized={serializedResult} mdxComponents={{}} />;

Plugins

Import individual plugins from the sub-path export:

import {
  remarkGfm,
  rehypePrism,
  rehypeAutolinkHeadings,
  rehypeSlug,
  rehypeCodeTitles,
  rehypeCodeRaw,
} from "@ariadocs/react/plugins";

| Plugin | Description | | ------------------------ | ----------------------------------------------- | | remarkGfm | GitHub Flavored Markdown support | | rehypePrism | Syntax highlighting with Prism.js | | rehypeSlug | Add IDs to headings | | rehypeAutolinkHeadings | Add anchor links to headings | | rehypeCodeTitles | Add titles to code blocks | | rehypeCodeRaw | Inject raw code string into <pre> for copying |

Recommended Setup

import { createDocs } from "@ariadocs/react";
import {
  remarkGfm,
  rehypePrism,
  rehypeSlug,
  rehypeAutolinkHeadings,
  rehypeCodeTitles,
} from "@ariadocs/react/plugins";

const docs = createDocs({
  contentDir: "contents/docs",
  remarkPlugins: [remarkGfm],
  rehypePlugins: [
    rehypeSlug,
    rehypeAutolinkHeadings,
    rehypeCodeTitles,
    rehypePrism,
  ],
});

Sub-path Exports

The package provides multiple entry points for tree-shaking:

| Export | Description | | ---------------------------- | ----------------------------- | | @ariadocs/react | Main entry (all exports) | | @ariadocs/react/client | MdxClient component | | @ariadocs/react/server | MdxServer component | | @ariadocs/react/plugins | All rehype/remark plugins | | @ariadocs/react/nav | Navigation functions | | @ariadocs/react/parse | Parse/serialize functions | | @ariadocs/react/types | Type definitions only | | @ariadocs/react/syntax.css | Prism syntax highlighting CSS |

Types

All types are exported from the main entry:

import type {
  // Core types
  BaseFrontmatter,
  DocsConfig,
  RemoteDocsConfig,
  ParseResult,
  SerializeResult,
  DocsInstance,
  ParseSlugOptions,
  LocalOptions,
  RemoteOptions,
  // Navigation types
  NavItem,
  MetaItem,
  // Plugin types
  RemarkPlugins,
  RehypePlugins,
  // Component types
  MdxServerProps,
  MdxClientProps,
  // Re-exports from external libs
  MDXComponents,
  TocItem,
} from "@ariadocs/react";

Organizing Content with _meta.json

Control navigation order, titles, and visibility with _meta.json files:

contents/docs/
├── _meta.json
├── introduction.mdx
├── getting-started.mdx
├── advanced/
│   ├── _meta.json
│   ├── configuration.mdx
│   └── plugins.mdx
└── api/
    └── reference.mdx

_meta.json Format

[
  { "slug": "introduction", "title": "Introduction", "nav": true },
  { "slug": "getting-started", "title": "Quick Start", "nav": true },
  { "slug": "advanced", "title": "Advanced", "nav": true },
  { "slug": "api", "title": "API Reference", "nav": true }
]

Options

| Property | Type | Default | Description | | -------- | ------------------------ | ------------------- | ------------------------------------ | | slug | string | Required | File or folder name (without .mdx) | | title | string | slugToTitle(slug) | Display title | | nav | boolean | true | Show in navigation | | props | Record<string, string> | {} | Custom props for rendering |

Behavior

• Items in _meta.json appear in the order defined
• Items not in _meta.json are appended at the end (sorted alphabetically)
• Nested directories use their own _meta.json

Custom Frontmatter

interface MyFrontmatter {
  title: string;
  description: string;
  author: string;
  tags: string[];
}

const { frontmatter } = await parseMdx<MyFrontmatter>({
  contentDir: "contents/docs",
  slug: "article",
});

// frontmatter.title, frontmatter.author, etc. are typed!

Full Next.js Example

// lib/docs.ts - Create docs instance once
import { createDocs } from "@ariadocs/react";
import {
  remarkGfm,
  rehypePrism,
  rehypeSlug,
  rehypeAutolinkHeadings,
  rehypeCodeTitles,
} from "@ariadocs/react/plugins";

export const docs = createDocs({
  contentDir: "contents/docs",
  remarkPlugins: [remarkGfm],
  rehypePlugins: [
    rehypeSlug,
    rehypeAutolinkHeadings,
    rehypeCodeTitles,
    rehypePrism,
  ],
});

// app/docs/[[...path]]/page.tsx
import { docs } from "@/lib/docs";
import "@ariadocs/react/syntax.css";

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

export default async function DocPage({
  params,
}: {
  params: { path?: string[] };
}) {
  const slug = params.path?.join("/") ?? "index";

  const [{ MDX, frontmatter, toc }, navItems] = await Promise.all([
    docs.parse({ slug }),
    docs.getNavItems(),
  ]);

  return (
    <div className="flex">
      <aside>
        <NavList items={navItems} />
      </aside>
      <main>
        <h1>{frontmatter.title}</h1>
        <Toc items={toc} />
        {MDX}
      </main>
    </div>
  );
}

License

MIT © Nisab Mohd