3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-10 07:37:19 +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} ## 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" ```js title="docusaurus.config.js"
module.exports = { module.exports = {
plugins: [ plugins: [
[ [
'@docusaurus/plugin-content-blog', '@docusaurus/plugin-content-blog',
{ {
/**
* Path to data on filesystem relative to site dir.
*/
path: 'blog', path: 'blog',
/** // Simple use-case: string editUrl
* Base url to edit your site. // editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
* Docusaurus will compute the final editUrl with "editUrl + relativeDocPath" // Advanced use-case: functional editUrl
*/
editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
/**
* For advanced cases, compute the edit url for each Markdown file yourself.
*/
editUrl: ({locale, blogDirPath, blogPath, permalink}) => { editUrl: ({locale, blogDirPath, blogPath, permalink}) => {
return `https://github.com/facebook/docusaurus/edit/master/website/${blogDirPath}/${blogPath}`; 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, editLocalizedFiles: false,
/**
* Blog page title for better SEO
*/
blogTitle: 'Blog title', blogTitle: 'Blog title',
/**
* Blog page meta description for better SEO
*/
blogDescription: 'Blog', blogDescription: 'Blog',
/**
* Number of blog post elements to show in the blog sidebar
* 'ALL' to show all blog posts
* 0 to disable
*/
blogSidebarCount: 5, blogSidebarCount: 5,
/**
* Title of the blog sidebar
*/
blogSidebarTitle: 'All our posts', blogSidebarTitle: 'All our posts',
/**
* URL route for the blog section of your site.
* *DO NOT* include a trailing slash.
*/
routeBasePath: 'blog', routeBasePath: 'blog',
include: ['*.md', '*.mdx'], include: ['*.md', '*.mdx'],
/**
* No route will be created for matching files
*/
exclude: [ exclude: [
'**/_*.{js,jsx,ts,tsx,md,mdx}', '**/_*.{js,jsx,ts,tsx,md,mdx}',
'**/_*/**', '**/_*/**',
@ -82,44 +94,22 @@ module.exports = {
'**/__tests__/**', '**/__tests__/**',
], ],
postsPerPage: 10, postsPerPage: 10,
/**
* Theme components used by the blog pages.
*/
blogListComponent: '@theme/BlogListPage', blogListComponent: '@theme/BlogListPage',
blogPostComponent: '@theme/BlogPostPage', blogPostComponent: '@theme/BlogPostPage',
blogTagsListComponent: '@theme/BlogTagsListPage', blogTagsListComponent: '@theme/BlogTagsListPage',
blogTagsPostsComponent: '@theme/BlogTagsPostsPage', blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
/** remarkPlugins: [require('remark-math')],
* Remark and Rehype plugins passed to MDX.
*/
remarkPlugins: [
/* require('remark-math') */
],
rehypePlugins: [], rehypePlugins: [],
/**
* Custom Remark and Rehype plugins passed to MDX before
* the default Docusaurus Remark and Rehype plugins.
*/
beforeDefaultRemarkPlugins: [], beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [], beforeDefaultRehypePlugins: [],
/**
* Truncate marker, can be a regex or string.
*/
truncateMarker: /<!--\s*(truncate)\s*-->/, truncateMarker: /<!--\s*(truncate)\s*-->/,
/**
* Show estimated reading time for the blog post.
*/
showReadingTime: true, showReadingTime: true,
/**
* Blog feed.
* If feedOptions is undefined, no rss feed will be generated.
*/
feedOptions: { feedOptions: {
type: '', // required. 'rss' | 'feed' | 'all' type: '',
title: '', // default to siteConfig.title title: '',
description: '', // default to `${siteConfig.title} Blog` description: '',
copyright: '', 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} ## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first. 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} ## 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" ```js title="docusaurus.config.js"
module.exports = { module.exports = {
plugins: [ plugins: [
[ [
'@docusaurus/plugin-content-docs', '@docusaurus/plugin-content-docs',
{ {
/**
* Path to data on filesystem relative to site dir.
*/
path: 'docs', path: 'docs',
/** // Simple use-case: string editUrl
* Base url to edit your site. // editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
* Docusaurus will compute the final editUrl with "editUrl + relativeDocPath" // Advanced use-case: functional editUrl
* Omitting this variable entirely will disable edit links. editUrl: ({versionDocsDirPath, docPath}) =>
*/ `https://github.com/facebook/docusaurus/edit/master/website/${versionDocsDirPath}/${docPath}`,
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
*/
editLocalizedFiles: false, 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, 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', routeBasePath: 'docs',
include: ['**/*.md', '**/*.mdx'], // Extensions to include. include: ['**/*.md', '**/*.mdx'],
/**
* No route will be created for matching files
*/
exclude: [ exclude: [
'**/_*.{js,jsx,ts,tsx,md,mdx}', '**/_*.{js,jsx,ts,tsx,md,mdx}',
'**/_*/**', '**/_*/**',
'**/*.test.{js,jsx,ts,tsx}', '**/*.test.{js,jsx,ts,tsx}',
'**/__tests__/**', '**/__tests__/**',
], ],
/**
* Path to sidebar configuration for showing a list of markdown pages.
*/
sidebarPath: 'sidebars.js', 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 ({ sidebarItemsGenerator: async function ({
defaultSidebarItemsGenerator, // useful to re-use/enhance default sidebar generation logic from Docusaurus defaultSidebarItemsGenerator,
numberPrefixParser, // numberPrefixParser configured for this plugin numberPrefixParser,
item, // the sidebar item with type "autogenerated" item,
version, // the current version version,
docs, // all the docs of that version (unfiltered) docs,
}) { }) {
// Use the provided data to generate a custom sidebar slice // Use the provided data to generate a custom sidebar slice
return [ 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) { numberPrefixParser: function (filename) {
// Implement your own logic to extract a potential number prefix // Implement your own logic to extract a potential number prefix
const numberPrefix = findNumberPrefix(filename); const numberPrefix = findNumberPrefix(filename);
@ -136,62 +149,18 @@ module.exports = {
// No number prefix found // No number prefix found
return {numberPrefix: undefined, filename}; return {numberPrefix: undefined, filename};
}, },
/**
* Theme components used by the docs pages
*/
docLayoutComponent: '@theme/DocPage', docLayoutComponent: '@theme/DocPage',
docItemComponent: '@theme/DocItem', docItemComponent: '@theme/DocItem',
/** remarkPlugins: [require('remark-math')],
* Remark and Rehype plugins passed to MDX
*/
remarkPlugins: [
/* require('remark-math') */
],
rehypePlugins: [], rehypePlugins: [],
/**
* Custom Remark and Rehype plugins passed to MDX before
* the default Docusaurus Remark and Rehype plugins.
*/
beforeDefaultRemarkPlugins: [], beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [], beforeDefaultRehypePlugins: [],
/**
* Whether to display the author who last updated the doc.
*/
showLastUpdateAuthor: false, showLastUpdateAuthor: false,
/**
* Whether to display the last date the doc was updated.
*/
showLastUpdateTime: false, 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, 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, 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, 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: { versions: {
/*
Example configuration:
current: { current: {
label: 'Android SDK v2.0.0 (WIP)', label: 'Android SDK v2.0.0 (WIP)',
path: 'android-2.0.0', path: 'android-2.0.0',
@ -202,13 +171,8 @@ module.exports = {
path: 'android-1.0.0', path: 'android-1.0.0',
banner: 'unmaintained', banner: 'unmaintained',
}, },
*/
}, },
/** onlyIncludeVersions: ['current', '1.0.0', '2.0.0'],
* 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"]
}, },
], ],
], ],
@ -217,21 +181,29 @@ module.exports = {
## Markdown Frontmatter {#markdown-frontmatter} ## 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) Accepted fields:
- `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` <small>
- `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` | Name | Type | Default | Description |
- `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` | `id` | `string` | file path (including folders, without the extension) | A unique document id. |
- `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 | `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. |
- `custom_edit_url`: The URL for editing this document. Default value: computed using the `editUrl` plugin options | `pagination_label` | `string` | `sidebar_label` or `title` | The text used in the document next/previous buttons for this document. |
- `keywords`: Keywords meta tag for the document page, for search engines | `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. |
- `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 | `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). |
- `image`: Cover or thumbnail image that will be used when displaying the link to your post. | `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. |
- `slug`: Allows to customize the document url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. | `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: 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} ## 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" ```js title="docusaurus.config.js"
module.exports = { module.exports = {
plugins: [ plugins: [
[ [
'@docusaurus/plugin-content-pages', '@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', path: 'src/pages',
/**
* URL route for the page section of your site
* do not include trailing slash
*/
routeBasePath: '', routeBasePath: '',
include: ['**/*.{js,jsx,ts,tsx,md,mdx}'], include: ['**/*.{js,jsx,ts,tsx,md,mdx}'],
/**
* No route will be created for matching files
*/
exclude: [ exclude: [
'**/_*.{js,jsx,ts,tsx,md,mdx}', '**/_*.{js,jsx,ts,tsx,md,mdx}',
'**/_*/**', '**/_*/**',
'**/*.test.{js,jsx,ts,tsx}', '**/*.test.{js,jsx,ts,tsx}',
'**/__tests__/**', '**/__tests__/**',
], ],
/**
* Theme component used by markdown pages.
*/
mdxPageComponent: '@theme/MDXPage', mdxPageComponent: '@theme/MDXPage',
/** remarkPlugins: [require('remark-math')],
* Remark and Rehype plugins passed to MDX
*/
remarkPlugins: [],
rehypePlugins: [], rehypePlugins: [],
/**
* Custom Remark and Rehype plugins passed to MDX before
* the default Docusaurus Remark and Rehype plugins.
*/
beforeDefaultRemarkPlugins: [], beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [], beforeDefaultRehypePlugins: [],
}, },

527
website/docs/api/themes/theme-configuration.md
View file

@ -8,53 +8,54 @@ This configuration applies to all [main themes](./overview.md).
## Common {#common} ## Common {#common}
### Color mode - dark mode {#color-mode---dark-mode} ### Color mode {#color-mode---dark-mode}
The classic theme provides by default light and dark mode support, with a navbar switch for the user. The classic theme provides by default light and dark mode support, with a navbar switch for the user.
It is possible to customize the color mode support with the following configuration: It is possible to customize the color mode support within the `colorMode` object.
```js {6-36} title="docusaurus.config.js" Accepted fields:
<small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultMode` | <code>'light' &#124; 'dark' </code> | `'light'` | The color mode when user first visits the site. |
| `disableSwitch` | `boolean` | `false` | Hides the switch in the navbar. Useful if you want to support a single color mode. |
| `respectPrefersColorScheme` | `boolean` | `false` | Whether to use the `prefers-color-scheme` media-query, using user system preferences, instead of the hardcoded `defaultMode`. |
| `switchConfig` | _See below_ | _See below_ | Dark/light switch icon options. |
| `switchConfig.darkIcon` | `string` | `'🌜'` | Icon for the switch while in dark mode. |
| `switchConfig.darkIconStyle` | JSX style object (see [documentation](https://reactjs.org/docs/dom-elements.html#style)) | `{}` | CSS to apply to dark icon. |
| `switchConfig.lightIcon` | `string` | `'🌞'` | Icon for the switch while in light mode. |
| `switchConfig.lightIconStyle` | JSX style object | `{}` | CSS to apply to light icon. |
</small>
Example configuration:
```js title="docusaurus.config.js"
module.exports = { module.exports = {
// ...
themeConfig: { themeConfig: {
// ... // highlight-start
colorMode: { colorMode: {
// "light" | "dark"
defaultMode: 'light', defaultMode: 'light',
// Hides the switch in the navbar
// Useful if you want to support a single color mode
disableSwitch: false, disableSwitch: false,
// Should we use the prefers-color-scheme media-query,
// using user system preferences, instead of the hardcoded defaultMode
respectPrefersColorScheme: false, respectPrefersColorScheme: false,
// Dark/light switch icon options
switchConfig: { switchConfig: {
// Icon for the switch while in dark mode
darkIcon: '🌙', darkIcon: '🌙',
// CSS to apply to dark icon,
// React inline style object
// see https://reactjs.org/docs/dom-elements.html#style
darkIconStyle: { darkIconStyle: {
marginLeft: '2px', marginLeft: '2px',
}, },
// Unicode icons such as '\u2600' will work // Unicode icons such as '\u2600' will work
// Unicode with 5 chars require brackets: '\u{1F602}' // Unicode with 5 chars require brackets: '\u{1F602}'
lightIcon: '\u{1F602}', lightIcon: '\u{1F602}',
lightIconStyle: { lightIconStyle: {
marginLeft: '1px', marginLeft: '1px',
}, },
}, },
}, },
// ... // highlight-end
}, },
// ...
}; };
``` ```
@ -70,14 +71,23 @@ If you only want to support one color mode, you likely want to ignore user syste
You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`. You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`.
```js {4-6} title="docusaurus.config.js" Accepted fields:
<small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `image` | `string` | `undefined` | The meta image URL for the site. Relative to your site's "static" directory. Cannot be SVGs. Can be external URLs too. |
</small>
Example configuration:
```js title="docusaurus.config.js"
module.exports = { module.exports = {
// ...
themeConfig: { themeConfig: {
// Relative to your site's "static" directory. // highlight-next-line
// Cannot be SVGs. Can be external URLs too.
image: 'img/docusaurus.png', image: 'img/docusaurus.png',
// ...
}, },
}; };
``` ```
@ -86,118 +96,117 @@ module.exports = {
You can configure additional html metadatas (and override existing ones). You can configure additional html metadatas (and override existing ones).
```js {4} title="docusaurus.config.js" Accepted fields:
<small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `metadatas` | `Metadata[]` | `[]` | Any field will be directly passed to the `<meta />` tag. Possible fields include `id`, `name`, `property`, `content`, `itemprop`, etc. |
</small>
Example configuration:
```js title="docusaurus.config.js"
module.exports = { module.exports = {
// ...
themeConfig: { themeConfig: {
// highlight-next-line
metadatas: [{name: 'twitter:card', content: 'summary'}], metadatas: [{name: 'twitter:card', content: 'summary'}],
// ...
}, },
}; };
``` ```
### Announcement bar {#announcement-bar} ### Announcement bar {#announcement-bar}
Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and optionally dismissable panel above the navbar. Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and optionally dismissable panel above the navbar. All configuration are in the `announcementBar` object.
```js {4-11} title="docusaurus.config.js" Accepted fields:
<small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | `'announcement-bar'` | Any value that will identify this message. |
| `content` | `string` | `''` | The text content of the announcement. HTML will be interpolated. |
| `backgroundColor` | `string` | `'#fff'` | Background color of the entire bar. |
| `textColor` | `string` | `'#000'` | Announcement text color. |
| `isCloseable` | `boolean` | `true` | Whether this announcement can be dismissed with a '×' button. |
</small>
Example configuration:
```js title="docusaurus.config.js"
module.exports = { module.exports = {
// ...
themeConfig: { themeConfig: {
// highlight-start
announcementBar: { announcementBar: {
id: 'support_us', // Any value that will identify this message. id: 'support_us',
content: content:
'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>', 'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>',
backgroundColor: '#fafbfc', // Defaults to `#fff`. backgroundColor: '#fafbfc',
textColor: '#091E42', // Defaults to `#000`. textColor: '#091E42',
isCloseable: false, // Defaults to `true`. isCloseable: false,
}, },
// ... // highlight-end
}, },
}; };
``` ```
## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-theme-<themeName>`
- **Multi-instance path**: N/A
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir)
- **Markdown files**: N/A
### Example file-system structure {#example-file-system-structure}
```bash
website/i18n/<locale>/docusaurus-theme-classic
│
│ # translations for the theme
├── navbar.json
└── footer.json
```
## Hooks {#hooks}
### `useThemeContext` {#usethemecontext}
React hook to access theme context. This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use.
Usage example:
```jsx
import React from 'react';
// highlight-next-line
import useThemeContext from '@theme/hooks/useThemeContext';
const Example = () => {
// highlight-next-line
const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext();
return <h1>Dark mode is now {isDarkTheme ? 'on' : 'off'}</h1>;
};
```
:::note
The component calling `useThemeContext` must be a child of the `Layout` component.
```jsx
function ExamplePage() {
return (
<Layout>
<Example />
</Layout>
);
}
```
:::
## Navbar {#navbar} ## Navbar {#navbar}
### Navbar title & logo {#navbar-title--logo} Accepted fields:
You can add a logo and title to the navbar via `themeConfig.navbar`. Logo can be placed in [static folder](static-assets.md). Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab. <small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `undefined` | Title for the navbar. |
| `logo` | _See below_ | `undefined` | Customization of the logo object. |
| `items` | `NavbarItem[]` | `[]` | A list of navbar items. See specification below. |
| `hideOnScroll` | `boolean` | `false` | Whether the navbar is hidden when the user scrolls down. |
| `style` | <code>'primary' &#124; 'dark' </code> | Same as theme | Sets the navbar style, ignoring the dark/light theme. |
</small>
### Navbar logo {#navbar-logo}
The logo can be placed in [static folder](static-assets.md). Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab.
To improve dark mode support, you can also set a different logo for this mode. To improve dark mode support, you can also set a different logo for this mode.
```js {5-12} title="docusaurus.config.js" Accepted fields:
<small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `alt` | `string` | `undefined` | Alt tag for the logo image. |
| `src` | `string` | **Required** | URL to the logo image. Base URL is appended by default. |
| `srcDark` | `string` | `logo.src` | An alternative image URL to use in dark mode. |
| `href` | `string` | `siteConfig.baseUrl` | Link to navigate to when the logo is clicked. |
| `target` | `string` | Calculated based on `href` (external links will open in a new tab, all others in the current one). | The `target` attribute of the link; controls whether the link is opened in a new tab, the current one, or otherwise. |
</small>
Example configuration:
```js title="docusaurus.config.js"
module.exports = { module.exports = {
// ...
themeConfig: { themeConfig: {
navbar: { navbar: {
title: 'Site Title', title: 'Site Title',
// highlight-start
logo: { logo: {
alt: 'Site Logo', alt: 'Site Logo',
src: 'img/logo.svg', src: 'img/logo.svg',
srcDark: 'img/logo_dark.svg', // Default to `logo.src`. srcDark: 'img/logo_dark.svg',
href: 'https://docusaurus.io/', // Default to `siteConfig.baseUrl`. href: 'https://docusaurus.io/',
target: '_self', // By default, this value is calculated based on the `href` attribute (the external link will open in a new tab, all others in the current one). target: '_self',
}, },
// highlight-end
}, },
// ...
}, },
}; };
``` ```
@ -208,7 +217,6 @@ You can add items to the navbar via `themeConfig.navbar.items`.
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {
// ...
themeConfig: { themeConfig: {
navbar: { navbar: {
// highlight-start // highlight-start
@ -237,7 +245,6 @@ module.exports = {
], ],
// highlight-end // highlight-end
}, },
// ...
}, },
}; };
``` ```
@ -254,16 +261,20 @@ Outbound (external) links automatically get `target="_blank" rel="noopener noref
Accepted fields: Accepted fields:
| Field | Value | Explanation | Required | Default | <small>
| --- | --- | --- | --- | --- |
| `label` | `string` | The name to be shown for this item. | Yes | | | Name | Type | Default | Description |
| `to` | `string` | Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value. | Yes | | | --- | --- | --- | --- |
| `href` | `string` | A full-page navigation, used for navigating outside of the website. **Only one of `to` or `href` should be used.** | Yes | | | `label` | `string` | **Required** | The name to be shown for this item. |
| `prependBaseUrlToHref` | `boolean` | Prepends the baseUrl to `href` values. | No | `false` | | `to` | `string` | **Required** | Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value. |
| `position` | <code>'left' &#124; 'right'</code> | The side of the navbar this item should appear on. | No | `'left'` | | `href` | `string` | **Required** | A full-page navigation, used for navigating outside of the website. **Only one of `to` or `href` should be used.** |
| `activeBasePath` | `string` | To apply the active class styling on all routes starting with this path. This usually isn't necessary. | No | `to` / `href` | | `prependBaseUrlToHref` | `boolean` | `false` | Prepends the baseUrl to `href` values. |
| `activeBaseRegex` | `string` | Alternative to `activeBasePath` if required. | No | `undefined` | | `position` | <code>'left' &#124; 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
| `className` | `string` | Custom CSS class (for styling any item). | No | `''` | | `activeBasePath` | `string` | `to` / `href` | To apply the active class styling on all routes starting with this path. This usually isn't necessary. |
| `activeBaseRegex` | `string` | `undefined` | Alternative to `activeBasePath` if required. |
| `className` | `string` | `''` | Custom CSS class (for styling any item). |
</small>
Example configuration: Example configuration:
@ -296,17 +307,21 @@ Navbar dropdown items only accept the following **"link-like" item types**:
- [Navbar link](#navbar-link) - [Navbar link](#navbar-link)
- [Navbar doc link](#navbar-doc-link) - [Navbar doc link](#navbar-doc-link)
- [Navbar doc version](#navbar-doc-version) - [Navbar docs version](#navbar-docs-version)
Note that the dropdown base item is a clickable link as well, so this item can receive any of the props of a [plain navbar link](#navbar-link). Note that the dropdown base item is a clickable link as well, so this item can receive any of the props of a [plain navbar link](#navbar-link).
Accepted fields: Accepted fields:
| Field | Value | Explanation | Required | Default | <small>
| --- | --- | --- | --- | --- |
| `label` | `string` | The name to be shown for this item. | Yes | | | Name | Type | Default | Description |
| `items` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | The items to be contained in the dropdown. | Yes | | | --- | --- | --- | --- |
| `position` | <code>'left' &#124; 'right'</code> | The side of the navbar this item should appear on. | No | `'left'` | | `label` | `string` | **Required** | The name to be shown for this item. |
| `items` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | **Required** | The items to be contained in the dropdown. |
| `position` | <code>'left' &#124; 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
</small>
Example configuration: Example configuration:
@ -346,12 +361,16 @@ If you want to link to a specific doc, this special navbar item type will render
Accepted fields: Accepted fields:
| Field | Value | Explanation | Required | Default | <small>
| --- | --- | --- | --- | --- |
| `docId` | `string` | The ID of the doc that this item links to. | Yes | | | Name | Type | Default | Description |
| `label` | `string` | The name to be shown for this item. | No | `docId` | | --- | --- | --- | --- |
| `position` | <code>'left' &#124; 'right'</code> | The side of the navbar this item should appear on. | No | `'left'` | | `docId` | `string` | **Required** | The ID of the doc that this item links to. |
| `docsPluginId` | `string` | The ID of the docs plugin that the doc belongs to. | No | `'default'` | | `label` | `string` | `docId` | The name to be shown for this item. |
| `position` | <code>'left' &#124; 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
| `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc belongs to. |
</small>
Example configuration: Example configuration:
@ -382,13 +401,17 @@ The user will be able to switch from one version to another, while staying on th
Accepted fields: Accepted fields:
| Field | Value | Explanation | Required | Default | <small>
| --- | --- | --- | --- | --- |
| `position` | <code>'left' &#124; 'right'</code> | The side of the navbar this item should appear on. | No | `'left'` | | Name | Type | Default | Description |
| `dropdownItemsBefore` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | Add additional dropdown items at the beginning of the dropdown. | No | `[]` | | --- | --- | --- | --- |
| `dropdownItemsAfter` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | Add additional dropdown items at the end of the dropdown. | No | `[]` | | `position` | <code>'left' &#124; 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
| `docsPluginId` | `string` | The ID of the docs plugin that the doc versioning belongs to. | No | `'default'` | | `dropdownItemsBefore` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the beginning of the dropdown. |
| `dropdownActiveClassDisabled` | `boolean` | Do not add the link active class when browsing docs. | No | `false` | | `dropdownItemsAfter` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the end of the dropdown. |
| `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. |
| `dropdownActiveClassDisabled` | `boolean` | `false` | Do not add the link active class when browsing docs. |
</small>
Example configuration: Example configuration:
@ -417,12 +440,16 @@ If you use docs with versioning, this special navbar item type will link to the
Accepted fields: Accepted fields:
| Field | Value | Explanation | Required | Default | <small>
| --- | --- | --- | --- | --- |
| `label` | `string` | The name to be shown for this item. | No | The active/latest version label. | | Name | Type | Default | Description |
| `to` | `string` | The internal link that this item points to. | No | The active/latest version. | | --- | --- | --- | --- |
| `position` | <code>'left' &#124; 'right'</code> | The side of the navbar this item should appear on. | No | `'left'` | | `label` | `string` | The active/latest version label. | The name to be shown for this item. |
| `docsPluginId` | `string` | The ID of the docs plugin that the doc versioning belongs to. | No | `'default'` | | `to` | `string` | The active/latest version. | The internal link that this item points to. |
| `position` | <code>'left' &#124; 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
| `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. |
</small>
Example configuration: Example configuration:
@ -453,11 +480,15 @@ The user will be able to switch from one locale to another, while staying on the
Accepted fields: Accepted fields:
| Field | Value | Explanation | Required | Default | <small>
| --- | --- | --- | --- | --- |
| `position` | <code>'left' &#124; 'right'</code> | The side of the navbar this item should appear on. | No | `'left'` | | Name | Type | Default | Description |
| `dropdownItemsBefore` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | Add additional dropdown items at the beginning of the dropdown. | No | `[]` | | --- | --- | --- | --- |
| `dropdownItemsAfter` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | Add additional dropdown items at the end of the dropdown. | No | `[]` | | `position` | <code>'left' &#124; 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
| `dropdownItemsBefore` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the beginning of the dropdown. |
| `dropdownItemsAfter` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the end of the dropdown. |
</small>
Example configuration: Example configuration:
@ -490,19 +521,25 @@ If you use the [search](../../search.md), the search bar will be the rightmost e
However, with this special navbar item type, you can change the default location. However, with this special navbar item type, you can change the default location.
| Field | Value | Explanation | Required | Default | <small>
| --- | --- | --- | --- | --- |
| `position` | <code>'left' &#124; 'right'</code> | The side of the navbar this item should appear on. | No | `'left'` |
```js {5-8} title="docusaurus.config.js" | Name | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | <code>'left' &#124; 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
</small>
```js title="docusaurus.config.js"
module.exports = { module.exports = {
themeConfig: { themeConfig: {
navbar: { navbar: {
items: [ items: [
// highlight-start
{ {
type: 'search', type: 'search',
position: 'right', position: 'right',
}, },
// highlight-end
], ],
}, },
}, },
@ -513,14 +550,13 @@ module.exports = {
You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up. You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up.
```js {5} title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {
// ...
themeConfig: { themeConfig: {
navbar: { navbar: {
// highlight-next-line
hideOnScroll: true, hideOnScroll: true,
}, },
// ...
}, },
}; };
``` ```
@ -531,43 +567,48 @@ You can set the static Navbar style without disabling the theme switching abilit
Currently, there are two possible style options: `dark` and `primary` (based on the `--ifm-color-primary` color). You can see the styles preview in the [Infima documentation](https://infima.dev/docs/components/navbar/). Currently, there are two possible style options: `dark` and `primary` (based on the `--ifm-color-primary` color). You can see the styles preview in the [Infima documentation](https://infima.dev/docs/components/navbar/).
```js {5} title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {
// ...
themeConfig: { themeConfig: {
navbar: { navbar: {
// highlight-next-line
style: 'primary', style: 'primary',
}, },
// ...
}, },
}; };
``` ```
<!--
## Footer {#footer}
TODO.
-->
## CodeBlock {#codeblock} ## CodeBlock {#codeblock}
Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight code blocks. Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight code blocks. All configuration are in the `prism` object.
Accepted fields:
<small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `PrismTheme` | `palenight` | The Prism theme to use for light-theme code blocks. |
| `darkTheme` | `PrismTheme` | `palenight` | The Prism theme to use for dark-theme code blocks. |
| `defaultLanguage` | `string` | `undefined` | The side of the navbar this item should appear on. |
</small>
### Theme {#theme} ### Theme {#theme}
By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes). If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so. By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes). You may also use a different syntax highlighting theme when the site is in dark mode.
```js {5-6} title="docusaurus.config.js" Example configuration:
```js title="docusaurus.config.js"
module.exports = { module.exports = {
// ...
themeConfig: { themeConfig: {
prism: { prism: {
// highlight-start
theme: require('prism-react-renderer/themes/github'), theme: require('prism-react-renderer/themes/github'),
darkTheme: require('prism-react-renderer/themes/dracula'), darkTheme: require('prism-react-renderer/themes/dracula'),
// highlight-end
}, },
// ...
}, },
}; };
``` ```
@ -580,16 +621,17 @@ If you use the line highlighting Markdown syntax, you might need to specify a di
### Default language {#default-language} ### Default language {#default-language}
You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid [language name](https://prismjs.com/#supported-languages) must be passed, e.g.: You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid [language name](https://prismjs.com/#supported-languages) must be passed.
```js {5} title="docusaurus.config.js" Example configuration:
```js title="docusaurus.config.js"
module.exports = { module.exports = {
// ...
themeConfig: { themeConfig: {
prism: { prism: {
// highlight-next-line
defaultLanguage: 'javascript', defaultLanguage: 'javascript',
}, },
// ...
}, },
}; };
``` ```
@ -598,36 +640,78 @@ module.exports = {
You can add logo and a copyright to the footer via `themeConfig.footer`. Logo can be placed in [static folder](static-assets.md). Logo URL works in the same way of the navbar logo. You can add logo and a copyright to the footer via `themeConfig.footer`. Logo can be placed in [static folder](static-assets.md). Logo URL works in the same way of the navbar logo.
```js {5-15} title="docusaurus.config.js" Accepted fields:
// ...
footer: { <small>
logo: {
alt: 'Facebook Open Source Logo', | Name | Type | Default | Description |
src: 'img/oss_logo.png', | --- | --- | --- | --- |
href: 'https://opensource.facebook.com', | `logo` | `Logo` | `undefined` | Customization of the logo object. See [Navbar logo](#navbar-logo) for details. |
| `copyright` | `string` | `undefined` | The copyright message to be displayed at the bottom. |
| `style` | <code>'dark' &#124; 'light'</code> | `'light'` | The color theme of the footer component. |
| `items` | `FooterItem[]` | `[]` | The link groups to be present. |
</small>
Example configuration:
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
// highlight-start
footer: {
logo: {
alt: 'Facebook Open Source Logo',
src: 'img/oss_logo.png',
href: 'https://opensource.facebook.com',
},
copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
}, },
copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`, // highlight-end
} },
};
``` ```
## Footer Links {#footer-links} ### Footer Links {#footer-links}
You can add links to the footer via `themeConfig.footer.links`: You can add links to the footer via `themeConfig.footer.links`.
```js {5-15} title="docusaurus.config.js" Accepted fields of each link section:
<small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `undefined` | Label of the section of these links. |
| `items` | `FooterLink[]` | `[]` | Links in this section. |
</small>
Accepted fields of each item in `items`:
<small>
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | **Required** | Text to be displayed for this link. |
| `to` | `string` | **Required** | Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value. |
| `href` | `string` | **Required** | A full-page navigation, used for navigating outside of the website. **Only one of `to` or `href` should be used.** |
| `html` | `string` | `undefined` | Renders the html pass-through instead of a simple link. In case `html` is used, no other options should be provided. |
</small>
Example configuration:
```js title="docusaurus.config.js"
module.exports = { module.exports = {
// ...
footer: { footer: {
// highlight-start
links: [ links: [
{ {
// Label of the section of these links
title: 'Docs', title: 'Docs',
items: [ items: [
{ {
// Label of the link
label: 'Style Guide', label: 'Style Guide',
// Client-side routing, used for navigating within the website.
// The baseUrl will be automatically prepended to this value.
to: 'docs/', to: 'docs/',
}, },
{ {
@ -641,7 +725,6 @@ module.exports = {
items: [ items: [
{ {
label: 'Stack Overflow', label: 'Stack Overflow',
// A full-page navigation, used for navigating outside of the website.
href: 'https://stackoverflow.com/questions/tagged/docusaurus', href: 'https://stackoverflow.com/questions/tagged/docusaurus',
}, },
{ {
@ -653,7 +736,6 @@ module.exports = {
href: 'https://twitter.com/docusaurus', href: 'https://twitter.com/docusaurus',
}, },
{ {
//Renders the html pass-through instead of a simple link
html: ` html: `
<a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify"> <a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">
<img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" /> <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" />
@ -663,6 +745,65 @@ module.exports = {
], ],
}, },
], ],
// highlight-end
}, },
}; };
``` ```
## Hooks {#hooks}
### `useThemeContext` {#usethemecontext}
React hook to access theme context. This context contains functions for setting light and dark mode and exposes boolean variable, indicating which mode is currently in use.
Usage example:
```jsx
import React from 'react';
// highlight-next-line
import useThemeContext from '@theme/hooks/useThemeContext';
const Example = () => {
// highlight-next-line
const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext();
return <h1>Dark mode is now {isDarkTheme ? 'on' : 'off'}</h1>;
};
```
:::note
The component calling `useThemeContext` must be a child of the `Layout` component.
```jsx
function ExamplePage() {
return (
<Layout>
<Example />
</Layout>
);
}
```
:::
## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-theme-<themeName>`
- **Multi-instance path**: N/A
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir)
- **Markdown files**: N/A
### Example file-system structure {#example-file-system-structure}
```bash
website/i18n/<locale>/docusaurus-theme-classic
│
│ # translations for the theme
├── navbar.json
└── footer.json
```

105
website/docs/blog.md
View file

@ -51,25 +51,11 @@ This is my first post on Docusaurus 2.
A whole bunch of exploration to follow. A whole bunch of exploration to follow.
``` ```
## Header options {#header-options} The only required field in the front matter is `title`; however, we provide options to add more metadata to your blog post, for example, author information. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-frontmatter).
The only required field is `title`; however, we provide options to add author information to your blog post as well along with other options. ## Blog list {#blog-list}
- `author`: The author name to be displayed. The blog's index page (by default, it is at `/blog`) is the _blog list page_, where all blog posts are collectively displayed.
- `author_url`: The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook profile URL, etc.
- `author_image_url`: The URL to the author's thumbnail image.
- `author_title`: A description of the author.
- `title`: The blog post title.
- `slug`: Allows to customize the blog post url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-blog-post`, `slug: /my/path/to/blog/post`, slug: `/`.
- `date`: The blog post creation date. If not specified, this could be extracted from the file name, e.g, `2021-04-15-blog-post.mdx`. By default, it is the Markdown file creation time.
- `tags`: A list of strings or objects of two string fields `label` and `permalink` to tag to your post.
- `draft`: 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.
- `description`: The description of your post, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines. If this field is not present, it will default to the first line of the contents.
- `keywords`: Keywords meta tag, which will become the `<meta name="keywords" content="keyword1,keyword2,..."/>` in `<head>`, used by search engines.
- `image`: Cover or thumbnail image that will be used when displaying the link to your post.
- `hide_table_of_contents`: Whether to hide the table of contents to the right. By default, it is `false`.
## Summary truncation {#summary-truncation}
Use the `<!--truncate-->` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `<!--truncate-->` will be part of the summary. For example: Use the `<!--truncate-->` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `<!--truncate-->` will be part of the summary. For example:
@ -90,17 +76,71 @@ Not this.
Or this. Or this.
``` ```
By default, 10 posts are shown on each blog list page, but you can control pagination with the `postsPerPage` option in the plugin configuration. You can also add meta description to the blog list page for better SEO:
```js title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
// highlight-start
blogTitle: 'Docusaurus blog!',
blogDescription: 'A Docusaurus powered blog!',
postsPerPage: 20,
// highlight-end
},
},
],
],
};
```
## Blog sidebar {#blog-sidebar}
The blog sidebar displays recent blog posts. The default number of items shown is 5, but you can customize with the `blogSidebarCount` option in the plugin configuration. By setting `blogSidebarCount: 0`, the sidebar will be completely disabled, with the container removed as well. This will increase the width of the main container. Specially, if you have set `blogSidebarCount: 'ALL'`, _all_ posts will be displayed.
You can also alter the sidebar heading text with the `blogSidebarTitle` option. For example, if you have set `blogSidebarCount: 'ALL'`, instead of the default "Recent posts", you may would rather make it say "All posts":
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
// highlight-start
blogSidebarTitle: 'All posts',
blogSidebarCount: 'ALL',
// highlight-end
},
},
],
],
};
```
:::note
Because the sidebar title is hard-coded in the configuration file, it is currently untranslatable.
:::
## Feed {#feed} ## Feed {#feed}
You can generate RSS/Atom feed by passing feedOptions. By default, RSS and Atom feeds are generated. To disable feed generation, set `feedOptions.type` to `null`. You can generate RSS/Atom feed by passing feedOptions. By default, RSS and Atom feeds are generated. To disable feed generation, set `feedOptions.type` to `null`.
```ts ```ts
feedOptions?: { type BlogOptions = {
type?: 'rss' | 'atom' | 'all' | null; feedOptions?: {
title?: string; type?: 'rss' | 'atom' | 'all' | null;
description?: string; title?: string;
copyright: string; description?: string;
language?: string; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes copyright: string;
language?: string; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
};
}; };
``` ```
@ -169,25 +209,6 @@ Don't forget to delete the existing homepage at `./src/pages/index.js` or else t
::: :::
You can also add meta description to the blog list page for better SEO:
```js {8} title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
blogTitle: 'Docusaurus blog!',
blogDescription: 'A Docusaurus powered blog!',
},
},
],
],
};
```
### Multiple blogs {#multiple-blogs} ### Multiple blogs {#multiple-blogs}
By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the `plugins` option for `docusaurus.config.js`. By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the `plugins` option for `docusaurus.config.js`.

68
website/docs/guides/docs/sidebar.md
View file

@ -22,9 +22,8 @@ module.exports = {
'@docusaurus/preset-classic', '@docusaurus/preset-classic',
{ {
docs: { docs: {
// highlight-start // highlight-next-line
sidebarPath: require.resolve('./sidebars.js'), sidebarPath: require.resolve('./sidebars.js'),
// highlight-end
}, },
}, },
], ],
@ -334,9 +333,30 @@ module.exports = {
#### Collapsible categories {#collapsible-categories} #### Collapsible categories {#collapsible-categories}
By default, categories are collapsible and collapsed. We support the option to expand/collapse categories. Categories are collapsible by default, but you can disable collapsing with `collapsible: false`.
The docs plugin options allow to change these defaults globally: ```js title="sidebars.js"
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
items: [
'creating-pages',
{
type: 'category',
// highlight-next-line
collapsible: false,
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
```
To make all categories non-collapsible by default, set the `sidebarCollapsible` option in `plugin-docs` to `false`:
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {
@ -345,10 +365,8 @@ module.exports = {
'@docusaurus/preset-classic', '@docusaurus/preset-classic',
{ {
docs: { docs: {
// highlight-start // highlight-next-line
sidebarCollapsible: true, sidebarCollapsible: false,
sidebarCollapsed: false,
// highlight-end
}, },
}, },
], ],
@ -356,9 +374,15 @@ module.exports = {
}; };
``` ```
:::note
The option in `sidebars.js` takes precedence over plugin configuration, so it is possible to make certain categories collapsible when `sidebarCollapsible` is set to `false` globally.
:::
#### Expanded categories by default {#expanded-categories-by-default} #### Expanded categories by default {#expanded-categories-by-default}
For docs that have collapsible categories, you may want more fine-grain control over certain categories. If you want specific categories to be always expanded, you can set `collapsed` to `false`: Collapsible categories are collapsed by default. If you want them to be expanded on first render, you can set `collapsed` to `false`:
```js title="sidebars.js" ```js title="sidebars.js"
module.exports = { module.exports = {
@ -368,7 +392,7 @@ module.exports = {
{ {
type: 'category', type: 'category',
label: 'Docs', label: 'Docs',
collapsible: true, // highlight-next-line
collapsed: false, collapsed: false,
items: ['markdown-features', 'sidebar', 'versioning'], items: ['markdown-features', 'sidebar', 'versioning'],
}, },
@ -377,6 +401,30 @@ module.exports = {
}; };
``` ```
Similar to `collapsible`, you can also set the global configuration `options.sidebarCollapsed` to `false`. Individual `collapsed` options in `sidebars.js` will still take precedence over this configuration.
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// highlight-next-line
sidebarCollapsed: false,
},
},
],
],
};
```
:::caution
When a category has `collapsed: true` but `collapsible: false` (either through `sidebars.js` or through plugin configuration), the latter takes precedence and the category is still rendered as expanded.
:::
### Autogenerated: generate a sidebar {#sidebar-item-autogenerated} ### Autogenerated: generate a sidebar {#sidebar-item-autogenerated}
Docusaurus can **create a sidebar automatically** from your **filesystem structure**: each folder creates a sidebar category. Docusaurus can **create a sidebar automatically** from your **filesystem structure**: each folder creates a sidebar category.