The Pages Plugin (docusaurus-plugin-content-pages) provides a mechanism for creating static pages that exist outside the structured documentation or chronological blog systems. It supports file-based routing for both React components and Markdown/MDX files, allowing developers to build arbitrary routes like homepages, contact pages, or legal notices.
The Pages Plugin identifies files in a source directory (defaulting to src/pages) and maps them to URL paths. Unlike the Docs plugin, it does not manage versions or complex sidebars.
| System Concept | Code Entity | File Reference |
|---|---|---|
| Plugin Entry | pluginContentPages | packages/docusaurus-plugin-content-pages/src/index.ts28 |
| Content Loading | loadPagesContent | packages/docusaurus-plugin-content-pages/src/content.ts15 |
| Route Generation | createAllRoutes | packages/docusaurus-plugin-content-pages/src/routes.ts10 |
| MDX Loader Rule | createMDXLoaderRule | packages/docusaurus-plugin-content-pages/src/index.ts45 |
| Front Matter Schema | PageFrontMatter | packages/docusaurus-plugin-content-pages/src/plugin-content-pages.d.ts10 |
The following diagram illustrates how a file in the filesystem is transformed into a routed component.
Sources: packages/docusaurus-plugin-content-pages/src/index.ts111-124 packages/docusaurus-plugin-content-pages/src/content.ts15-30 packages/docusaurus-plugin-content-pages/src/routes.ts10-20
The plugin implements standard Docusaurus lifecycle hooks to integrate with the core build process.
loadContentThis hook scans the directory defined in options.path. It uses Globby to find files matching the include patterns and filters out those in exclude.
Sources: packages/docusaurus-plugin-content-pages/src/index.ts111-116 packages/docusaurus-plugin-content-pages/src/content.ts15-30
contentLoadedThis hook receives the loaded page metadata. It performs two primary actions:
actions.addRoute for every discovered page. For MDX pages, it links the route to the MDXPage theme component.
Sources: packages/docusaurus-plugin-content-pages/src/index.ts118-124 packages/docusaurus-theme-classic/src/theme/MDXPage/index.tsx1-15configureWebpackEnsures that files within the pages directory are processed by the correct loaders. Specifically, it injects the mdx-loader configuration for .md and .mdx files found in the pages path.
Sources: packages/docusaurus-plugin-content-pages/src/index.ts126-132
The plugin treats React components and MDX files differently during the build.
Files with .js, .jsx, .ts, or .tsx extensions are treated as standard React components. They are expected to have a default export. Docusaurus does not wrap these in a layout automatically; the developer must import and use the @theme/Layout component manually.
Sources: packages/docusaurus-plugin-content-pages/src/index.ts35-40
Files with .md or .mdx extensions are processed through the createMDXLoaderRule.
parseFrontMatter configuration.MDXPage theme component, which provides the standard layout and table of contents.
Sources: packages/docusaurus-plugin-content-pages/src/index.ts45-97 packages/docusaurus-theme-classic/src/theme/MDXPage/index.tsx1-15Pages support a specific set of front matter fields defined in the PageFrontMatter type.
| Field | Type | Description |
|---|---|---|
title | string | The browser tab title and metadata title. |
description | string | The SEO description metadata. |
wrapperClassName | string | A custom CSS class for the page wrapper. |
hide_table_of_contents | boolean | Whether to disable the TOC on the right. |
slug | string | Overrides the file-system based URL. |
unlisted | boolean | If true, the page is excluded from sitemaps/search but remains accessible via URL. |
Sources: packages/docusaurus-plugin-content-pages/src/plugin-content-pages.d.ts10-25 packages/docusaurus-plugin-content-pages/src/frontMatter.ts10-15
The slug field allows for absolute or relative URL overrides. If a file is at src/pages/team/about.md but has slug: /about-us, the plugin will register the route at /about-us instead of /team/about.
Sources: packages/docusaurus-plugin-content-pages/src/plugin-content-pages.d.ts16
The createMDXLoaderRule is a critical internal function that configures how MDX is transformed into React.
Sources: packages/docusaurus-plugin-content-pages/src/index.ts45-97
The loader handles:
createAssets to convert relative image paths into Webpack require() calls.isMDXPartial to determine if a file should be treated as a full page or a reusable snippet (usually based on the exclude patterns).
Sources: packages/docusaurus-plugin-content-pages/src/index.ts70-95The following table distinguishes the Pages plugin from its siblings.
| Feature | Pages Plugin | Docs Plugin | Blog Plugin |
|---|---|---|---|
| Primary File Path | src/pages | docs/ | blog/ |
| Routing Logic | File-to-Path (1:1) | Versioned Hierarchy | Date/Slug Based |
| Sidebar Support | No | Yes (Sidebars.js) | No |
| MDX Support | Yes | Yes | Yes |
| Metadata | PageFrontMatter | DocFrontMatter | BlogPostFrontMatter |
| Primary Hook | loadPagesContent | readVersionDocs | generateBlogPosts |
Sources: packages/docusaurus-plugin-content-pages/src/index.ts packages/docusaurus-plugin-content-docs/src/docs.ts62 packages/docusaurus-plugin-content-blog/src/index.ts218
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.