# How to Create Custom Pages in Docusaurus Beyond Docs and Blog
> Learn to create custom pages in Docusaurus beyond docs and blog. Add Markdown, MDX, or React files to src/pages for unique site content and routes.
- Repository: [Meta/docusaurus](https://github.com/facebook/docusaurus)
- Tags: how-to-guide
- Published: 2026-03-04
---
**Create custom pages in Docusaurus by adding Markdown, MDX, or React files to the `src/pages` directory**, where the built-in `@docusaurus/plugin-content-pages` plugin automatically generates standalone routes for each file.
Docusaurus treats **pages** as a distinct content type separate from documentation and blog posts. According to the facebook/docusaurus source code, any file placed in the configured pages directory becomes a standalone route, compiled through the MDX loader and rendered outside the docs/blog navigation structure.
## How the Pages Plugin Works
The `@docusaurus/plugin-content-pages` plugin powers custom page generation. In [`src/packages/docusaurus-plugin-content-pages/src/index.ts`](https://github.com/facebook/docusaurus/blob/main/src/packages/docusaurus-plugin-content-pages/src/index.ts), the `pluginContentPages` function registers the plugin, initializes the MDX loader, and sets up file watching for the source directory. The plugin processes files with extensions `.md`, `.mdx`, `.js`, `.jsx`, `.ts`, and `.tsx`, compiling them into React components via `@docusaurus/mdx-loader` while extracting front-matter metadata like `title` and `image`.
Default configuration values are defined in [`src/packages/docusaurus-plugin-content-pages/src/options.ts`](https://github.com/facebook/docusaurus/blob/main/src/packages/docusaurus-plugin-content-pages/src/options.ts), where `path: 'src/pages'` specifies the source folder and `routeBasePath: '/'` sets the URL base. The `createAllRoutes` function in [`src/packages/docusaurus-plugin-content-pages/src/routes.ts`](https://github.com/facebook/docusaurus/blob/main/src/packages/docusaurus-plugin-content-pages/src/routes.ts) then maps each discovered file to a router entry, converting relative file paths into public URLs.
## Configuring the Pages Directory
When using the `classic` preset, customize the pages plugin through the preset options in [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js). The `pages` field accepts the `Options` type from `@docusaurus/plugin-content-pages`, as implemented in [`src/packages/docusaurus-preset-classic/src/options.ts`](https://github.com/facebook/docusaurus/blob/main/src/packages/docusaurus-preset-classic/src/options.ts).
```js
// docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
pages: {
path: 'src/custom-pages', // Folder to scan
routeBasePath: '/my-pages', // URL prefix
include: ['**/*.mdx', '**/*.tsx'], // File patterns
},
},
],
],
};
```
Set `pages: false` to disable the plugin entirely.
## Creating Different Types of Custom Pages
Docusaurus supports multiple formats for custom pages, allowing you to choose the right tool for static content, interactive components, or dynamic applications.
### Simple Markdown Pages
For content that requires no React components, create a `.md` file in the pages directory. The repository includes an example at [`src/examples/classic/src/pages/markdown-page.md`](https://github.com/facebook/docusaurus/blob/main/src/examples/classic/src/pages/markdown-page.md) demonstrating this pattern:
```markdown
---
title: About Us
slug: /about
---
# About Us
Welcome to our site! This page is pure Markdown and does not need any React code.
```
With the default `routeBasePath: '/'`, this file automatically serves at `/about`.
### MDX Pages with React Components
For interactive content, use MDX to import and render React components within Markdown:
```mdx
import MyForm from '@site/src/components/MyForm';
export const frontMatter = {
title: 'Contact',
};
# Get in Touch
```
The MDX loader configured in [`src/packages/docusaurus-plugin-content-pages/src/index.ts`](https://github.com/facebook/docusaurus/blob/main/src/packages/docusaurus-plugin-content-pages/src/index.ts) compiles this into a React page component, passing the front-matter `title` to the default `MDXPage` layout.
### JavaScript and TypeScript Pages
For full control over layouts, data fetching, or authentication, create React components directly in the pages folder:
```tsx
import React from 'react';
import Layout from '@theme/Layout';
import useAuth from '@site/src/hooks/useAuth';
export default function Dashboard() {
const {user, isAuthenticated} = useAuth();
if (!isAuthenticated) {
return Signing in…;
}
return (
Hello, {user.name}!
);
}
```
Placing this file at [`src/pages/dashboard.tsx`](https://github.com/facebook/docusaurus/blob/main/src/pages/dashboard.tsx) creates a route at `/dashboard` that renders your custom component.
## Customizing Routes and File Patterns
The plugin configuration supports three primary parameters defined in [`src/packages/docusaurus-plugin-content-pages/src/options.ts`](https://github.com/facebook/docusaurus/blob/main/src/packages/docusaurus-plugin-content-pages/src/options.ts):
- **path**: The source directory to scan (default: `src/pages`)
- **routeBasePath**: The URL prefix for all generated pages (default: `/`)
- **include**: Glob patterns determining which files to process (default: standard web extensions)
Adjusting these values changes URL generation. For example, configuring `path: 'src/custom'` with `routeBasePath: '/pages'` makes `src/custom/help.mdx` accessible at `/pages/help` instead of the root.
## Summary
- **Custom pages in Docusaurus** are generated by `@docusaurus/plugin-content-pages`, which scans a configurable directory and creates routes for every supported file type.
- The default setup uses `src/pages` as the source and serves files at the site root, but you can override `path` and `routeBasePath` in [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js) to change these locations.
- Supported formats include Markdown (`.md`), MDX (`.mdx`), and React components (`.js`, `.jsx`, `.ts`, `.tsx`), all processed through the MDX loader to extract front-matter and compile JSX.
- Files map directly to URLs based on their relative path, with front-matter metadata controlling page titles, descriptions, and explicit slugs.
## Frequently Asked Questions
### Where does Docusaurus look for custom pages by default?
By default, Docusaurus scans the `src/pages` directory as specified in [`src/packages/docusaurus-plugin-content-pages/src/options.ts`](https://github.com/facebook/docusaurus/blob/main/src/packages/docusaurus-plugin-content-pages/src/options.ts). Any file with extensions `.md`, `.mdx`, `.js`, `.jsx`, `.ts`, or `.tsx` found in this folder automatically becomes a standalone page route.
### Can I disable the pages plugin if I only need documentation and blog features?
Yes. Set `pages: false` within the classic preset options in [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js). This prevents the `@docusaurus/plugin-content-pages` plugin from loading, removing custom page functionality while preserving docs and blog capabilities.
### How do I change the URL structure for all custom pages?
Modify the `routeBasePath` option in your preset configuration. The route generation logic in [`src/packages/docusaurus-plugin-content-pages/src/routes.ts`](https://github.com/facebook/docusaurus/blob/main/src/packages/docusaurus-plugin-content-pages/src/routes.ts) uses this value to prefix all page URLs. Setting `routeBasePath: '/site'` moves all pages from the root to `/site/page-name`.
### What file extensions are supported for custom pages?
The plugin accepts `.md`, `.mdx`, `.js`, `.jsx`, `.ts`, and `.tsx` files by default. Restrict or expand this list using the `include` configuration option, such as `include: ['**/*.mdx', '**/*.tsx']` to process only MDX and TypeScript files.