Next.js | Hanzo Docs

Prerequisite

Before continuing, make sure you have configured:

Next.js 16.
Tailwind CSS 4.

We will use Hanzo Docs MDX as a content source, you can configure it first:

Installation

npm

pnpm

yarn

bun

npm i @hanzo/docs-mdx @hanzo/docs-core @types/mdx

pnpm add @hanzo/docs-mdx @hanzo/docs-core @types/mdx

yarn add @hanzo/docs-mdx @hanzo/docs-core @types/mdx

bun add @hanzo/docs-mdx @hanzo/docs-core @types/mdx

Create the configuration file:

source.config.ts

import { defineDocs, defineConfig } from '@hanzo/docs-mdx/config';

export const docs = defineDocs({
  dir: 'content/docs',
});

export default defineConfig();

Add the plugin to Next.js config:

next.config.mjs

import { createMDX } from '@hanzo/docs-mdx/next';

/** @type {import('next').NextConfig} */
const config = {
  reactStrictMode: true,
};

const withMDX = createMDX({
  // customise the config file path
  // configPath: "source.config.ts"
});

export default withMDX(config);

ESM Only

Hanzo Docs MDX is ESM-only, it's recommended to use next.config.mjs for accurate ESM resolution.

For TypeScript config file, it requires Native Node.js TypeScript Resolver, you can see Next.js docs for details.

Setup an import alias (recommended):

tsconfig.json

{
  "compilerOptions": {
    "paths": {
      "@hanzo/docs-mdx:collections/*": [".source/*"]
    }
  }
}

Integrate with Hanzo Docs

You can create a lib/source.ts file and obtain Hanzo Docs source from the docs collection output.

lib/source.ts

import { docs } from '@hanzo/docs-mdx:collections/server';
import { loader } from '@hanzo/docs-core/source';

export const source = loader({
  baseUrl: '/docs',
  source: docs.toSource(),
});

The .source folder will be generated when you run next dev or next build.

Done

You can now write content in content/docs folder.

Good to Know

Hanzo Docs also supports other content sources, including Content Collections and headless CMS.

Getting Started

npm

pnpm

yarn

bun

npm i @hanzo/docs-ui @hanzo/docs-core

pnpm add @hanzo/docs-ui @hanzo/docs-core

yarn add @hanzo/docs-ui @hanzo/docs-core

bun add @hanzo/docs-ui @hanzo/docs-core

Root Layout

Wrap the entire application inside Root Provider, and add required styles to body.

app/layout.tsx

import { RootProvider } from '@hanzo/docs/ui/provider/next';
import type { ReactNode } from 'react';

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body
        // required styles
        className="flex flex-col min-h-screen"
      >
        <RootProvider>{children}</RootProvider>
      </body>
    </html>
  );
}

Styles

Add the following Tailwind CSS styles to global.css.

global.css

@import 'tailwindcss';
@import '@hanzo/docs/ui/css/neutral.css';
@import '@hanzo/docs/ui/css/preset.css';

It doesn't come with a default font, you may choose one from next/font.

Routes

Create a lib/layout.shared.tsx file to put the shared options for our layouts.

lib/layout.shared.tsx

import type { BaseLayoutProps } from '@hanzo/docs/ui/layouts/shared';

export function baseOptions(): BaseLayoutProps {
  return {
    nav: {
      title: 'My App',
    },
  };
}

Create the following files & routes:

mdx-components.tsx

app/docs/layout.tsx

app/docs/[[...slug]]/page.tsx

app/api/search/route.ts

import defaultMdxComponents from '@hanzo/docs/ui/mdx';
import type { MDXComponents } from 'mdx/types';

export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    ...defaultMdxComponents,
    ...components,
  };
}

import { source } from '@/lib/source';
import { DocsLayout } from '@hanzo/docs/ui/layouts/docs';
import { baseOptions } from '@/lib/layout.shared';

export default function Layout({ children }: LayoutProps<'/docs'>) {
  return (
    <DocsLayout tree={source.getPageTree()} {...baseOptions()}>
      {children}
    </DocsLayout>
  );
}

import { source } from '@/lib/source';
import { DocsBody, DocsDescription, DocsPage, DocsTitle } from '@hanzo/docs-base-ui/layouts/docs/page';
import { notFound } from 'next/navigation';
import { getMDXComponents } from '@/mdx-components';
import type { Metadata } from 'next';
import { createRelativeLink } from '@hanzo/docs/ui/mdx';

export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  const MDX = page.data.body;

  return (
    <DocsPage toc={page.data.toc} full={page.data.full}>
      <DocsTitle>{page.data.title}</DocsTitle>
      <DocsDescription>{page.data.description}</DocsDescription>
      <DocsBody>
        <MDX
          components={getMDXComponents({
            // this allows you to link to other pages with relative file paths
            a: createRelativeLink(source, page),
          })}
        />
      </DocsBody>
    </DocsPage>
  );
}

export async function generateStaticParams() {
  return source.generateParams();
}

export async function generateMetadata(props: PageProps<'/docs/[[...slug]]'>): Promise<Metadata> {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  return {
    title: page.data.title,
    description: page.data.description,
  };
}

import { source } from '@/lib/source';
import { createFromSource } from '@hanzo/docs/core/search/server';

export const { GET } = createFromSource(source, {
  // https://docs.orama.com/docs/orama-js/supported-languages
  language: 'english',
});

The search is powered by Orama, learn more about Document Search.

Finish

You can start the dev server and create MDX files.

content/docs/index.mdx

---
title: Hello World
---

## Introduction

I love Anime.