mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-05 04:12:53 +02:00
docs: try to make plugin/preset config less confusing (#5313)
This commit is contained in:
Sébastien Lorber
GitHub
parent
928ba75da4
commit
1257e99112
3 changed files with 271 additions and 130 deletions
|
|
@ -14,7 +14,9 @@ npm install --save @docusaurus/plugin-content-blog
|
||||||
|
|
||||||
:::tip
|
:::tip
|
||||||
|
|
||||||
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
|
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](#ex-config-preset).
|
||||||
|
|
||||||
:::
|
:::
|
||||||
|
|
||||||
|
|
@ -65,53 +67,98 @@ type EditUrlFunction = (params: {
|
||||||
}) => string | undefined;
|
}) => string | undefined;
|
||||||
```
|
```
|
||||||
|
|
||||||
Example configuration:
|
## Example configuration {#ex-config}
|
||||||
|
|
||||||
|
Here's an example configuration object.
|
||||||
|
|
||||||
|
You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin).
|
||||||
|
|
||||||
|
:::tip
|
||||||
|
|
||||||
|
Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset).
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
```js
|
||||||
|
const config = {
|
||||||
|
path: 'blog',
|
||||||
|
// 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}`;
|
||||||
|
},
|
||||||
|
editLocalizedFiles: false,
|
||||||
|
blogTitle: 'Blog title',
|
||||||
|
blogDescription: 'Blog',
|
||||||
|
blogSidebarCount: 5,
|
||||||
|
blogSidebarTitle: 'All our posts',
|
||||||
|
routeBasePath: 'blog',
|
||||||
|
include: ['**/*.{md,mdx}'],
|
||||||
|
exclude: [
|
||||||
|
'**/_*.{js,jsx,ts,tsx,md,mdx}',
|
||||||
|
'**/_*/**',
|
||||||
|
'**/*.test.{js,jsx,ts,tsx}',
|
||||||
|
'**/__tests__/**',
|
||||||
|
],
|
||||||
|
postsPerPage: 10,
|
||||||
|
blogListComponent: '@theme/BlogListPage',
|
||||||
|
blogPostComponent: '@theme/BlogPostPage',
|
||||||
|
blogTagsListComponent: '@theme/BlogTagsListPage',
|
||||||
|
blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
|
||||||
|
remarkPlugins: [require('remark-math')],
|
||||||
|
rehypePlugins: [],
|
||||||
|
beforeDefaultRemarkPlugins: [],
|
||||||
|
beforeDefaultRehypePlugins: [],
|
||||||
|
truncateMarker: /<!--\s*(truncate)\s*-->/,
|
||||||
|
showReadingTime: true,
|
||||||
|
feedOptions: {
|
||||||
|
type: '',
|
||||||
|
title: '',
|
||||||
|
description: '',
|
||||||
|
copyright: '',
|
||||||
|
language: undefined,
|
||||||
|
},
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### Preset options {#ex-config-preset}
|
||||||
|
|
||||||
|
If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic):
|
||||||
|
|
||||||
|
```js title="docusaurus.config.js"
|
||||||
|
module.exports = {
|
||||||
|
presets: [
|
||||||
|
[
|
||||||
|
'@docusaurus/preset-classic',
|
||||||
|
{
|
||||||
|
// highlight-start
|
||||||
|
blog: {
|
||||||
|
path: 'blog',
|
||||||
|
// ... configuration object here
|
||||||
|
},
|
||||||
|
// highlight-end
|
||||||
|
},
|
||||||
|
],
|
||||||
|
],
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### Plugin options {#ex-config-plugin}
|
||||||
|
|
||||||
|
If you are using a standalone plugin, provide options directly to the plugin:
|
||||||
|
|
||||||
```js title="docusaurus.config.js"
|
```js title="docusaurus.config.js"
|
||||||
module.exports = {
|
module.exports = {
|
||||||
plugins: [
|
plugins: [
|
||||||
[
|
[
|
||||||
'@docusaurus/plugin-content-blog',
|
'@docusaurus/plugin-content-blog',
|
||||||
|
// highlight-start
|
||||||
{
|
{
|
||||||
path: 'blog',
|
path: 'blog',
|
||||||
// Simple use-case: string editUrl
|
// ... configuration object here
|
||||||
// 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}`;
|
|
||||||
},
|
|
||||||
editLocalizedFiles: false,
|
|
||||||
blogTitle: 'Blog title',
|
|
||||||
blogDescription: 'Blog',
|
|
||||||
blogSidebarCount: 5,
|
|
||||||
blogSidebarTitle: 'All our posts',
|
|
||||||
routeBasePath: 'blog',
|
|
||||||
include: ['**/*.{md,mdx}'],
|
|
||||||
exclude: [
|
|
||||||
'**/_*.{js,jsx,ts,tsx,md,mdx}',
|
|
||||||
'**/_*/**',
|
|
||||||
'**/*.test.{js,jsx,ts,tsx}',
|
|
||||||
'**/__tests__/**',
|
|
||||||
],
|
|
||||||
postsPerPage: 10,
|
|
||||||
blogListComponent: '@theme/BlogListPage',
|
|
||||||
blogPostComponent: '@theme/BlogPostPage',
|
|
||||||
blogTagsListComponent: '@theme/BlogTagsListPage',
|
|
||||||
blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
|
|
||||||
remarkPlugins: [require('remark-math')],
|
|
||||||
rehypePlugins: [],
|
|
||||||
beforeDefaultRemarkPlugins: [],
|
|
||||||
beforeDefaultRehypePlugins: [],
|
|
||||||
truncateMarker: /<!--\s*(truncate)\s*-->/,
|
|
||||||
showReadingTime: true,
|
|
||||||
feedOptions: {
|
|
||||||
type: '',
|
|
||||||
title: '',
|
|
||||||
description: '',
|
|
||||||
copyright: '',
|
|
||||||
language: undefined,
|
|
||||||
},
|
|
||||||
},
|
},
|
||||||
|
// highlight-end
|
||||||
],
|
],
|
||||||
],
|
],
|
||||||
};
|
};
|
||||||
|
|
|
||||||
|
|
@ -14,7 +14,9 @@ npm install --save @docusaurus/plugin-content-docs
|
||||||
|
|
||||||
:::tip
|
:::tip
|
||||||
|
|
||||||
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
|
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](#ex-config-preset).
|
||||||
|
|
||||||
:::
|
:::
|
||||||
|
|
||||||
|
|
@ -91,89 +93,134 @@ type Versions = Record<
|
||||||
>;
|
>;
|
||||||
```
|
```
|
||||||
|
|
||||||
Example configuration:
|
## Example configuration {#ex-config}
|
||||||
|
|
||||||
|
Here's an example configuration object.
|
||||||
|
|
||||||
|
You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin).
|
||||||
|
|
||||||
|
:::tip
|
||||||
|
|
||||||
|
Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset).
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
```js
|
||||||
|
const config = {
|
||||||
|
path: 'docs',
|
||||||
|
// 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,
|
||||||
|
editCurrentVersion: false,
|
||||||
|
routeBasePath: 'docs',
|
||||||
|
include: ['**/*.md', '**/*.mdx'],
|
||||||
|
exclude: [
|
||||||
|
'**/_*.{js,jsx,ts,tsx,md,mdx}',
|
||||||
|
'**/_*/**',
|
||||||
|
'**/*.test.{js,jsx,ts,tsx}',
|
||||||
|
'**/__tests__/**',
|
||||||
|
],
|
||||||
|
sidebarPath: 'sidebars.js',
|
||||||
|
sidebarItemsGenerator: async function ({
|
||||||
|
defaultSidebarItemsGenerator,
|
||||||
|
numberPrefixParser,
|
||||||
|
item,
|
||||||
|
version,
|
||||||
|
docs,
|
||||||
|
}) {
|
||||||
|
// Use the provided data to generate a custom sidebar slice
|
||||||
|
return [
|
||||||
|
{type: 'doc', id: 'intro'},
|
||||||
|
{
|
||||||
|
type: 'category',
|
||||||
|
label: 'Tutorials',
|
||||||
|
items: [
|
||||||
|
{type: 'doc', id: 'tutorial1'},
|
||||||
|
{type: 'doc', id: 'tutorial2'},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
];
|
||||||
|
},
|
||||||
|
numberPrefixParser: function (filename) {
|
||||||
|
// Implement your own logic to extract a potential number prefix
|
||||||
|
const numberPrefix = findNumberPrefix(filename);
|
||||||
|
// Prefix found: return it with the cleaned filename
|
||||||
|
if (numberPrefix) {
|
||||||
|
return {
|
||||||
|
numberPrefix,
|
||||||
|
filename: filename.replace(prefix, ''),
|
||||||
|
};
|
||||||
|
}
|
||||||
|
// No number prefix found
|
||||||
|
return {numberPrefix: undefined, filename};
|
||||||
|
},
|
||||||
|
docLayoutComponent: '@theme/DocPage',
|
||||||
|
docItemComponent: '@theme/DocItem',
|
||||||
|
remarkPlugins: [require('remark-math')],
|
||||||
|
rehypePlugins: [],
|
||||||
|
beforeDefaultRemarkPlugins: [],
|
||||||
|
beforeDefaultRehypePlugins: [],
|
||||||
|
showLastUpdateAuthor: false,
|
||||||
|
showLastUpdateTime: false,
|
||||||
|
disableVersioning: false,
|
||||||
|
includeCurrentVersion: true,
|
||||||
|
lastVersion: undefined,
|
||||||
|
versions: {
|
||||||
|
current: {
|
||||||
|
label: 'Android SDK v2.0.0 (WIP)',
|
||||||
|
path: 'android-2.0.0',
|
||||||
|
banner: 'none',
|
||||||
|
},
|
||||||
|
'1.0.0': {
|
||||||
|
label: 'Android SDK v1.0.0',
|
||||||
|
path: 'android-1.0.0',
|
||||||
|
banner: 'unmaintained',
|
||||||
|
},
|
||||||
|
},
|
||||||
|
onlyIncludeVersions: ['current', '1.0.0', '2.0.0'],
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### Preset options {#ex-config-preset}
|
||||||
|
|
||||||
|
If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic):
|
||||||
|
|
||||||
|
```js title="docusaurus.config.js"
|
||||||
|
module.exports = {
|
||||||
|
presets: [
|
||||||
|
[
|
||||||
|
'@docusaurus/preset-classic',
|
||||||
|
{
|
||||||
|
// highlight-start
|
||||||
|
docs: {
|
||||||
|
path: 'docs',
|
||||||
|
// ... configuration object here
|
||||||
|
},
|
||||||
|
// highlight-end
|
||||||
|
},
|
||||||
|
],
|
||||||
|
],
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### Plugin options {#ex-config-plugin}
|
||||||
|
|
||||||
|
If you are using a standalone plugin, provide options directly to the plugin:
|
||||||
|
|
||||||
```js title="docusaurus.config.js"
|
```js title="docusaurus.config.js"
|
||||||
module.exports = {
|
module.exports = {
|
||||||
plugins: [
|
plugins: [
|
||||||
[
|
[
|
||||||
'@docusaurus/plugin-content-docs',
|
'@docusaurus/plugin-content-docs',
|
||||||
|
// highlight-start
|
||||||
{
|
{
|
||||||
path: 'docs',
|
path: 'docs',
|
||||||
// Simple use-case: string editUrl
|
// ... configuration object here
|
||||||
// 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,
|
|
||||||
editCurrentVersion: false,
|
|
||||||
routeBasePath: 'docs',
|
|
||||||
include: ['**/*.md', '**/*.mdx'],
|
|
||||||
exclude: [
|
|
||||||
'**/_*.{js,jsx,ts,tsx,md,mdx}',
|
|
||||||
'**/_*/**',
|
|
||||||
'**/*.test.{js,jsx,ts,tsx}',
|
|
||||||
'**/__tests__/**',
|
|
||||||
],
|
|
||||||
sidebarPath: 'sidebars.js',
|
|
||||||
sidebarItemsGenerator: async function ({
|
|
||||||
defaultSidebarItemsGenerator,
|
|
||||||
numberPrefixParser,
|
|
||||||
item,
|
|
||||||
version,
|
|
||||||
docs,
|
|
||||||
}) {
|
|
||||||
// Use the provided data to generate a custom sidebar slice
|
|
||||||
return [
|
|
||||||
{type: 'doc', id: 'intro'},
|
|
||||||
{
|
|
||||||
type: 'category',
|
|
||||||
label: 'Tutorials',
|
|
||||||
items: [
|
|
||||||
{type: 'doc', id: 'tutorial1'},
|
|
||||||
{type: 'doc', id: 'tutorial2'},
|
|
||||||
],
|
|
||||||
},
|
|
||||||
];
|
|
||||||
},
|
|
||||||
numberPrefixParser: function (filename) {
|
|
||||||
// Implement your own logic to extract a potential number prefix
|
|
||||||
const numberPrefix = findNumberPrefix(filename);
|
|
||||||
// Prefix found: return it with the cleaned filename
|
|
||||||
if (numberPrefix) {
|
|
||||||
return {
|
|
||||||
numberPrefix,
|
|
||||||
filename: filename.replace(prefix, ''),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
// No number prefix found
|
|
||||||
return {numberPrefix: undefined, filename};
|
|
||||||
},
|
|
||||||
docLayoutComponent: '@theme/DocPage',
|
|
||||||
docItemComponent: '@theme/DocItem',
|
|
||||||
remarkPlugins: [require('remark-math')],
|
|
||||||
rehypePlugins: [],
|
|
||||||
beforeDefaultRemarkPlugins: [],
|
|
||||||
beforeDefaultRehypePlugins: [],
|
|
||||||
showLastUpdateAuthor: false,
|
|
||||||
showLastUpdateTime: false,
|
|
||||||
disableVersioning: false,
|
|
||||||
includeCurrentVersion: true,
|
|
||||||
lastVersion: undefined,
|
|
||||||
versions: {
|
|
||||||
current: {
|
|
||||||
label: 'Android SDK v2.0.0 (WIP)',
|
|
||||||
path: 'android-2.0.0',
|
|
||||||
banner: 'none',
|
|
||||||
},
|
|
||||||
'1.0.0': {
|
|
||||||
label: 'Android SDK v1.0.0',
|
|
||||||
path: 'android-1.0.0',
|
|
||||||
banner: 'unmaintained',
|
|
||||||
},
|
|
||||||
},
|
|
||||||
onlyIncludeVersions: ['current', '1.0.0', '2.0.0'],
|
|
||||||
},
|
},
|
||||||
|
// highlight-end
|
||||||
],
|
],
|
||||||
],
|
],
|
||||||
};
|
};
|
||||||
|
|
|
||||||
|
|
@ -14,7 +14,9 @@ npm install --save @docusaurus/plugin-content-pages
|
||||||
|
|
||||||
:::tip
|
:::tip
|
||||||
|
|
||||||
If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
|
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](#ex-config-preset).
|
||||||
|
|
||||||
:::
|
:::
|
||||||
|
|
||||||
|
|
@ -27,7 +29,7 @@ Accepted fields:
|
||||||
| Name | Type | Default | Description |
|
| 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. |
|
| `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. |
|
| `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. |
|
| `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. |
|
| `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. |
|
||||||
| `mdxPageComponent` | `string` | `'@theme/MDXPage'` | Component used by each MDX page. |
|
| `mdxPageComponent` | `string` | `'@theme/MDXPage'` | Component used by each MDX page. |
|
||||||
|
|
@ -38,29 +40,74 @@ Accepted fields:
|
||||||
|
|
||||||
</small>
|
</small>
|
||||||
|
|
||||||
Example configuration:
|
## Example configuration {#ex-config}
|
||||||
|
|
||||||
|
Here's an example configuration object.
|
||||||
|
|
||||||
|
You can provide it as [preset options](#ex-config-preset) or [plugin options](#ex-config-plugin).
|
||||||
|
|
||||||
|
:::tip
|
||||||
|
|
||||||
|
Most Docusaurus users configure this plugin through the [preset options](#ex-config-preset).
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
```js
|
||||||
|
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('remark-math')],
|
||||||
|
rehypePlugins: [],
|
||||||
|
beforeDefaultRemarkPlugins: [],
|
||||||
|
beforeDefaultRehypePlugins: [],
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### Preset options {#ex-config-preset}
|
||||||
|
|
||||||
|
If you use a preset, configure this plugin through the [preset options](presets.md#docusauruspreset-classic):
|
||||||
|
|
||||||
|
```js title="docusaurus.config.js"
|
||||||
|
module.exports = {
|
||||||
|
presets: [
|
||||||
|
[
|
||||||
|
'@docusaurus/preset-classic',
|
||||||
|
{
|
||||||
|
// highlight-start
|
||||||
|
pages: {
|
||||||
|
path: 'src/pages',
|
||||||
|
// ... configuration object here
|
||||||
|
},
|
||||||
|
// highlight-end
|
||||||
|
},
|
||||||
|
],
|
||||||
|
],
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### Plugin options {#ex-config-plugin}
|
||||||
|
|
||||||
|
If you are using a standalone plugin, provide options directly to the plugin:
|
||||||
|
|
||||||
```js title="docusaurus.config.js"
|
```js title="docusaurus.config.js"
|
||||||
module.exports = {
|
module.exports = {
|
||||||
plugins: [
|
plugins: [
|
||||||
[
|
[
|
||||||
'@docusaurus/plugin-content-pages',
|
'@docusaurus/plugin-content-pages',
|
||||||
|
// highlight-start
|
||||||
{
|
{
|
||||||
path: 'src/pages',
|
path: 'src/pages',
|
||||||
routeBasePath: '',
|
// ... configuration object here
|
||||||
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('remark-math')],
|
|
||||||
rehypePlugins: [],
|
|
||||||
beforeDefaultRemarkPlugins: [],
|
|
||||||
beforeDefaultRehypePlugins: [],
|
|
||||||
},
|
},
|
||||||
|
// highlight-end
|
||||||
],
|
],
|
||||||
],
|
],
|
||||||
};
|
};
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue