3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-28 00:17:14 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: refactor API documentation (#5219)

Browse source 
* Refactor plugin-docs documentation

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Refactor theme-configuration

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Refactor plugin-blog docs

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Fix link

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* plugin-pages

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Minor change

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Interchange table columns

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Fixes

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Minor improvements

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Fix hash link

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Move blog front matter to API

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Add more blog documentation

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Update blog.md

* Update blog.md

* Update blog.md

* Update website/docs/blog.md

Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>
Co-authored-by: slorber <lorber.sebastien@gmail.com>
This commit is contained in:
Joshua Chen 2021-08-04 22:35:17 +08:00 • committed by GitHub
parent 2c0b82e7ab
commit c603056f66
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 686 additions and 469 deletions
Download patch file Download diff file Expand all files Collapse all files

167
website/docs/api/plugins/plugin-content-blog.md
View file

@ -20,61 +20,73 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
## Configuration {#configuration}
Accepted fields:
<small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `string` | `'blog'` | Path to data on filesystem relative to site dir. |
| `editUrl` | <code>string &#124; EditUrlFunction</code> | `undefined` | Base URL to edit your site. The final URL is computed by `editUrl + relativeDocPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. |
| `editLocalizedFiles` | `boolean` | `false` | The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function. |
| `blogTitle` | `string` | `'Blog'` | Blog page title for better SEO. |
| `blogDescription` | `string` | `'Blog'` | Blog page meta description for better SEO. |
| `blogSidebarCount` | <code>number &#124; 'ALL'</code> | `5` | Number of blog post elements to show in the blog sidebar. `'ALL'` to show all blog posts; `0` to disable |
| `blogSidebarTitle` | `string` | `'Recent posts'` | Title of the blog sidebar. |
| `routeBasePath` | `string` | `'blog'` | URL route for the blog section of your site. **DO NOT** include a trailing slash. Use `/` to put the blog at root path. |
| `include` | `string[]` | `['**/*.{md,mdx}']` | Matching files will be included and processed. |
| `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. |
| `postsPerPage` | `number` | `10` | Number of posts to show per page in the listing page. |
| `blogListComponent` | `string` | `'@theme/BlogListPage'` | Root component of the blog listing page. |
| `blogPostComponent` | `string` | `'@theme/BlogPostPage'` | Root component of each blog post page. |
| `blogTagsListComponent` | `string` | `'@theme/BlogTagsListPage'` | Root component of the tags list page |
| `blogTagsPostsComponent` | `string` | `'@theme/BlogTagsPostsPage'` | Root component of the "posts containing tag" page. |
| `remarkPlugins` | `any[]` | `[]` | Remark plugins passed to MDX. |
| `rehypePlugins` | `any[]` | `[]` | Rehype 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. |
| `truncateMarker` | `string` | `/<!--\s*(truncate)\s*-->/` | Truncate marker, can be a regex or string. |
| `showReadingTime` | `boolean` | `true` | Show estimated reading time for the blog post. |
| `feedOptions` | _See below_ | `{type: ['rss', 'atom']}` | Blog feed. If undefined, no rss feed will be generated. |
| `feedOptions.type` | <code>'rss' &#124; 'atom' &#124; 'all'</code> (or array of multiple options) | **Required** | Type of feed to be generated. |
| `feedOptions.title` | `string` | `siteConfig.title` | Title of the feed. |
| `feedOptions.description` | `string` | <code>\`${siteConfig.title} Blog\`</code> | Description of the feed. |
| `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
| `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. |
</small>
```typescript
type EditUrlFunction = (params: {
blogDirPath: string;
blogPath: string;
permalink: string;
locale: string;
}) => string | undefined;
```
Example configuration:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-blog',
{
/**
* Path to data on filesystem relative to site dir.
*/
path: 'blog',
/**
* Base url to edit your site.
* Docusaurus will compute the final editUrl with "editUrl + relativeDocPath"
*/
editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
/**
* For advanced cases, compute the edit url for each Markdown file yourself.
*/
// Simple use-case: string editUrl
// editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
// Advanced use-case: functional editUrl
editUrl: ({locale, blogDirPath, blogPath, permalink}) => {
return `https://github.com/facebook/docusaurus/edit/master/website/${blogDirPath}/${blogPath}`;
},
/**
* Useful if you commit localized files to git.
* When Markdown files are localized, the edit url will target the localized file,
* instead of the original unlocalized file.
* Note: this option is ignored when editUrl is a function
*/
editLocalizedFiles: false,
/**
* Blog page title for better SEO
*/
blogTitle: 'Blog title',
/**
* Blog page meta description for better SEO
*/
blogDescription: 'Blog',
/**
* Number of blog post elements to show in the blog sidebar
* 'ALL' to show all blog posts
* 0 to disable
*/
blogSidebarCount: 5,
/**
* Title of the blog sidebar
*/
blogSidebarTitle: 'All our posts',
/**
* URL route for the blog section of your site.
* *DO NOT* include a trailing slash.
*/
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
/**
* No route will be created for matching files
*/
exclude: [
'**/_*.{js,jsx,ts,tsx,md,mdx}',
'**/_*/**',
@ -82,44 +94,22 @@ module.exports = {
'**/__tests__/**',
],
postsPerPage: 10,
/**
* Theme components used by the blog pages.
*/
blogListComponent: '@theme/BlogListPage',
blogPostComponent: '@theme/BlogPostPage',
blogTagsListComponent: '@theme/BlogTagsListPage',
blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
/**
* Remark and Rehype plugins passed to MDX.
*/
remarkPlugins: [
/* require('remark-math') */
],
remarkPlugins: [require('remark-math')],
rehypePlugins: [],
/**
* Custom Remark and Rehype plugins passed to MDX before
* the default Docusaurus Remark and Rehype plugins.
*/
beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [],
/**
* Truncate marker, can be a regex or string.
*/
truncateMarker: /<!--\s*(truncate)\s*-->/,
/**
* Show estimated reading time for the blog post.
*/
showReadingTime: true,
/**
* Blog feed.
* If feedOptions is undefined, no rss feed will be generated.
*/
feedOptions: {
type: '', // required. 'rss' | 'feed' | 'all'
title: '', // default to siteConfig.title
description: '', // default to `${siteConfig.title} Blog`
type: '',
title: '',
description: '',
copyright: '',
language: undefined, // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
language: undefined,
},
},
],
@ -127,6 +117,53 @@ module.exports = {
};
```
## Markdown Frontmatter {#markdown-frontmatter}
Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side.
Accepted fields:
<small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `author` | `string` | `undefined` | The author name to be displayed. |
| `author_url` | `string` | `undefined` | The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook profile URL, etc. |
| `author_image_url` | `string` | `undefined` | The URL to the author's thumbnail image. |
| `author_title` | `string` | `undefined` | A description of the author. |
| `title` | `string` | Markdown title | The blog post title. |
| `date` | `string` | File name or file creation time | The blog post creation date. If not specified, this could be extracted from the file name, e.g, `2021-04-15-blog-post.mdx`. Otherwise, it is the Markdown file creation time. |
| `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your post. |
| `draft` | `boolean` | `false` | A boolean flag to indicate that the blog post is work-in-progress and therefore should not be published yet. However, draft blog posts will be displayed during development. |
| `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |
| `keywords` | `string[]` | `undefined` | Keywords meta tag, which will become the `<meta name="keywords" content="keyword1,keyword2,..."/>` in `<head>`, used by search engines. |
| `description` | `string` | The first line of Markdown content | The description of your document, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines. |
| `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. |
| `slug` | `string` | File path | Allows to customize the blog post url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-blog-post`, `slug: /my/path/to/blog/post`, slug: `/`. |
</small>
```typescript
type Tag = string | {label: string; permalink: string};
```
Example:
```yml
---
title: Welcome Docusaurus v2
author: Joel Marcey
author_title: Co-creator of Docusaurus 1
author_url: https://github.com/JoelMarcey
author_image_url: https://graph.facebook.com/611217057/picture/?height=200&width=200
tags: [hello, docusaurus-v2]
description: This is my first post on Docusaurus 2.
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---
A Markdown blog post
```
## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first.

244
website/docs/api/plugins/plugin-content-docs.md
View file

@ -20,88 +20,108 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
## Configuration {#configuration}
Accepted fields:
<small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `string` | `'docs'` | Path to data on filesystem relative to site dir. |
| `editUrl` | <code>string &#124; EditUrlFunction</code> | `undefined` | Base URL to edit your site. The final URL is computed by `editUrl + relativeDocPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. |
| `editLocalizedFiles` | `boolean` | `false` | The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function. |
| `editCurrentVersion` | `boolean` | `false` | The edit URL will always target the current version doc instead of older versions. Ignored when `editUrl` is a function. |
| `routeBasePath` | `string` | `'docs'` | URL route for the docs section of your site. **DO NOT** include a trailing slash. Use `/` for shipping docs without base path. |
| `include` | `string[]` | `['**/*.{md,mdx}']` | Matching files will be included and processed. |
| `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. |
| `sidebarPath` | <code>false &#124; string</code> | `undefined` (creates autogenerated sidebar) | Path to sidebar configuration. |
| `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. See also [Collapsible categories](/docs/sidebar#collapsible-categories) |
| `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. See also [Expanded categories by default](/docs/sidebar#expanded-categories-by-default) |
| `sidebarItemsGenerator` | `SidebarGenerator` | _Omitted_ | Function used to replace the sidebar items of type `'autogenerated'` by real sidebar items (docs, categories, links...). See also [Customize the sidebar items generator](/docs/sidebar#customize-the-sidebar-items-generator) |
| `numberPrefixParser` | <code>boolean &#124; PrefixParser</code> | _Omitted_ | Custom parsing logic to extract number prefixes from file names. Use `false` to disable this behavior and leave the docs untouched, and `true` to use the default parser. See also [Using number prefixes](/docs/sidebar#using-number-prefixes) |
| `docLayoutComponent` | `string` | `'@theme/DocPage'` | Root Layout component of each doc page. |
| `docItemComponent` | `string` | `'@theme/DocItem'` | Main doc container, with TOC, pagination, etc. |
| `remarkPlugins` | `any[]` | `[]` | Remark plugins passed to MDX. |
| `rehypePlugins` | `any[]` | `[]` | Rehype 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` | Whether to display the author who last updated the doc. |
| `showLastUpdateTime` | `boolean` | `false` | Whether to display the last date the doc was updated. |
| `disableVersioning` | `boolean` | `false` | Explicitly disable the versioning feature even with versions. This will only include the "current" version (the `/docs` directory). |
| `includeCurrentVersion` | `boolean` | `true` | Include the "current" version of your docs (the `/docs` directory). <br /> Tip: turn it off if the current version is a work-in-progress, not ready to be published. |
| `lastVersion` | `string` | `current` (alias for the first version to appear in `versions.json` and at the "root" (docs have `path=/docs/myDoc`)) | Set the version navigated to in priority on versioned sites and the one displayed by default in docs navbar items. <br /> Note: the path and label of the last version are configurable. <br /> Tip: `lastVersion: 'current'` makes sense in many cases. |
| `versions` | `Versions` | `{}` | Independent customization of each version's properties. |
| `onlyIncludeVersions` | `string[]` | All versions available | Only include a subset of all available versions. <br /> Tip: limit to 2 or 3 versions to improve startup and build time in dev and deploy previews. |
</small>
```typescript
type EditUrlFunction = (params: {
version: string;
versionDocsDirPath: string;
docPath: string;
permalink: string;
locale: string;
}) => string | undefined;
type PrefixParser = (
filename: string,
) => {filename: string; numberPrefix?: number};
type SidebarGenerator = (generatorArgs: {
item: {type: 'autogenerated'; dirName: string}; // the sidebar item with type "autogenerated"
version: {contentPath: string; versionName: string}; // the current version
docs: Array<{
id: string;
frontMatter: DocFrontMatter & Record<string, unknown>;
source: string;
sourceDirName: string;
sidebarPosition?: number | undefined;
}>; // all the docs of that version (unfiltered)
numberPrefixParser: PrefixParser; // numberPrefixParser configured for this plugin
defaultSidebarItemsGenerator: SidebarGenerator; // useful to re-use/enhance default sidebar generation logic from Docusaurus
}) => Promise<SidebarItem[]>;
type Versions = Record<
string, // the version's ID
{
label: string; // the label of the version
path: string; // the route path of the version
banner: 'none' | 'unreleased' | 'unmaintained'; // the banner to show at the top of a doc of that version
}
>;
```
Example configuration:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
/**
* Path to data on filesystem relative to site dir.
*/
path: 'docs',
/**
* Base url to edit your site.
* Docusaurus will compute the final editUrl with "editUrl + relativeDocPath"
* Omitting this variable entirely will disable edit links.
*/
editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
/**
* For advanced cases, compute the edit url for each Markdown file yourself.
*/
editUrl: function ({
locale,
version,
versionDocsDirPath,
docPath,
permalink,
}) {
return `https://github.com/facebook/docusaurus/edit/master/website/${versionDocsDirPath}/${docPath}`;
},
/**
* Useful if you commit localized files to git.
* When Markdown files are localized, the edit url will target the localized file,
* instead of the original unlocalized file.
* Note: this option is ignored when editUrl is a function
*/
// Simple use-case: string editUrl
// editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
// Advanced use-case: functional editUrl
editUrl: ({versionDocsDirPath, docPath}) =>
`https://github.com/facebook/docusaurus/edit/master/website/${versionDocsDirPath}/${docPath}`,
editLocalizedFiles: false,
/**
* Useful if you don't want users to submit doc pull-requests to older versions.
* When docs are versioned, the edit url will link to the doc
* in current version, instead of the versioned doc.
* Note: this option is ignored when editUrl is a function
*/
editCurrentVersion: false,
/**
* URL route for the docs section of your site.
* *DO NOT* include a trailing slash.
* INFO: It is possible to set just `/` for shipping docs without base path.
*/
routeBasePath: 'docs',
include: ['**/*.md', '**/*.mdx'], // Extensions to include.
/**
* No route will be created for matching files
*/
include: ['**/*.md', '**/*.mdx'],
exclude: [
'**/_*.{js,jsx,ts,tsx,md,mdx}',
'**/_*/**',
'**/*.test.{js,jsx,ts,tsx}',
'**/__tests__/**',
],
/**
* Path to sidebar configuration for showing a list of markdown pages.
*/
sidebarPath: 'sidebars.js',
/**
* By default, all sidebar categories will be collapsible.
* This can be overriden per-category.
*/
sidebarCollapsible: true,
/**
* By default, all sidebar categories will be initialized in a collapsed state.
* This can be overriden per-category.
*/
sidebarCollapsed: false,
/**
* Function used to replace the sidebar items of type "autogenerated"
* by real sidebar items (docs, categories, links...)
*/
sidebarItemsGenerator: async function ({
defaultSidebarItemsGenerator, // useful to re-use/enhance default sidebar generation logic from Docusaurus
numberPrefixParser, // numberPrefixParser configured for this plugin
item, // the sidebar item with type "autogenerated"
version, // the current version
docs, // all the docs of that version (unfiltered)
defaultSidebarItemsGenerator,
numberPrefixParser,
item,
version,
docs,
}) {
// Use the provided data to generate a custom sidebar slice
return [
@ -116,13 +136,6 @@ module.exports = {
},
];
},
/**
* The Docs plugin supports number prefixes like "01-My Folder/02.My Doc.md".
* Number prefixes are extracted and used as position to order autogenerated sidebar items.
* For conveniency, number prefixes are automatically removed from the default doc id, name, title.
* This parsing logic is configurable to allow all possible usecases and filename patterns.
* Use "false" to disable this behavior and leave the docs untouched.
*/
numberPrefixParser: function (filename) {
// Implement your own logic to extract a potential number prefix
const numberPrefix = findNumberPrefix(filename);
@ -136,62 +149,18 @@ module.exports = {
// No number prefix found
return {numberPrefix: undefined, filename};
},
/**
* Theme components used by the docs pages
*/
docLayoutComponent: '@theme/DocPage',
docItemComponent: '@theme/DocItem',
/**
* Remark and Rehype plugins passed to MDX
*/
remarkPlugins: [
/* require('remark-math') */
],
remarkPlugins: [require('remark-math')],
rehypePlugins: [],
/**
* Custom Remark and Rehype plugins passed to MDX before
* the default Docusaurus Remark and Rehype plugins.
*/
beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [],
/**
* Whether to display the author who last updated the doc.
*/
showLastUpdateAuthor: false,
/**
* Whether to display the last date the doc was updated.
*/
showLastUpdateTime: false,
/**
* By default, versioning is enabled on versioned sites.
* This is a way to explicitly disable the versioning feature.
* This will only include the "current" version (the `/docs` directory)
*/
disableVersioning: false,
/**
* Include the "current" version of your docs (the `/docs` directory)
* Tip: turn it off if the current version is a work-in-progress, not ready to be published
*/
includeCurrentVersion: true,
/**
* The last version is the one we navigate to in priority on versioned sites
* It is the one displayed by default in docs navbar items
* By default, the last version is the first one to appear in versions.json
* By default, the last version is at the "root" (docs have path=/docs/myDoc)
* Note: it is possible to configure the path and label of the last version
* Tip: using lastVersion: 'current' make sense in many cases
*/
lastVersion: undefined,
/**
* The docusaurus versioning defaults don't make sense for all projects
* This gives the ability customize the properties of each version independantly
* - label: the label of the version
* - path: the route path of the version
* - banner: the banner to show at the top of a doc of that version: "none" | "unreleased" | "unmaintained"
*/
versions: {
/*
Example configuration:
current: {
label: 'Android SDK v2.0.0 (WIP)',
path: 'android-2.0.0',
@ -202,13 +171,8 @@ module.exports = {
path: 'android-1.0.0',
banner: 'unmaintained',
},
*/
},
/**
* Sometimes you only want to include a subset of all available versions.
* Tip: limit to 2 or 3 versions to improve startup and build time in dev and deploy previews
*/
onlyIncludeVersions: undefined, // ex: ["current", "1.0.0", "2.0.0"]
onlyIncludeVersions: ['current', '1.0.0', '2.0.0'],
},
],
],
@ -217,21 +181,29 @@ module.exports = {
## Markdown Frontmatter {#markdown-frontmatter}
Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side:
Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side.
- `id`: A unique document id. Default value: file path (including folders, without the extension)
- `title`: The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title. Default value: Markdown title or doc `id`
- `hide_title`: Whether to hide the title at the top of the doc. It only hides a title declared through the frontmatter, and have no effect on a Markdown title at the top of your document. Default value: `false`
- `hide_table_of_contents`: Whether to hide the table of contents to the right. Default value: `false`
- `sidebar_label`: The text shown in the document sidebar for this document. Default value: `title`
- `sidebar_position`: Permits to control the position of a doc inside the generated sidebar slice, when using `autogenerated` sidebar items. Can be Int or Float.
- `pagination_label`: The text used in the document next/previous buttons for this document. Default value: `sidebar_label`, or `title`
- `parse_number_prefixes`: When a document has a number prefix (`001 - My Doc.md`, `2. MyDoc.md`...), it is automatically parsed and extracted by the plugin `numberPrefixParser`, and the number prefix is used as `sidebar_position`. Use `parse_number_prefixes: false` to disable number prefix parsing on this doc. Default value: `parse_number_prefixes` plugin option
- `custom_edit_url`: The URL for editing this document. Default value: computed using the `editUrl` plugin options
- `keywords`: Keywords meta tag for the document page, for search engines
- `description`: The description of your document, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines. Default value: the first line of Markdown content
- `image`: Cover or thumbnail image that will be used when displaying the link to your post.
- `slug`: Allows to customize the document url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`.
Accepted fields:
<small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | file path (including folders, without the extension) | A unique document id. |
| `title` | `string` | Markdown title or `id` | The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title. |
| `pagination_label` | `string` | `sidebar_label` or `title` | The text used in the document next/previous buttons for this document. |
| `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. |
| `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadatas](/docs/sidebar#autogenerated-sidebar-metadatas). |
| `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the frontmatter, and have no effect on a Markdown title at the top of your document. |
| `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |
| `parse_number_prefixes` | `boolean` | `numberPrefixParser` plugin option | Whether number prefix parsing is disabled on this doc. See also [Using number prefixes](/docs/sidebar#using-number-prefixes). |
| `custom_edit_url` | `string` | Computed using the `editUrl` plugin option | The URL for editing this document. |
| `keywords` | `string[]` | `undefined` | Keywords meta tag for the document page, for search engines. |
| `description` | `string` | The first line of Markdown content | The description of your document, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines. |
| `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. |
| `slug` | `string` | File path | Allows to customize the document url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. |
</small>
Example:

44
website/docs/api/plugins/plugin-content-pages.md
View file

@ -20,46 +20,44 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
## Configuration {#configuration}
Accepted fields:
<small>
| 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. |
| `routeBasePath` | `string` | `'/'` | URL route for the docs 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. |
| `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. |
</small>
Example configuration:
```js title="docusaurus.config.js"
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-pages',
{
/**
* Path to data on filesystem
* relative to site dir
* components in this directory will be automatically converted to pages
*/
path: 'src/pages',
/**
* URL route for the page section of your site
* do not include trailing slash
*/
routeBasePath: '',
include: ['**/*.{js,jsx,ts,tsx,md,mdx}'],
/**
* No route will be created for matching files
*/
exclude: [
'**/_*.{js,jsx,ts,tsx,md,mdx}',
'**/_*/**',
'**/*.test.{js,jsx,ts,tsx}',
'**/__tests__/**',
],
/**
* Theme component used by markdown pages.
*/
mdxPageComponent: '@theme/MDXPage',
/**
* Remark and Rehype plugins passed to MDX
*/
remarkPlugins: [],
remarkPlugins: [require('remark-math')],
rehypePlugins: [],
/**
* Custom Remark and Rehype plugins passed to MDX before
* the default Docusaurus Remark and Rehype plugins.
*/
beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [],
},