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