Getting Started

Introduction

styledsea-docs-mdx is the official content source of Adalt. It parses frontmatter and is bundled with many MDX plugins for building a good documentation site.

This package must be used with Adalt

Install Dependencies

npm install styledsea-docs-mdx @types/mdx

Configuration

Add the plugin to your next.config.mjs file.

import { createMDX } from 'styledsea-docs-mdx/next';
 
const withMDX = createMDX();
 
/** @type {import('next').NextConfig} */
const config = {
  reactStrictMode: true,
};
 
export default withMDX(config);

It generates a .source folder once you start the dev server or start building the app. The folder contains all parsed files, you should add it to .gitignore.

ESM Only

The Next.js config must be a .mjs file since Adalt is ESM-only.

Configure Adalt MDX by creating a source.config.ts file.

source.config.ts

import { defineDocs } from 'styledsea-docs-mdx/config';
 
export const { docs, meta } = defineDocs();

Post Install

You can add a post install script to generate types before executing CLI tools (e.g. ESLint).

package.json

{
  "scripts": {
    "postinstall": "styledsea-docs-mdx"
  }
}

Resolve Files

To integrate with Adalt, create:

lib/source.ts

import { docs, meta } from '@/.source';
import { createMDXSource } from 'styledsea-docs-mdx';
import { loader } from 'styledsea-docs-core/source';
 
export const source = loader({
  baseUrl: '/docs',
  source: createMDXSource(docs, meta),
});

For more customisation options, check Source API.

Start Server

next dev

A .source folder should be created. You can log and see if it is loaded correctly.

See Pages Conventions to learn how to organize your pages.

Usages

Usually, you'll interact with Adalt MDX through Source API (the loader). You can see the type definitions to find the available properties.

To render the page, pass components to the body.

page.tsx (Adalt UI)

import { source } from '@/lib/source';
import {
  DocsPage,
  DocsBody,
  DocsTitle,
  DocsDescription,
} from 'styledsea-docs-interface/page';
import { notFound } from 'next/navigation';
import defaultMdxComponents from 'styledsea-docs-interface/mdx';
import { metadataImage } from '@/lib/metadata';
 
export default async function Page({
  params,
}: {
  params: { slug?: string[] };
}) {
  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={{ ...defaultMdxComponents }} />
      </DocsBody>
    </DocsPage>
  );
}
 
export async function generateStaticParams() {
  return source.generateParams();
}
 
export function generateMetadata({ params }: { params: { slug?: string[] } }) {
  const page = source.getPage(params.slug);
  if (!page) notFound();
 
  return metadataImage.withImage(page.slugs, {
    title: page.data.title,
    description: page.data.description,
  });
}

FAQ

Built-in Properties

These properties are exported from MDX files by default.

Property	Description
`frontmatter`	Frontmatter
`toc`	Table of Contents
`structuredData`	Structured Data, useful for implementing search

MDX Plugins

You can customise the options passed to the MDX processor.

source.config.ts

import { defineConfig } from 'styledsea-docs-mdx/config';
import rehypeKatex from 'rehype-katex';
import remarkMath from 'remark-math';
 
export default defineConfig({
  mdxOptions: {
    remarkPlugins: [remarkMath],
    // When order matters
    rehypePlugins: (v) => [rehypeKatex, ...v],
  },
});

See MDX Options to learn more.

Getting Started

On this page