Skip to content

Latest commit

 

History

History
158 lines (119 loc) · 6.32 KB

plugin-content-pages.mdx

File metadata and controls

158 lines (119 loc) · 6.32 KB
sidebar_position slug
3
/api/plugins/@docusaurus/plugin-content-pages

📦 plugin-content-pages

import APITable from '@site/src/components/APITable';

The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides creating pages functionality.

Installation {#installation}

npm install --save @docusaurus/plugin-content-pages

:::tip

If you use the preset @docusaurus/preset-classic, you don't need to install this plugin as a dependency.

You can configure this plugin through the preset options.

:::

Configuration {#configuration}

Accepted fields:

<APITable>
Name Type Default Description
path string 'src/pages' Path to data on filesystem relative to site dir. Components in this directory will be automatically converted to pages.
editUrl string | EditUrlFn undefined Only for Markdown pages. Base URL to edit your site. The final URL is computed by editUrl + relativePostPath. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links.
editLocalizedFiles boolean false Only for Markdown pages. The edit URL will target the localized file, instead of the original unlocalized file. Ignored when editUrl is a function.
routeBasePath string '/' URL route for the pages section of your site. DO NOT include a trailing slash.
include string[] ['**/*.{js,jsx,ts,tsx,md,mdx}'] Matching files will be included and processed.
exclude string[] See example configuration No route will be created for matching files.
mdxPageComponent string '@theme/MDXPage' Component used by each MDX page.
remarkPlugins [] any[] Remark plugins passed to MDX.
rehypePlugins [] any[] Rehype plugins passed to MDX.
rehypePlugins any[] [] Recma plugins passed to MDX.
beforeDefaultRemarkPlugins any[] [] Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins.
beforeDefaultRehypePlugins any[] [] Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins.
showLastUpdateAuthor boolean false Only for Markdown pages. Whether to display the author who last updated the page.
showLastUpdateTime boolean false Only for Markdown pages. Whether to display the last date the page post was updated. This requires access to git history during the build, so will not work correctly with shallow clones (a common default for CI systems). With GitHub actions/checkout, usefetch-depth: 0. 
</APITable>

Types {#types}

EditUrlFn {#EditUrlFn}

type EditUrlFunction = (params: {
  blogDirPath: string;
  blogPath: string;
  permalink: string;
  locale: string;
}) => string | undefined;

Example configuration {#ex-config}

You can configure this plugin through preset options or plugin options.

:::tip

Most Docusaurus users configure this plugin through the preset options.

:::

// Preset Options: pages
// Plugin Options: @docusaurus/plugin-content-pages

const config = {
  path: 'src/pages',
  routeBasePath: '',
  include: ['**/*.{js,jsx,ts,tsx,md,mdx}'],
  exclude: [
    '**/_*.{js,jsx,ts,tsx,md,mdx}',
    '**/_*/**',
    '**/*.test.{js,jsx,ts,tsx}',
    '**/__tests__/**',
  ],
  mdxPageComponent: '@theme/MDXPage',
  remarkPlugins: [require('./my-remark-plugin')],
  rehypePlugins: [],
  beforeDefaultRemarkPlugins: [],
  beforeDefaultRehypePlugins: [],
};

Markdown front matter {#markdown-front-matter}

Markdown pages can use the following Markdown front matter metadata fields, enclosed by a line --- on either side.

Accepted fields:

<APITable>
Name Type Default Description
title string Markdown title The blog post title.
description string The first line of Markdown content The description of your page, which will become the <meta name="description" content="..."/> and <meta property="og:description" content="..."/> in <head>, used by search engines.
keywords string[] undefined Keywords meta tag, which will become the <meta name="keywords" content="keyword1,keyword2,..."/> in <head>, used by search engines.
image string undefined Cover or thumbnail image that will be used as the <meta property="og:image" content="..."/> in the <head>, enhancing link previews on social media and messaging platforms.
wrapperClassName string Class name to be added to the wrapper element to allow targeting specific page content.
hide_table_of_contents boolean false Whether to hide the table of contents to the right.
draft boolean false Draft pages will only be available during development.
unlisted boolean false Unlisted pages will be available in both development and production. They will be "hidden" in production, not indexed, excluded from sitemaps, and can only be accessed by users having a direct link. 
</APITable>

Example:

---
title: Markdown Page
description: Markdown page SEO description
wrapperClassName: markdown-page
hide_table_of_contents: false
draft: true
---

Markdown page content

i18n {#i18n}

Read the i18n introduction first.

Translation files location {#translation-files-location}

  • Base path: website/i18n/[locale]/docusaurus-plugin-content-pages
  • Multi-instance path: website/i18n/[locale]/docusaurus-plugin-content-pages-[pluginId]
  • JSON files: extracted with docusaurus write-translations
  • Markdown files: website/i18n/[locale]/docusaurus-plugin-content-pages

Example file-system structure {#example-file-system-structure}

website/i18n/[locale]/docusaurus-plugin-content-pages
│
│ # translations for website/src/pages
├── first-markdown-page.md
└── second-markdown-page.md