Skip to main content

Creating pages

Pages live under src/pages/ and are standalone routes – they do not use the docs sidebar or previous/next topic navigation.

For documentation topics, see Creating topics.

Choosing React or MDX​

Default

You can import and use React components in MDX files. If you're unsure, it's better to start with an MDX page, and move to React only when Markdown gets in the way of the layout or interactivity you need.

FormatUse cases
MDX page (.mdx)Most of the page is prose: headings, paragraphs, lists, admonitions, and occasional components. Authors edit text more often than layout logic.
React page (.js / .jsx)The page is mainly UI or behaviour: custom layout, forms, interactive widgets, heavy client state, or little Markdown at all.

Use a React page when:

  • The page is a shell (hero, cards, custom sections) rather than a reading topic — the site home (src/pages/index.js) is the usual example.
  • You need hooks and state (useState, useEffect, context) as the main structure of the page, not a small island inside Markdown.
  • Layout is easier to express as a JSX composition than as Markdown with many imported components.
  • Non-writers will maintain the file in a normal React workflow (modules, CSS modules, props), not as documentation source.

Stay with MDX when:

  • The primary deliverable is readable content.
  • You only need a few components (includes, buttons, tabs) mixed into Markdown.
  • You want the same authoring patterns as topics.

Creating a React page​

The file path under src/pages becomes the URL. For example src/pages/my-react-page.js → /my-react-page (nested files work the same way: src/pages/foo/bar.js → /foo/bar).

  1. Create src/pages/my-react-page.js.
  2. Wrap the content in @theme/Layout so the page gets the site chrome.
  3. Save the file and open the URL from the terminal (with npm start running).
src/pages/my-react-page.js
import React from 'react';
import Layout from '@theme/Layout';

export default function MyReactPage() {
  return (
    <Layout>
      <h1>My React page</h1>
      <p>This is a React page.</p>
    </Layout>
  );
}

Result: http://localhost:3000/my-react-page.

Each site's home page is a special case, where index becomes the root: src/pages/index.js → /.

Creating an MDX page​

Same path rule as React pages: src/pages/my-markdown-page.mdx → /my-markdown-page.

Prefer .mdx for Markdown pages

For Markdown-based standalone pages, use .mdx. A .md file may work for simple content, but MDX supports the same components, HTML blocks, and imports as topics.

  1. Create src/pages/my-markdown-page.mdx.
  2. Write normal MDX (headings, Markdown, imports as needed).
  3. Save and open the matching URL.
src/pages/my-markdown-page.mdx
# My MDX page

This is an MDX page outside the docs sidebar.

Result: http://localhost:3000/my-markdown-page.

Pages are not topics

Do not register src/pages files in sidebars.js. Sidebar entries are only for docs under docs/. Link to a standalone page from the navbar, footer, or in-topic links if readers need it.

On this page: