diff --git a/website/docs/api/plugins/plugin-content-blog.md b/website/docs/api/plugins/plugin-content-blog.md index 23e4ba8264..75ad752840 100644 --- a/website/docs/api/plugins/plugin-content-blog.md +++ b/website/docs/api/plugins/plugin-content-blog.md @@ -14,7 +14,9 @@ npm install --save @docusaurus/plugin-content-blog :::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; ``` -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: //, + 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" module.exports = { plugins: [ [ '@docusaurus/plugin-content-blog', + // highlight-start { 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: //, - showReadingTime: true, - feedOptions: { - type: '', - title: '', - description: '', - copyright: '', - language: undefined, - }, + // ... configuration object here }, + // highlight-end ], ], }; diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md index 631d116b62..42e95defe6 100644 --- a/website/docs/api/plugins/plugin-content-docs.md +++ b/website/docs/api/plugins/plugin-content-docs.md @@ -14,7 +14,9 @@ npm install --save @docusaurus/plugin-content-docs :::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" module.exports = { plugins: [ [ '@docusaurus/plugin-content-docs', + // highlight-start { 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'], + // ... configuration object here }, + // highlight-end ], ], }; diff --git a/website/docs/api/plugins/plugin-content-pages.md b/website/docs/api/plugins/plugin-content-pages.md index 82457e369a..27e3b0c9b9 100644 --- a/website/docs/api/plugins/plugin-content-pages.md +++ b/website/docs/api/plugins/plugin-content-pages.md @@ -14,7 +14,9 @@ npm install --save @docusaurus/plugin-content-pages :::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 | | --- | --- | --- | --- | | `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. | | `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. | | `mdxPageComponent` | `string` | `'@theme/MDXPage'` | Component used by each MDX page. | @@ -38,29 +40,74 @@ Accepted fields: -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" module.exports = { plugins: [ [ '@docusaurus/plugin-content-pages', + // highlight-start { 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: [], + // ... configuration object here }, + // highlight-end ], ], };