mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-01 18:32:52 +02:00
docs(website): use .mdx extension for every docs (#8490)
This commit is contained in:
Sébastien Lorber
GitHub
parent
428af8af5e
commit
120b99b1f3
308 changed files with 1050 additions and 1009 deletions
|
|
@ -60,11 +60,11 @@ Read more about [importing partial pages](../markdown-features/markdown-features
|
|||
|
||||
## Doc front matter {#doc-front-matter}
|
||||
|
||||
The [front matter](../markdown-features/markdown-features-intro.mdx#front-matter) is used to provide additional metadata for your doc page. Front matter is optional—Docusaurus will be able to infer all necessary metadata without the front matter. For example, the [doc tags](#dog-tags) feature introduced below requires using front matter. For all possible fields, see [the API documentation](../../api/plugins/plugin-content-docs.md#markdown-front-matter).
|
||||
The [front matter](../markdown-features/markdown-features-intro.mdx#front-matter) is used to provide additional metadata for your doc page. Front matter is optional—Docusaurus will be able to infer all necessary metadata without the front matter. For example, the [doc tags](#dog-tags) feature introduced below requires using front matter. For all possible fields, see [the API documentation](../../api/plugins/plugin-content-docs.mdx#markdown-front-matter).
|
||||
|
||||
## Doc tags {#doc-tags}
|
||||
|
||||
Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar/index.md). Tags are passed in the front matter as a list of labels:
|
||||
Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar/index.mdx). Tags are passed in the front matter as a list of labels:
|
||||
|
||||
```md "your-doc-page.md"
|
||||
---
|
||||
|
|
@ -137,7 +137,7 @@ slug: /bonjour
|
|||
Lorem ipsum
|
||||
```
|
||||
|
||||
`slug` will be appended to the doc plugin's `routeBasePath`, which is `/docs` by default. See [Docs-only mode](docs-introduction.md#docs-only-mode) for how to remove the `/docs` part from the URL.
|
||||
`slug` will be appended to the doc plugin's `routeBasePath`, which is `/docs` by default. See [Docs-only mode](docs-introduction.mdx#docs-only-mode) for how to remove the `/docs` part from the URL.
|
||||
|
||||
:::note
|
||||
|
||||
|
|
@ -161,6 +161,6 @@ Lorem ipsum
|
|||
|
||||
### Sidebars {#sidebars}
|
||||
|
||||
When using [autogenerated sidebars](./sidebar/autogenerated.md), the file structure will determine the sidebar structure.
|
||||
When using [autogenerated sidebars](./sidebar/autogenerated.mdx), the file structure will determine the sidebar structure.
|
||||
|
||||
Our recommendation for file system organization is: make your file system mirror the sidebar structure (so you don't need to handwrite your `sidebars.js` file), and use the `slug` front matter to customize URLs of each document.
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ The docs feature provides users with a way to organize Markdown files in a hiera
|
|||
|
||||
:::info
|
||||
|
||||
Check the [Docs Plugin API Reference documentation](./../../api/plugins/plugin-content-docs.md) for an exhaustive list of options.
|
||||
Check the [Docs Plugin API Reference documentation](./../../api/plugins/plugin-content-docs.mdx) for an exhaustive list of options.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -21,7 +21,7 @@ Your site's documentation is organized by four levels, from lowest to highest:
|
|||
3. Versions.
|
||||
4. Plugin instances.
|
||||
|
||||
The guide will introduce them in that order: starting from [how individual pages can be configured](./docs-create-doc.mdx), to [how to create a sidebar or multiple ones](./sidebar/index.md), to [how to create and manage versions](./versioning.md), to [how to use multiple docs plugin instances](./docs-multi-instance.mdx).
|
||||
The guide will introduce them in that order: starting from [how individual pages can be configured](./docs-create-doc.mdx), to [how to create a sidebar or multiple ones](./sidebar/index.mdx), to [how to create and manage versions](./versioning.mdx), to [how to use multiple docs plugin instances](./docs-multi-instance.mdx).
|
||||
|
||||
## Docs-only mode {#docs-only-mode}
|
||||
|
||||
|
|
@ -6,11 +6,11 @@ slug: /docs-multi-instance
|
|||
|
||||
# Docs Multi-instance
|
||||
|
||||
The `@docusaurus/plugin-content-docs` plugin can support [multi-instance](../../using-plugins.md#multi-instance-plugins-and-plugin-ids).
|
||||
The `@docusaurus/plugin-content-docs` plugin can support [multi-instance](../../using-plugins.mdx#multi-instance-plugins-and-plugin-ids).
|
||||
|
||||
:::note
|
||||
|
||||
This feature is only useful for [versioned documentation](./versioning.md). It is recommended to be familiar with docs versioning before reading this page. If you just want [multiple sidebars](./sidebar/multiple-sidebars.md), you can do so within one plugin.
|
||||
This feature is only useful for [versioned documentation](./versioning.mdx). It is recommended to be familiar with docs versioning before reading this page. If you just want [multiple sidebars](./sidebar/multiple-sidebars.mdx), you can do so within one plugin.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -185,7 +185,7 @@ npm run docusaurus docs:version:community 1.0.0
|
|||
|
||||
## Docs navbar items {#docs-navbar-items}
|
||||
|
||||
Each docs-related [theme navbar items](../../api/themes/theme-configuration.md#navbar) take an optional `docsPluginId` attribute.
|
||||
Each docs-related [theme navbar items](../../api/themes/theme-configuration.mdx#navbar) take an optional `docsPluginId` attribute.
|
||||
|
||||
For example, if you want to have one version dropdown for each mobile SDK (iOS and Android), you could do:
|
||||
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
An `autogenerated` item is converted by Docusaurus to a **sidebar slice** (also discussed in [category shorthands](items.md#category-shorthand)): a list of items of type `doc` or `category`, so you can splice **multiple `autogenerated` items** from multiple directories, interleaving them with regular sidebar items, in one sidebar level.
|
||||
An `autogenerated` item is converted by Docusaurus to a **sidebar slice** (also discussed in [category shorthands](items.mdx#category-shorthand)): a list of items of type `doc` or `category`, so you can splice **multiple `autogenerated` items** from multiple directories, interleaving them with regular sidebar items, in one sidebar level.
|
||||
|
||||
<details>
|
||||
<summary>A real-world example</summary>
|
||||
|
|
@ -171,7 +171,7 @@ A category index document is a document following one of those filename conventi
|
|||
- Named as `README` (case-insensitive): `docs/Guides/README.mdx`
|
||||
- Same name as parent folder: `docs/Guides/Guides.md`
|
||||
|
||||
This is equivalent to using a category with a [doc link](items.md#category-doc-link):
|
||||
This is equivalent to using a category with a [doc link](items.mdx#category-doc-link):
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
|
|
@ -370,7 +370,7 @@ customProps:
|
|||
|
||||
:::info
|
||||
|
||||
If the `link` is explicitly specified, Docusaurus will not apply any [default conventions](items.md#category-index-convention).
|
||||
If the `link` is explicitly specified, Docusaurus will not apply any [default conventions](items.mdx#category-index-convention).
|
||||
|
||||
The doc links can be specified relatively, e.g. if the category is generated with the `guides` directory, `"link": {"type": "doc", "id": "intro"}` will be resolved to the ID `guides/intro`, only falling back to `intro` if a doc with the former ID doesn't exist.
|
||||
|
||||
|
|
@ -414,8 +414,8 @@ By default, Docusaurus will **remove the number prefix** from the doc id, title,
|
|||
Updating a number prefix can be annoying, as it can require **updating multiple existing Markdown links**:
|
||||
|
||||
```diff title="docs/02-Tutorial Easy/01-First Part.md"
|
||||
- Check the [Tutorial End](../04-End.md);
|
||||
+ Check the [Tutorial End](../05-End.md);
|
||||
- Check the [Tutorial End](../04-End.mdx);
|
||||
+ Check the [Tutorial End](../05-End.mdx);
|
||||
```
|
||||
|
||||
:::
|
||||
|
|
@ -41,7 +41,7 @@ import DocCardList from '@theme/DocCardList';
|
|||
|
||||
## Default sidebar {#default-sidebar}
|
||||
|
||||
If the `sidebarPath` is unspecified, Docusaurus [automatically generates a sidebar](autogenerated.md) for you, by using the filesystem structure of the `docs` folder:
|
||||
If the `sidebarPath` is unspecified, Docusaurus [automatically generates a sidebar](autogenerated.mdx) for you, by using the filesystem structure of the `docs` folder:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
|
|
@ -108,7 +108,7 @@ module.exports = {
|
|||
|
||||
This is a sidebars file that exports one sidebar, called `mySidebar`. It has three top-level items: two categories and one external link. Within each category, there are a few doc links.
|
||||
|
||||
A sidebars file can contain [**multiple sidebar objects**](multiple-sidebars.md), identified by their object keys.
|
||||
A sidebars file can contain [**multiple sidebar objects**](multiple-sidebars.mdx), identified by their object keys.
|
||||
|
||||
```ts
|
||||
type SidebarsFile = {
|
||||
|
|
@ -16,9 +16,9 @@ We have introduced three types of item types in the example in the previous sect
|
|||
- **[Doc](#sidebar-item-doc)**: link to a doc page, associating it with the sidebar
|
||||
- **[Link](#sidebar-item-link)**: link to any internal or external page
|
||||
- **[Category](#sidebar-item-category)**: creates a dropdown of sidebar items
|
||||
- **[Autogenerated](autogenerated.md)**: generate a sidebar slice automatically
|
||||
- **[Autogenerated](autogenerated.mdx)**: generate a sidebar slice automatically
|
||||
- **[HTML](#sidebar-item-html)**: renders pure HTML in the item's position
|
||||
- **[\*Ref](multiple-sidebars.md#sidebar-item-ref)**: link to a doc page, without making the item take part in navigation generation
|
||||
- **[\*Ref](multiple-sidebars.mdx#sidebar-item-ref)**: link to a doc page, without making the item take part in navigation generation
|
||||
|
||||
## Doc: link to a doc {#sidebar-item-doc}
|
||||
|
||||
|
|
@ -231,7 +231,7 @@ With category links, clicking on a category can navigate you to another page.
|
|||
|
||||
Use category links to introduce a category of documents.
|
||||
|
||||
Autogenerated categories can use the [`_category_.yml`](./autogenerated.md#category-item-metadata) file to declare the link.
|
||||
Autogenerated categories can use the [`_category_.yml`](./autogenerated.mdx#category-item-metadata) file to declare the link.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -288,7 +288,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
See it in action on the [i18n introduction page](../../../i18n/i18n-introduction.md).
|
||||
See it in action on the [i18n introduction page](../../../i18n/i18n-introduction.mdx).
|
||||
|
||||
#### Embedding generated index in doc page {#embedding-generated-index-in-doc-page}
|
||||
|
||||
|
|
@ -569,7 +569,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
Note how the two consecutive category shorthands are compressed into one object with two entries. This syntax generates a **sidebar slice**: you shouldn't see that object as one bulk item—this object is unwrapped, with each entry becoming a separate item, and they spliced together with the rest of the items (in this case, the "Learn more" link) to form the final sidebar level. Sidebar slices are also important when discussing [autogenerated sidebars](autogenerated.md).
|
||||
Note how the two consecutive category shorthands are compressed into one object with two entries. This syntax generates a **sidebar slice**: you shouldn't see that object as one bulk item—this object is unwrapped, with each entry becoming a separate item, and they spliced together with the rest of the items (in this case, the "Learn more" link) to form the final sidebar level. Sidebar slices are also important when discussing [autogenerated sidebars](autogenerated.mdx).
|
||||
|
||||
Wherever you have an array of items that is reduced to one category shorthand, you can omit that enclosing array as well.
|
||||
|
||||
|
|
@ -10,8 +10,8 @@ You can create a sidebar for each **set of Markdown files** that you want to **g
|
|||
|
||||
The Docusaurus site is a good example of using multiple sidebars:
|
||||
|
||||
- [Docs](../../../introduction.md)
|
||||
- [API](../../../cli.md)
|
||||
- [Docs](../../../introduction.mdx)
|
||||
- [API](../../../cli.mdx)
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -72,10 +72,19 @@ By default, the `current` docs version is labeled as `Next` and hosted under `/d
|
|||
Note the terminology we use here.
|
||||
|
||||
<dl>
|
||||
<dt><b>Current version</b></dt>
|
||||
<dd>The version placed in the <code>./docs</code> folder.</dd>
|
||||
<dt><b>Latest version / last version</b></dt>
|
||||
<dd>The version served by default for docs navbar items. Usually has path <code>/docs</code>.</dd>
|
||||
<dt>
|
||||
<b>Current version</b>
|
||||
</dt>
|
||||
<dd>
|
||||
The version placed in the <code>./docs</code> folder.
|
||||
</dd>
|
||||
<dt>
|
||||
<b>Latest version / last version</b>
|
||||
</dt>
|
||||
<dd>
|
||||
The version served by default for docs navbar items. Usually has path{' '}
|
||||
<code>/docs</code>.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
Current version is defined by the **file system location**, while latest version is defined by the **the navigation behavior**. They may or may not be the same version! (And the default configuration, as shown in the table above, would treat them as different: current version at `/docs/next` and latest at `/docs`.)
|
||||
|
|
@ -94,7 +103,7 @@ npm run docusaurus docs:version 1.1.0
|
|||
When tagging a new version, the document versioning mechanism will:
|
||||
|
||||
- Copy the full `docs/` folder contents into a new `versioned_docs/version-[versionName]/` folder.
|
||||
- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-[versionName]-sidebars.json`.
|
||||
- Create a versioned sidebars file based from your current [sidebar](docs-introduction.mdx#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-[versionName]-sidebars.json`.
|
||||
- Append the new version number to `versions.json`.
|
||||
|
||||
### Creating new docs {#creating-new-docs}
|
||||
|
|
@ -211,16 +220,16 @@ We offer these plugin options to customize versioning behavior:
|
|||
- `badge`: show a badge with the version name at the top of a doc of that version.
|
||||
- `className`: add a custom `className` to the `<html>` element of doc pages of that version.
|
||||
|
||||
See [docs plugin configuration](../../api/plugins/plugin-content-docs.md#configuration) for more details.
|
||||
See [docs plugin configuration](../../api/plugins/plugin-content-docs.mdx#configuration) for more details.
|
||||
|
||||
## Navbar items {#navbar-items}
|
||||
|
||||
We offer several navbar items to help you quickly set up navigation without worrying about versioned routes.
|
||||
|
||||
- [`doc`](../../api/themes/theme-configuration.md#navbar-doc-link): a link to a doc.
|
||||
- [`docSidebar`](../../api/themes/theme-configuration.md#navbar-doc-sidebar): a link to the first item in a sidebar.
|
||||
- [`docsVersion`](../../api/themes/theme-configuration.md#navbar-docs-version): a link to the main doc of the currently viewed version.
|
||||
- [`docsVersionDropdown`](../../api/themes/theme-configuration.md#navbar-docs-version-dropdown): a dropdown containing all the versions available.
|
||||
- [`doc`](../../api/themes/theme-configuration.mdx#navbar-doc-link): a link to a doc.
|
||||
- [`docSidebar`](../../api/themes/theme-configuration.mdx#navbar-doc-sidebar): a link to the first item in a sidebar.
|
||||
- [`docsVersion`](../../api/themes/theme-configuration.mdx#navbar-docs-version): a link to the main doc of the currently viewed version.
|
||||
- [`docsVersionDropdown`](../../api/themes/theme-configuration.mdx#navbar-docs-version-dropdown): a dropdown containing all the versions available.
|
||||
|
||||
These links would all look for an appropriate version to link to, in the following order:
|
||||
|
||||
|
|
@ -260,9 +269,9 @@ Don't use relative paths import within the docs. Because when we cut a version t
|
|||
Refer to other docs by relative file paths with the `.md` extension, so that Docusaurus can rewrite them to actual URL paths during building. Files will be linked to the correct corresponding version.
|
||||
|
||||
```md
|
||||
The [@hello](hello.md#paginate) document is great!
|
||||
The [@hello](hello.mdx#paginate) document is great!
|
||||
|
||||
See the [Tutorial](../getting-started/tutorial.md) for more info.
|
||||
See the [Tutorial](../getting-started/tutorial.mdx) for more info.
|
||||
```
|
||||
|
||||
### Global or versioned collocated assets {#global-or-versioned-collocated-assets}
|
||||
Loading…
Add table
Add a link
Reference in a new issue