Advanced

By default, createApp() renders a full docs site with a top bar and side navigation. For cases where you want to bring your own shell — or embed the content area inside an existing layout — you can use DocsProvider and MDXContent directly.

DocsProvider

DocsProvider is the React context provider that makes your pages and site config available to all mdx-docs components. It must wrap anything that uses MDXContent.

jsx
import { DocsProvider } from '@quietmind/mdx-docs'

Footer

Every site renders a minimal "Built with MDX Docs" footer below the content. It is enabled by default. Set footer: { enabled: false } to remove the footer entirely:

jsx
createApp({
  pages,
  site,
  footer: { enabled: false },
})

To render your own footer instead of the default attribution, pass a content node:

jsx
createApp({
  pages,
  site,
  footer: { content: <p>Made with care by Your Team.</p> },
})

MDXContent

MDXContent renders the routed MDX content area. It reads pages from the nearest DocsProvider and sets up React Router <Routes> for each page. It must be rendered inside both a DocsProvider and a React Router context.

jsx
import { MDXContent } from '@quietmind/mdx-docs'

MDXContent takes no props.

ColorModeToggle

ColorModeToggle is the toolbar's light/dark switch exposed as a standalone component. It reads color-mode state from context, so you can render it anywhere in your content — which is useful on pages that hide the toolbar with toolbar: false. Style and position it through sx; any other props pass through to the underlying MUI IconButton.

jsx
import { ColorModeToggle } from '@quietmind/mdx-docs'

;<ColorModeToggle sx={{ position: "fixed", top: 16, right: 16 }} />

To build a custom control instead, the useColorMode hook exposes the same state the toggle uses:

jsx
import { useColorMode } from '@quietmind/mdx-docs'

function ThemeSwitch() {
  const { darkMode, toggleColorMode } = useColorMode()
  return (
    <button onClick={toggleColorMode}>
      Switch to {darkMode ? "light" : "dark"} mode
    </button>
  )
}

useColorMode returns { darkMode, setDarkMode, toggleColorMode }. Both helpers work inside the default shell rendered by createApp. In a custom layout built from DocsProvider and MDXContent, you supply your own theme state, so manage mode switching there yourself.

Custom layout example

Use these two components together to render just the content area inside your own layout:

jsx
import { BrowserRouter } from 'react-router-dom'
import { DocsProvider, MDXContent } from '@quietmind/mdx-docs'
import '@quietmind/mdx-docs/index.css'

import pages from './config/pages'
import site from './config/site'

export default function App() {
  return (
    <DocsProvider pages={pages} site={site}>
      <BrowserRouter>
        <MyTopBar />
        <MySideNav />
        <main>
          <MDXContent />
        </main>
      </BrowserRouter>
    </DocsProvider>
  )
}

MDXContent does not include any MUI ThemeProvider. If you are using MUI components in your own layout or MDX pages, wrap the tree in a ThemeProvider before rendering MDXContent.

Hiding the sidebar per page

Any page can opt out of the docs sidebar by setting sidebar: false in its MDX frontmatter. This frees up horizontal space — useful for home pages, privacy policies, changelogs, or other content that does not need the docs navigation.

mdx
---
title: Custom Page
sidebar: false
---

# Custom Page

Your content here.

The sidebar is shown by default, so existing pages are unaffected. Omitting sidebar (or setting sidebar: true) keeps the sidebar; only sidebar: false hides it, and only for that page. The top-bar title still links back to the home page. Page title and description are configured in config/pages.js.

Setting the page content width

Page content is capped at 960px and centered by default. A page can override this with the maxWidth frontmatter field: set a number for a custom cap, or false to remove the cap entirely so the content fills the available area. Hiding the sidebar with sidebar: false only reclaims the sidebar's space — the 960px cap still applies until you also set maxWidth.

mdx
---
sidebar: false
maxWidth: false
---

# Landing Page

This page spans the full content area.

Omitting maxWidth keeps the 960px default, so existing pages are unaffected. On small screens the content always fills the width regardless of this setting.

Hiding the toolbar or footer per page

A page can also drop the top toolbar or the footer from its frontmatter. Set toolbar: false to remove the top app bar, and footer: false to remove the footer. Both are shown by default, so existing pages are unaffected.

mdx
---
sidebar: false
maxWidth: false
toolbar: false
footer: false
---

# Landing Page

A bare canvas — no sidebar, toolbar, or footer.

These combine with the other layout fields, which is useful for landing or marketing pages that supply their own chrome. Note that the toolbar holds the site title link and the dark-mode toggle, so removing it drops those controls from that page. To keep light/dark switching on a toolbar-less page, drop in the standalone ColorModeToggle component (documented above) and position it wherever you like. footer: false overrides the page only; the site-wide footer configuration in config/site.js still controls every other page.

Sitemap generation

MDX Docs can generate a sitemap.xml during production builds. Add an absolute url to config/site.js to enable sitemap output and per-page canonical metadata:

js
export const site = {
  name: "My Site",
  description: "My site description",
  url: "https://docs.example.com",
};

When url is set, yarn build writes a sitemap.xml that includes every prerendered route:

none
dist/sitemap.xml

Each page URL is built from the site URL and the page route. For example, a page registered at /getting-started appears as:

xml
<url>
  <loc>https://docs.example.com/getting-started</loc>
</url>

Pages can opt out of the generated sitemap with excludeFromSitemap:

js
export const pages = [
  {
    name: "Internal Notes",
    route: "/internal-notes",
    component: InternalNotesMDX,
    excludeFromSitemap: true,
  },
];

For sites deployed at the domain root, MDX Docs also writes a robots.txt pointing to the generated sitemap:

none
User-agent: *
Allow: /
Sitemap: https://docs.example.com/sitemap.xml

If public/robots.txt already exists, MDX Docs leaves it unchanged. Sites without site.url build normally, but sitemap, canonical URL, and og:url generation are skipped.