DOCSEARCHbyAlgolia
Submit Docs

Ariadocs Documentation

website·Indexed 30 days ago

https://ariadocs.vercel.app

A lightweight, React-first library for building documentation sites with MDX. Features include support for Next.js (App and Pages Router), React Router, and TanStack Start, with built-in utilities for parsing MDX, extracting frontmatter, generating tables of contents, and managing navigation via _meta.json.

Tokens
10.8K
Snippets
81
Records
88
Agent score
75%

What's inside Ariadocs

  1. Overview of AriaDocs MDX Plugins

    AriaDocs provides a set of built-in rehype and remark plugins to extend MDX processing. These plugins are exported from the @ariadocs/react/plugins sub-path to support tree-shaking.
    import {
  remarkGfm,
  rehypePrism,
  rehypeSlug,
  rehypeAutolinkHeadings,
  rehypeCodeTitles,
  rehypeCodeRaw,
} from "@ariadocs/react/plugins";

  2. Define documentation navigation with _meta.json

    The _meta.json file is placed within directories in the contents folder to control the sidebar navigation structure. It determines the order of items, their display titles, visibility, and custom rendering properties. If no _meta.json exists, all .mdx files in that directory are included alphabetically with auto-generated titles.

  3. Create and view your first Ariadocs page

    Ariadocs pages are created as MDX files. Place your content in the contents/docs/ directory. Once the file is created and the app is running via pnpm dev, the page will be accessible at /docs/[slug].
    ---
title: Hello World
---

# Hello World

This is your **first Ariadocs page**.

  4. Ensure type safety for MDX components

    Use the MDXComponents type from @ariadocs/react/types to ensure your custom component map is type-safe.
    import type { MDXComponents } from "@ariadocs/react/types";

const components: MDXComponents = {
  h1: ({ children }) => <h1 className="text-3xl">{children}</h1>,
};

  5. Create a new Ariadocs project using the CLI

    Use the create-ariadocs-app CLI tool to scaffold a new Ariadocs project. During the setup process, you will be prompted to choose a framework template. Available templates include:

    • next-app: Next.js App Router
    • next-pages: Next.js Pages Router
    • react-router-v7: React Router v7
    • tanstack: TanStack Start
    npx create-ariadocs-app my-docs

  6. Initialize AriaDocs using createDocs

    Use createDocs(config) to create a docs instance with pre-configured options. This is the recommended approach to avoid repetitive configuration across your application. The instance provides a set of methods to parse, serialize, and retrieve metadata from MDX files located in a specified content directory.
    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
});

  7. Recommended plugin configuration and order

    When using multiple rehype plugins, the order of execution is critical. The recommended sequence is: 1. rehypeSlug (IDs), 2. rehypeAutolinkHeadings (Links), 3. rehypeCodeTitles (Titles), and 4. rehypePrism (Highlighting).
    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,
  ],
});

  8. Override createDocs configuration per-call

    You can override the global configuration for a specific method call by passing the configuration options (such as rehypePlugins) directly into the method's argument object alongside the slug.
    const docs = createDocs({
  contentDir: "contents/docs",
  rehypePlugins: defaultPlugins,
});

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

  9. Create a custom syntax highlighting theme

    You can create a custom theme by defining CSS rules for specific syntax token classes. To support dark mode in a custom theme, nest the token classes under the .dark selector.
    /* Custom Theme */
.keyword { color: #your-color; }
.function { color: #your-color; }
.punctuation { color: #your-color; }
.comment { color: #your-color; }
.string, .constant, .annotation, .boolean, .number { color: #your-color; }
.tag { color: #your-color; }
.attr-name { color: #your-color; }
.attr-value { color: #your-color; }

/* Dark Mode */
.dark .keyword { color: #your-dark-color; }
/* ... repeat for other tokens */

  10. Understand how AriaDocs builds navigation structure

    AriaDocs constructs the navigation tree based on three primary sources:

    1. Directory structure: Folders are automatically treated as nested navigation items.
    2. _meta.json files: These files are used to control the order of items, override titles, and manage visibility.
    3. MDX files: Every .mdx file in the content directory is treated as a navigation item.
    contents/docs/
├── _meta.json
├── introduction.mdx
├── getting-started/
│   ├── _meta.json
│   ├── installation.mdx
│   └── configuration.mdx
└── api/
    ├── _meta.json
    └── reference.mdx

  11. Enable dark mode for syntax highlighting

    All Ariadocs themes support dark mode automatically. To activate dark mode colors for code blocks, apply the .dark class to a parent element, such as the <html> or <body> tag.
    <html className="dark">{/* Code blocks will use dark mode colors */}</html>

  12. Start the Ariadocs development server

    After scaffolding the project with the CLI, navigate into the project directory, install dependencies, and start the development server. The site will be accessible at http://localhost:3000.
    cd my-docs
npm install
npm run dev