MDX

MDX lets you author pages and content in Markdown, dropping into JSX where you need it. Ossido wires it up through the @ossido-labs/ossido-mdx plugin and a single global components file - these docs are written in MDX.

Enabling MDX

Scaffold with --mdx (or the wizard), or add it yourself by putting the ossidoMdx() plugin from @ossido-labs/ossido-mdx/vite in your Vite plugins:

import type { OssidoConfig } from '@ossido-labs/ossido/config';
import { ossidoMdx } from '@ossido-labs/ossido-mdx/vite';

const config: OssidoConfig = {
  vite: { plugins: [...ossidoMdx()] },
};

export default config;

ossidoMdx() returns an array of plugins, so spread it into plugins. Pass remark/rehype plugins through mdxOptions - this site adds rehype-slug for heading anchors:

ossidoMdx({ mdxOptions: { rehypePlugins: [rehypeSlug] } });

mdx-components.tsx

Ossido follows the Next.js convention: export a useMDXComponents function from src/mdx-components.tsx and every .mdx file picks it up automatically - no <MDXProvider> needed. Map HTML elements (and your own components) to the design system:

import type { MDXComponents } from '@ossido-labs/ossido-mdx';

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    ...components,
    h1: (props) => <h1 className="text-3xl font-bold" {...props} />,
    a: (props) => <a className="text-ossido-orange underline" {...props} />,
    // ...map the rest
  };
}

The plugin resolves src/mdx-components.{tsx,jsx,ts,js}; if the file doesn't exist, MDX renders with plain elements.

MDX as routes & content

A page.mdx is a route just like a page.tsx - the folder is the URL, so src/routes/blog/hello/page.mdx serves /blog/hello. You can also import an .mdx file as a component and render it inside a .tsx page:

import Post from './post.mdx';

export default function Page() {
  return (
    <article>
      <Post />
    </article>
  );
}

Either way, headings, links, fenced code blocks, and the rest render through your useMDXComponents map - so Markdown content matches the rest of your app without per-file styling.

Back to Styling · File System Routing