mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-05 20:32:42 +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
|
|
@ -11,13 +11,13 @@ The `@docusaurus/plugin-content-pages` plugin empowers you to create **one-off s
|
|||
|
||||
:::note
|
||||
|
||||
Pages do not have sidebars, only [docs](./docs/docs-introduction.md) do.
|
||||
Pages do not have sidebars, only [docs](./docs/docs-introduction.mdx) do.
|
||||
|
||||
:::
|
||||
|
||||
:::info
|
||||
|
||||
Check the [Pages Plugin API Reference documentation](./../api/plugins/plugin-content-pages.md) for an exhaustive list of options.
|
||||
Check the [Pages Plugin API Reference documentation](./../api/plugins/plugin-content-pages.mdx) for an exhaustive list of options.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -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);
|
||||
```
|
||||
|
||||
:::
|
||||
|
|
@ -42,7 +42,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
|||
|
||||
## 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 = {
|
||||
|
|
@ -109,7 +109,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 = {
|
||||
|
|
@ -15,9 +15,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}
|
||||
|
||||
|
|
@ -230,7 +230,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.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -287,7 +287,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}
|
||||
|
||||
|
|
@ -302,7 +302,7 @@ In this section, we will introduce the following concepts:
|
|||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
```
|
||||
|
||||
See this in action on the [sidebar guides page](index.md).
|
||||
See this in action on the [sidebar guides page](index.mdx).
|
||||
|
||||
### Collapsible categories {#collapsible-categories}
|
||||
|
||||
|
|
@ -563,7 +563,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}
|
||||
|
|
@ -211,7 +211,7 @@ There are two kinds of customizations possible with admonitions: **parsing** and
|
|||
|
||||
### Customizing rendering behavior {#customizing-rendering-behavior}
|
||||
|
||||
You can customize how each individual admonition type is rendered through [swizzling](../../swizzling.md). You can often achieve your goal through a simple wrapper. For example, in the follow example, we swap out the icon for `info` admonitions only.
|
||||
You can customize how each individual admonition type is rendered through [swizzling](../../swizzling.mdx). You can often achieve your goal through a simple wrapper. For example, in the follow example, we swap out the icon for `info` admonitions only.
|
||||
|
||||
```jsx title="src/theme/Admonition.js"
|
||||
import React from 'react';
|
||||
|
|
@ -253,4 +253,4 @@ The plugin accepts two options:
|
|||
- `tag`: The tag that encloses the admonition. Defaults to `:::`.
|
||||
- `keywords`: An array of keywords that can be used as the type for the admonition. Note that if you override this, the default values will not be applied.
|
||||
|
||||
The `keyword` will be passed as the `type` prop of the `Admonition` component. If you register more types than the default, you are also responsible for providing their implementation—including the container's style, icon, default title text, etc. You would usually need to [eject](../../swizzling.md#ejecting) the `@theme/Admonition` component, so you could re-use the same infrastructure as the other types.
|
||||
The `keyword` will be passed as the `type` prop of the `Admonition` component. If you register more types than the default, you are also responsible for providing their implementation—including the container's style, icon, default title text, etc. You would usually need to [eject](../../swizzling.mdx#ejecting) the `@theme/Admonition` component, so you could re-use the same infrastructure as the other types.
|
||||
|
|
|
|||
|
|
@ -80,7 +80,7 @@ All of the above result in displaying the image:
|
|||
|
||||
:::note
|
||||
|
||||
If you are using [@docusaurus/plugin-ideal-image](../../api/plugins/plugin-ideal-image.md), you need to use the dedicated image component, as documented.
|
||||
If you are using [@docusaurus/plugin-ideal-image](../../api/plugins/plugin-ideal-image.mdx), you need to use the dedicated image component, as documented.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -214,7 +214,7 @@ To toggle the visibility of an image using the path fragment (for GitHub, it's `
|
|||
|
||||
## Static assets {#static-assets}
|
||||
|
||||
If a Markdown link or image has an absolute path, the path will be seen as a file path and will be resolved from the static directories. For example, if you have configured [static directories](../../static-assets.md) to be `['public', 'static']`, then for the following image:
|
||||
If a Markdown link or image has an absolute path, the path will be seen as a file path and will be resolved from the static directories. For example, if you have configured [static directories](../../static-assets.mdx) to be `['public', 'static']`, then for the following image:
|
||||
|
||||
```md title="my-doc.md"
|
||||
|
||||
|
|
|
|||
|
|
@ -378,7 +378,7 @@ You can disable the default line highlighting comments with `magicComments: []`.
|
|||
|
||||
Every magic comment entry will contain three keys: `className` (required), `line`, which applies to the directly next line, or `block` (containing `start` and `end`), which applies to the entire block enclosed by the two comments.
|
||||
|
||||
Using CSS to target the class can already do a lot, but you can unlock the full potential of this feature through [swizzling](../../swizzling.md).
|
||||
Using CSS to target the class can already do a lot, but you can unlock the full potential of this feature through [swizzling](../../swizzling.mdx).
|
||||
|
||||
```bash npm2yarn
|
||||
npm run swizzle @docusaurus/theme-classic CodeBlock/Line
|
||||
|
|
@ -749,7 +749,7 @@ Displaying CLI commands in both npm and Yarn is a very common need, for example:
|
|||
npm install @docusaurus/remark-plugin-npm2yarn
|
||||
```
|
||||
|
||||
Docusaurus provides such a utility out of the box, freeing you from using the `Tabs` component every time. To enable this feature, first install the `@docusaurus/remark-plugin-npm2yarn` package as above, and then in `docusaurus.config.js`, for the plugins where you need this feature (doc, blog, pages, etc.), register it in the `remarkPlugins` option. (See [Docs configuration](../../api/plugins/plugin-content-docs.md#ex-config) for more details on configuration format)
|
||||
Docusaurus provides such a utility out of the box, freeing you from using the `Tabs` component every time. To enable this feature, first install the `@docusaurus/remark-plugin-npm2yarn` package as above, and then in `docusaurus.config.js`, for the plugins where you need this feature (doc, blog, pages, etc.), register it in the `remarkPlugins` option. (See [Docs configuration](../../api/plugins/plugin-content-docs.mdx#ex-config) for more details on configuration format)
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ This `<head>` declaration has been added to the current Markdown doc as a demo.
|
|||
|
||||
:::note
|
||||
|
||||
This feature is built on top of the Docusaurus [`<Head>`](./../../docusaurus-core.md#head) component. Refer to [react-helmet](https://github.com/nfl/react-helmet) for exhaustive documentation.
|
||||
This feature is built on top of the Docusaurus [`<Head>`](./../../docusaurus-core.mdx#head) component. Refer to [react-helmet](https://github.com/nfl/react-helmet) for exhaustive documentation.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -59,14 +59,14 @@ Content plugins (e.g. docs and blog) provide front matter options like `descript
|
|||
|
||||
## Markdown page description {#markdown-page-description}
|
||||
|
||||
The Markdown pages' description metadata may be used in more places than the head metadata. For example, the docs plugin's [generated category index](../docs/sidebar/items.md#generated-index-page) uses the description metadata for the doc cards.
|
||||
The Markdown pages' description metadata may be used in more places than the head metadata. For example, the docs plugin's [generated category index](../docs/sidebar/items.mdx#generated-index-page) uses the description metadata for the doc cards.
|
||||
|
||||
By default, the description is the first content-ful line, with some efforts to convert it to plain text. For example, the following file...
|
||||
|
||||
```md
|
||||
# Title
|
||||
|
||||
Main content... May contain some [links](./file.md) or **emphasis**.
|
||||
Main content... May contain some [links](./file.mdx) or **emphasis**.
|
||||
```
|
||||
|
||||
...will have the default description "Main content... May contain some links or emphasis". However, **it's not designed to be fully functional**. Where it fails to produce reasonable descriptions, you can explicitly provide one through front matter:
|
||||
|
|
@ -78,5 +78,5 @@ description: This description will override the default.
|
|||
|
||||
# Title
|
||||
|
||||
Main content... May contain some [links](./file.md) or **emphasis**.
|
||||
Main content... May contain some [links](./file.mdx) or **emphasis**.
|
||||
```
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ There are two ways of adding a link to another page: through a **URL path** and
|
|||
|
||||
```md
|
||||
- [URL path to another document](./installation)
|
||||
- [file path to another document](./installation.md)
|
||||
- [file path to another document](./installation.mdx)
|
||||
```
|
||||
|
||||
URL paths are unprocessed by Docusaurus, and you can see them as directly rendering to `<a href="./installation">`, i.e. it will be resolved according to the page's URL location, rather than its file-system location.
|
||||
|
|
@ -20,21 +20,21 @@ If you want to reference another Markdown file **included by the same plugin**,
|
|||
For example, if you are in `docs/folder/doc1.md` and you want to reference `docs/folder/doc2.md`, `docs/folder/subfolder/doc3.md` and `docs/otherFolder/doc4.md`:
|
||||
|
||||
```md title="docs/folder/doc1.md"
|
||||
I am referencing a [document](doc2.md).
|
||||
I am referencing a [document](doc2.mdx).
|
||||
|
||||
Reference to another [document in a subfolder](subfolder/doc3.md).
|
||||
Reference to another [document in a subfolder](subfolder/doc3.mdx).
|
||||
|
||||
[Relative document](../otherFolder/doc4.md) referencing works as well.
|
||||
[Relative document](../otherFolder/doc4.mdx) referencing works as well.
|
||||
```
|
||||
|
||||
Relative file paths are resolved against the current file's directory. Absolute file paths, on the other hand, are resolved relative to the **content root**, usually `docs/`, `blog/`, or [localized ones](../../i18n/i18n-tutorial.md) like `i18n/zh-Hans/plugin-content-docs/current`.
|
||||
Relative file paths are resolved against the current file's directory. Absolute file paths, on the other hand, are resolved relative to the **content root**, usually `docs/`, `blog/`, or [localized ones](../../i18n/i18n-tutorial.mdx) like `i18n/zh-Hans/plugin-content-docs/current`.
|
||||
|
||||
Absolute file paths can also be relative to the site directory. However, beware that links that begin with `/docs/` or `/blog/` are **not portable** as you would need to manually update them if you create new doc versions or localize them.
|
||||
|
||||
```md
|
||||
You can write [links](/otherFolder/doc4.md) relative to the content root (`/docs/`).
|
||||
You can write [links](/otherFolder/doc4.mdx) relative to the content root (`/docs/`).
|
||||
|
||||
You can also write [links](/docs/otherFolder/doc4.md) relative to the site directory, but it's not recommended.
|
||||
You can also write [links](/docs/otherFolder/doc4.mdx) relative to the site directory, but it's not recommended.
|
||||
```
|
||||
|
||||
Using relative _file_ paths (with `.md` extensions) instead of relative _URL_ links provides the following benefits:
|
||||
|
|
@ -42,8 +42,8 @@ Using relative _file_ paths (with `.md` extensions) instead of relative _URL_ li
|
|||
- Links will keep working on the GitHub interface and many Markdown editors
|
||||
- You can customize the files' slugs without having to update all the links
|
||||
- Moving files around the folders can be tracked by your editor, and some editors may automatically update file links
|
||||
- A [versioned doc](../docs/versioning.md) will link to another doc of the exact same version
|
||||
- Relative URL links are very likely to break if you update the [`trailingSlash` config](../../api/docusaurus.config.js.md#trailingSlash)
|
||||
- A [versioned doc](../docs/versioning.mdx) will link to another doc of the exact same version
|
||||
- Relative URL links are very likely to break if you update the [`trailingSlash` config](../../api/docusaurus.config.js.mdx#trailingSlash)
|
||||
|
||||
:::warning
|
||||
|
||||
|
|
@ -14,7 +14,7 @@ Sometimes, you may want to extend or tweak your Markdown syntax. For example:
|
|||
|
||||
And the answer is: create an MDX plugin! MDX has a built-in [plugin system](https://mdxjs.com/advanced/plugins/) that can be used to customize how the Markdown files will be parsed and transformed to JSX. There are three typical use-cases of MDX plugins:
|
||||
|
||||
- Using existing [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins) or [rehype plugins](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins);
|
||||
- Using existing [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.mdx#list-of-plugins) or [rehype plugins](https://github.com/rehypejs/rehype/blob/main/doc/plugins.mdx#list-of-plugins);
|
||||
- Creating remark/rehype plugins to transform the elements generated by existing MDX syntax;
|
||||
- Creating remark/rehype plugins to introduce new syntaxes to MDX.
|
||||
|
||||
|
|
@ -121,7 +121,7 @@ If there isn't an existing package that satisfies your customization need, you c
|
|||
|
||||
:::note
|
||||
|
||||
The writeup below is **not** meant to be a comprehensive guide to creating a plugin, but just an illustration of how to make it work with Docusaurus. Visit the [Remark](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#creating-plugins) or [Rehype](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#creating-plugins) documentation for a more in-depth explanation of how they work.
|
||||
The writeup below is **not** meant to be a comprehensive guide to creating a plugin, but just an illustration of how to make it work with Docusaurus. Visit the [Remark](https://github.com/remarkjs/remark/blob/main/doc/plugins.mdx#creating-plugins) or [Rehype](https://github.com/remarkjs/remark/blob/main/doc/plugins.mdx#creating-plugins) documentation for a more in-depth explanation of how they work.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -84,7 +84,7 @@ Since all doc files are parsed using MDX, anything that looks like HTML is actua
|
|||
<span style={{backgroundColor: 'red'}}>Foo</span>
|
||||
```
|
||||
|
||||
This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](../../migration/migration-manual.md#convert-style-attributes-to-style-objects-in-mdx).
|
||||
This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](../../migration/migration-manual.mdx#convert-style-attributes-to-style-objects-in-mdx).
|
||||
|
||||
In addition, MDX is not [100% compatible with CommonMark](https://github.com/facebook/docusaurus/issues/3018). Use the **[MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground)** to ensure that your syntax is valid MDX.
|
||||
|
||||
|
|
@ -106,7 +106,7 @@ import BrowserWindow from '@site/src/components/BrowserWindow';
|
|||
|
||||
:::tip
|
||||
|
||||
The `@site` alias points to your website's directory, usually where the `docusaurus.config.js` file is. Using an alias instead of relative paths (`'../../src/components/BrowserWindow'`) saves you from updating import paths when moving files around, or when [versioning docs](../docs/versioning.md) and [translating](../../i18n/i18n-tutorial.md).
|
||||
The `@site` alias points to your website's directory, usually where the `docusaurus.config.js` file is. Using an alias instead of relative paths (`'../../src/components/BrowserWindow'`) saves you from updating import paths when moving files around, or when [versioning docs](../docs/versioning.mdx) and [translating](../../i18n/i18n-tutorial.mdx).
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -159,9 +159,9 @@ It will be compiled to a React component containing `ul`, `li`, `p`, and `highli
|
|||
|
||||
In Docusaurus, this MDX component scope is provided by the `@theme/MDXComponents` component. It's not a React component, _per se_, unlike most other exports under the `@theme/` alias: it is a record from tag names like `ul` and `img` to their custom implementations.
|
||||
|
||||
If you [swizzle](../../swizzling.md) this component, you will find all tags that have been re-implemented, and you can further customize our implementation by swizzling the respective sub-component, like `@theme/MDXComponents/Head` (which is used to implement the [`<head>`](./markdown-features-head-metadata.mdx) feature).
|
||||
If you [swizzle](../../swizzling.mdx) this component, you will find all tags that have been re-implemented, and you can further customize our implementation by swizzling the respective sub-component, like `@theme/MDXComponents/Head` (which is used to implement the [`<head>`](./markdown-features-head-metadata.mdx) feature).
|
||||
|
||||
If you want to register extra tag names (like the `<highlight>` tag above), you should consider [wrapping `@theme/MDXComponents`](../../swizzling.md#wrapping), so you don't have to maintain all the existing mappings. Since the swizzle CLI doesn't allow wrapping non-component files yet, you should manually create the wrapper:
|
||||
If you want to register extra tag names (like the `<highlight>` tag above), you should consider [wrapping `@theme/MDXComponents`](../../swizzling.mdx#wrapping), so you don't have to maintain all the existing mappings. Since the swizzle CLI doesn't allow wrapping non-component files yet, you should manually create the wrapper:
|
||||
|
||||
```js title="src/theme/MDXComponents.js"
|
||||
import React from 'react';
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ A special Markdown syntax lets you set an **explicit heading id**:
|
|||
|
||||
:::tip
|
||||
|
||||
Use the **[`write-heading-ids`](../../cli.md#docusaurus-write-heading-ids-sitedir)** CLI command to add explicit IDs to all your Markdown documents.
|
||||
Use the **[`write-heading-ids`](../../cli.mdx#docusaurus-write-heading-ids-sitedir)** CLI command to add explicit IDs to all your Markdown documents.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -73,7 +73,7 @@ toc_max_heading_level: 5
|
|||
---
|
||||
```
|
||||
|
||||
To set the heading level for _all_ pages, use the [`themeConfig.tableOfContents`](../../api/themes/theme-configuration.md#table-of-contents) option.
|
||||
To set the heading level for _all_ pages, use the [`themeConfig.tableOfContents`](../../api/themes/theme-configuration.mdx#table-of-contents) option.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
|
|
|
|||
|
|
@ -1,21 +0,0 @@
|
|||
# What's next?
|
||||
|
||||
Congratulations! You have understood most core features of Docusaurus now. You have:
|
||||
|
||||
- [Used the pages plugin](./creating-pages.md) to create a standalone React / Markdown page
|
||||
- [Used the docs plugin](./docs/docs-introduction.md) to create documentation pages. This includes [configuring the sidebar](./docs/sidebar/index.md), and even [versioning](./docs/versioning.md)
|
||||
- [Used the blog plugin](../blog.mdx) to create a fully featured blog
|
||||
- Tried your hands on [a range of Markdown features](./markdown-features/markdown-features-intro.mdx), which are useful for all content plugins
|
||||
- [Used stylesheets](../styling-layout.md) or [swizzling](../swizzling.md) to customize your site's appearance
|
||||
- [Included images and other assets](../static-assets.md) in your pages
|
||||
- [Added search](../search.md) to your site
|
||||
- Understood how [browser support](../browser-support.md) and [SEO](../seo.md) are done through standard Docusaurus APIs
|
||||
- Learned about how [individual plugins](../using-plugins.md) are installed and configured
|
||||
- [Deployed](../deployment.mdx) your site to a content host
|
||||
- [Internationalized](../i18n/i18n-tutorial.md) your site to include multiple languages
|
||||
|
||||
At this point, you probably have a big `docusaurus.config.js` already😄 However, you haven't written much code yet! Most of the features are implemented through calling encapsulated Docusaurus APIs. As you continue your journey, you can take three paths:
|
||||
|
||||
- Learn more advanced Docusaurus concepts. This will help you gain a deeper understand of what the APIs do.
|
||||
- Read about [all existing APIs](../docusaurus-core.md). Many of them have not been covered in the Guides!
|
||||
- Learn to [develop a plugin](../api/plugin-methods/README.md) to extend the functionality of your site.
|
||||
21
website/versioned_docs/version-2.0.1/guides/whats-next.mdx
Normal file
21
website/versioned_docs/version-2.0.1/guides/whats-next.mdx
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
# What's next?
|
||||
|
||||
Congratulations! You have understood most core features of Docusaurus now. You have:
|
||||
|
||||
- [Used the pages plugin](./creating-pages.mdx) to create a standalone React / Markdown page
|
||||
- [Used the docs plugin](./docs/docs-introduction.mdx) to create documentation pages. This includes [configuring the sidebar](./docs/sidebar/index.mdx), and even [versioning](./docs/versioning.mdx)
|
||||
- [Used the blog plugin](../blog.mdx) to create a fully featured blog
|
||||
- Tried your hands on [a range of Markdown features](./markdown-features/markdown-features-intro.mdx), which are useful for all content plugins
|
||||
- [Used stylesheets](../styling-layout.mdx) or [swizzling](../swizzling.mdx) to customize your site's appearance
|
||||
- [Included images and other assets](../static-assets.mdx) in your pages
|
||||
- [Added search](../search.mdx) to your site
|
||||
- Understood how [browser support](../browser-support.mdx) and [SEO](../seo.mdx) are done through standard Docusaurus APIs
|
||||
- Learned about how [individual plugins](../using-plugins.mdx) are installed and configured
|
||||
- [Deployed](../deployment.mdx) your site to a content host
|
||||
- [Internationalized](../i18n/i18n-tutorial.mdx) your site to include multiple languages
|
||||
|
||||
At this point, you probably have a big `docusaurus.config.js` already😄 However, you haven't written much code yet! Most of the features are implemented through calling encapsulated Docusaurus APIs. As you continue your journey, you can take three paths:
|
||||
|
||||
- Learn more advanced Docusaurus concepts. This will help you gain a deeper understand of what the APIs do.
|
||||
- Read about [all existing APIs](../docusaurus-core.mdx). Many of them have not been covered in the Guides!
|
||||
- Learn to [develop a plugin](../api/plugin-methods/README.mdx) to extend the functionality of your site.
|
||||
Loading…
Add table
Add a link
Reference in a new issue