mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-31 18:07:00 +02:00
feat(core): support TypeScript + ESM configuration (#9317)
Co-authored-by: Joshua Chen <sidachen2003@gmail.com> Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
This commit is contained in:
Chongyi Zheng
GitHub
parent
336a44f3ea
commit
45f1a669b5
126 changed files with 2054 additions and 914 deletions
|
|
@ -44,7 +44,7 @@ All docs will be served under the subroute `docs/`. But what if **your site only
|
|||
Assume that you have the following in your configuration:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
|
|
@ -66,7 +66,7 @@ module.exports = {
|
|||
To enter docs-only mode, change it to like this:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
|
|
|
|||
|
|
@ -64,7 +64,7 @@ In this case, you should use the same plugin twice in your site configuration.
|
|||
When using the preset:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
|
|
@ -75,7 +75,7 @@ module.exports = {
|
|||
// highlight-end
|
||||
path: 'product',
|
||||
routeBasePath: 'product',
|
||||
sidebarPath: require.resolve('./sidebarsProduct.js'),
|
||||
sidebarPath: './sidebarsProduct.js',
|
||||
// ... other options
|
||||
},
|
||||
},
|
||||
|
|
@ -90,7 +90,7 @@ module.exports = {
|
|||
// highlight-end
|
||||
path: 'community',
|
||||
routeBasePath: 'community',
|
||||
sidebarPath: require.resolve('./sidebarsCommunity.js'),
|
||||
sidebarPath: './sidebarsCommunity.js',
|
||||
// ... other options
|
||||
},
|
||||
],
|
||||
|
|
@ -101,7 +101,7 @@ module.exports = {
|
|||
When not using the preset:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
plugins: [
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
|
|
@ -111,7 +111,7 @@ module.exports = {
|
|||
// highlight-end
|
||||
path: 'product',
|
||||
routeBasePath: 'product',
|
||||
sidebarPath: require.resolve('./sidebarsProduct.js'),
|
||||
sidebarPath: './sidebarsProduct.js',
|
||||
// ... other options
|
||||
},
|
||||
],
|
||||
|
|
@ -123,7 +123,7 @@ module.exports = {
|
|||
// highlight-end
|
||||
path: 'community',
|
||||
routeBasePath: 'community',
|
||||
sidebarPath: require.resolve('./sidebarsCommunity.js'),
|
||||
sidebarPath: './sidebarsCommunity.js',
|
||||
// ... other options
|
||||
},
|
||||
],
|
||||
|
|
@ -190,7 +190,7 @@ Each docs-related [theme navbar items](../../api/themes/theme-configuration.mdx#
|
|||
For example, if you want to have one version dropdown for each mobile SDK (iOS and Android), you could do:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
themeConfig: {
|
||||
navbar: {
|
||||
items: [
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ type SidebarItemAutogenerated = {
|
|||
Docusaurus can generate a full sidebar from your docs folder:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
myAutogeneratedSidebar: [
|
||||
// highlight-start
|
||||
{
|
||||
|
|
@ -67,7 +67,7 @@ docs
|
|||
And assume every doc's ID is just its file name. If you define an autogenerated sidebar like this:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
mySidebar: [
|
||||
'intro',
|
||||
{
|
||||
|
|
@ -109,7 +109,7 @@ module.exports = {
|
|||
It would be resolved as:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
mySidebar: [
|
||||
'intro',
|
||||
{
|
||||
|
|
@ -175,7 +175,7 @@ A category index document is a document following one of those filename conventi
|
|||
This is equivalent to using a category with a [doc link](items.mdx#category-doc-link):
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
docs: [
|
||||
// highlight-start
|
||||
{
|
||||
|
|
@ -215,7 +215,7 @@ some-doc
|
|||
It is possible to opt out any of the category index conventions, or define even more conventions. You can inject your own `isCategoryIndex` matcher through the [`sidebarItemsGenerator`](#customize-the-sidebar-items-generator) callback. For example, you can also pick `intro` as another file name eligible for automatically becoming the category index.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
plugins: [
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
|
|
@ -247,7 +247,7 @@ module.exports = {
|
|||
Or choose to not have any category index convention.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
plugins: [
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
|
|
@ -426,7 +426,7 @@ Updating a number prefix can be annoying, as it can require **updating multiple
|
|||
You can provide a custom `sidebarItemsGenerator` function in the docs plugin (or preset) config:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
plugins: [
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
|
|
@ -477,7 +477,7 @@ function reverseSidebarItems(items) {
|
|||
}
|
||||
// highlight-end
|
||||
|
||||
module.exports = {
|
||||
export default {
|
||||
plugins: [
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
|
|
|
|||
|
|
@ -16,14 +16,14 @@ To use sidebars on your Docusaurus site:
|
|||
2. Pass this object into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
// highlight-next-line
|
||||
sidebarPath: require.resolve('./sidebars.js'),
|
||||
sidebarPath: './sidebars.js',
|
||||
},
|
||||
},
|
||||
],
|
||||
|
|
@ -44,7 +44,7 @@ import DocCardList from '@theme/DocCardList';
|
|||
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 = {
|
||||
export default {
|
||||
mySidebar: [
|
||||
{
|
||||
type: 'autogenerated',
|
||||
|
|
@ -71,7 +71,7 @@ type Sidebar =
|
|||
For example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
mySidebar: [
|
||||
{
|
||||
type: 'category',
|
||||
|
|
@ -123,7 +123,7 @@ type SidebarsFile = {
|
|||
By enabling the `themeConfig.docs.sidebar.hideable` option, you can make the entire sidebar hideable, allowing users to better focus on the content. This is especially useful when content is consumed on medium-sized screens (e.g. tablets).
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
themeConfig: {
|
||||
// highlight-start
|
||||
docs: {
|
||||
|
|
@ -141,7 +141,7 @@ module.exports = {
|
|||
The `themeConfig.docs.sidebar.autoCollapseCategories` option would collapse all sibling categories when expanding one category. This saves the user from having too many categories open and helps them focus on the selected section.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
themeConfig: {
|
||||
// highlight-start
|
||||
docs: {
|
||||
|
|
@ -178,7 +178,7 @@ By default, breadcrumbs are rendered at the top, using the "sidebar path" of the
|
|||
This behavior can be disabled with plugin options:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
|
|
@ -201,7 +201,7 @@ A real-world example from the Docusaurus site:
|
|||
import CodeBlock from '@theme/CodeBlock';
|
||||
|
||||
<CodeBlock language="js" title="sidebars.js">
|
||||
{require('!!raw-loader!@site/sidebars.js')
|
||||
{require('!!raw-loader!@site/sidebars.ts')
|
||||
.default
|
||||
.split('\n')
|
||||
// remove comments
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ type SidebarItemDoc =
|
|||
Example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
mySidebar: [
|
||||
// Normal syntax:
|
||||
// highlight-start
|
||||
|
|
@ -92,7 +92,7 @@ type SidebarItemLink = {
|
|||
Example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
myLinksSidebar: [
|
||||
// highlight-start
|
||||
// External link
|
||||
|
|
@ -133,7 +133,7 @@ type SidebarItemHtml = {
|
|||
Example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
myHtmlSidebar: [
|
||||
// highlight-start
|
||||
{
|
||||
|
|
@ -151,7 +151,7 @@ module.exports = {
|
|||
The menu item is already wrapped in an `<li>` tag, so if your custom item is simple, such as a title, just supply a string as the value and use the `className` property to style it:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
myHtmlSidebar: [
|
||||
{
|
||||
type: 'html',
|
||||
|
|
@ -186,7 +186,7 @@ type SidebarItemCategory = {
|
|||
Example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
docs: [
|
||||
{
|
||||
type: 'category',
|
||||
|
|
@ -211,7 +211,7 @@ module.exports = {
|
|||
Use the [**shorthand syntax**](#category-shorthand) when you don't need customizations:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
docs: {
|
||||
Guides: [
|
||||
'creating-pages',
|
||||
|
|
@ -242,7 +242,7 @@ Autogenerated categories can use the [`_category_.yml`](./autogenerated.mdx#cate
|
|||
You can auto-generate an index page that displays all the direct children of this category. The `slug` allows you to customize the generated page's route, which defaults to `/category/[categoryName]`.
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
docs: [
|
||||
{
|
||||
type: 'category',
|
||||
|
|
@ -276,7 +276,7 @@ Use `generated-index` links as a quick way to get an introductory document.
|
|||
A category can link to an existing document.
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
docs: [
|
||||
{
|
||||
type: 'category',
|
||||
|
|
@ -317,7 +317,7 @@ import DocCardList from '@theme/DocCardList';
|
|||
We support the option to expand/collapse categories. Categories are collapsible by default, but you can disable collapsing with `collapsible: false`.
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
docs: [
|
||||
{
|
||||
type: 'category',
|
||||
|
|
@ -340,7 +340,7 @@ module.exports = {
|
|||
To make all categories non-collapsible by default, set the `sidebarCollapsible` option in `plugin-content-docs` to `false`:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
|
|
@ -366,7 +366,7 @@ The option in `sidebars.js` takes precedence over plugin configuration, so it is
|
|||
Collapsible categories are collapsed by default. If you want them to be expanded on the first render, you can set `collapsed` to `false`:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
docs: {
|
||||
Guides: [
|
||||
'creating-pages',
|
||||
|
|
@ -385,7 +385,7 @@ 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 = {
|
||||
export default {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
|
|
@ -420,7 +420,7 @@ An item with type `doc` can be simply a string representing its ID:
|
|||
```
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
sidebar: [
|
||||
// highlight-start
|
||||
{
|
||||
|
|
@ -438,7 +438,7 @@ module.exports = {
|
|||
```
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
sidebar: [
|
||||
// highlight-start
|
||||
'myDoc',
|
||||
|
|
@ -455,7 +455,7 @@ module.exports = {
|
|||
So it's possible to simplify the example above to:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
mySidebar: [
|
||||
{
|
||||
type: 'category',
|
||||
|
|
@ -494,7 +494,7 @@ A category item can be represented by an object whose key is its label, and the
|
|||
```
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
sidebar: [
|
||||
// highlight-start
|
||||
{
|
||||
|
|
@ -513,7 +513,7 @@ module.exports = {
|
|||
```
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
sidebar: [
|
||||
// highlight-start
|
||||
{
|
||||
|
|
@ -532,7 +532,7 @@ module.exports = {
|
|||
This permits us to simplify that example to:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
mySidebar: [
|
||||
// highlight-start
|
||||
{
|
||||
|
|
@ -554,7 +554,7 @@ module.exports = {
|
|||
Each shorthand object after this transformation will contain exactly one entry. Now consider the further simplified example below:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
mySidebar: [
|
||||
// highlight-start
|
||||
{
|
||||
|
|
@ -581,7 +581,7 @@ Wherever you have an array of items that is reduced to one category shorthand, y
|
|||
```
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
sidebar: [
|
||||
{
|
||||
'Getting started': ['doc1'],
|
||||
|
|
@ -602,7 +602,7 @@ module.exports = {
|
|||
```
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
sidebar: {
|
||||
'Getting started': ['doc1'],
|
||||
Docusaurus: {
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ The Docusaurus site is a good example of using multiple sidebars:
|
|||
Consider this example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
tutorialSidebar: {
|
||||
'Category A': ['doc1', 'doc2'],
|
||||
},
|
||||
|
|
@ -33,7 +33,7 @@ When browsing `doc1` or `doc2`, the `tutorialSidebar` will be displayed; when br
|
|||
Following the example above, if a `commonDoc` is included in both sidebars:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
tutorialSidebar: {
|
||||
'Category A': ['doc1', 'doc2', 'commonDoc'],
|
||||
},
|
||||
|
|
@ -51,7 +51,7 @@ When you add doc Y to sidebar X, it creates a two-way binding: sidebar X contain
|
|||
Front matter option `displayed_sidebar` will forcibly set the sidebar association. For the same example, you can still use doc shorthands without any special configuration:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
tutorialSidebar: {
|
||||
'Category A': ['doc1', 'doc2'],
|
||||
},
|
||||
|
|
@ -88,7 +88,7 @@ If a sidebar is displayed by setting `displayed_sidebar` front matter, and this
|
|||
You can customize pagination with front matter `pagination_next` and `pagination_prev`. Consider this sidebar:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
tutorial: [
|
||||
'introduction',
|
||||
{
|
||||
|
|
@ -123,7 +123,7 @@ It is particularly useful where you wish to link to the same document from multi
|
|||
Consider this example:
|
||||
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
tutorialSidebar: {
|
||||
'Category A': [
|
||||
'doc1',
|
||||
|
|
@ -135,7 +135,6 @@ module.exports = {
|
|||
},
|
||||
apiSidebar: ['doc3', 'doc4', 'commonDoc'],
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
You can think of the `ref` type as the equivalent to doing the following:
|
||||
|
|
|
|||
|
|
@ -187,7 +187,7 @@ Docusaurus defaults work great for the first use case. We will label the current
|
|||
**For the 2nd use case**: if you release v1 and don't plan to work on v2 anytime soon, instead of versioning v1 and having to maintain the docs in 2 folders (`./docs` + `./versioned_docs/version-1.0.0`), you may consider "pretending" that the current version is a cut version by giving it a path and a label:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
presets: [
|
||||
'@docusaurus/preset-classic',
|
||||
docs: {
|
||||
|
|
|
|||
|
|
@ -275,7 +275,7 @@ export default function AdmonitionWrapper(props) {
|
|||
Admonitions are implemented with a [Remark plugin](./markdown-features-plugins.mdx). The plugin is designed to be configurable. To customize the Remark plugin for a specific content plugin (docs, blog, pages), pass the options through the `admonitions` key.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
|
|
@ -306,7 +306,7 @@ By default, the theme doesn't know what do to with custom admonition keywords su
|
|||
If you registered a new admonition type `my-custom-admonition` via the following config:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
|
|
|
|||
|
|
@ -64,19 +64,19 @@ By default, the Prism [syntax highlighting theme](https://github.com/FormidableL
|
|||
For example, if you prefer to use the `dracula` highlighting theme:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
const {themes} = require('prism-react-renderer');
|
||||
import {themes as prismThemes} from 'prism-react-renderer';
|
||||
|
||||
module.exports = {
|
||||
export default {
|
||||
themeConfig: {
|
||||
prism: {
|
||||
// highlight-next-line
|
||||
theme: themes.dracula,
|
||||
theme: prismThemes.dracula,
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
Because a Prism theme is just a JS object, you can also write your own theme if you are not satisfied with the default. Docusaurus enhances the `github` and `vsDark` themes to provide richer highlight, and you can check our implementations for the [light](https://github.com/facebook/docusaurus/blob/main/website/src/utils/prismLight.mjs) and [dark](https://github.com/facebook/docusaurus/blob/main/website/src/utils/prismDark.mjs) code block themes.
|
||||
Because a Prism theme is just a JS object, you can also write your own theme if you are not satisfied with the default. Docusaurus enhances the `github` and `vsDark` themes to provide richer highlight, and you can check our implementations for the [light](https://github.com/facebook/docusaurus/blob/main/website/src/utils/prismLight.ts) and [dark](https://github.com/facebook/docusaurus/blob/main/website/src/utils/prismDark.ts) code block themes.
|
||||
|
||||
### Supported Languages {#supported-languages}
|
||||
|
||||
|
|
@ -99,7 +99,7 @@ Each additional language has to be a valid Prism component name. For example, Pr
|
|||
For example, if you want to add highlighting for the PowerShell language:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
// ...
|
||||
themeConfig: {
|
||||
prism: {
|
||||
|
|
@ -301,7 +301,7 @@ You can declare custom magic comments through theme config. For example, you can
|
|||
```
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
export default {
|
||||
themeConfig: {
|
||||
prism: {
|
||||
magicComments: [
|
||||
|
|
@ -445,7 +445,7 @@ npm install --save @docusaurus/theme-live-codeblock
|
|||
You will also need to add the plugin to your `docusaurus.config.js`.
|
||||
|
||||
```js {3}
|
||||
module.exports = {
|
||||
export default {
|
||||
// ...
|
||||
themes: ['@docusaurus/theme-live-codeblock'],
|
||||
// ...
|
||||
|
|
@ -758,7 +758,7 @@ 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.mdx#ex-config) for more details on configuration format)
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ npm install --save @docusaurus/theme-mermaid
|
|||
Enable Mermaid functionality by adding plugin `@docusaurus/theme-mermaid` and setting `markdown.mermaid` to `true` in your `docusaurus.config.js`.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
markdown: {
|
||||
mermaid: true,
|
||||
},
|
||||
|
|
@ -55,7 +55,7 @@ See the [Mermaid syntax documentation](https://mermaid-js.github.io/mermaid/#/./
|
|||
The diagram dark and light themes can be changed by setting `mermaid.theme` values in the `themeConfig` in your `docusaurus.config.js`. You can set themes for both light and dark mode.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
themeConfig: {
|
||||
mermaid: {
|
||||
theme: {light: 'neutral', dark: 'forest'},
|
||||
|
|
@ -71,7 +71,7 @@ See the [Mermaid theme documentation](https://mermaid-js.github.io/mermaid/#/the
|
|||
Options in `mermaid.options` will be passed directly to `mermaid.initialize`:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
themeConfig: {
|
||||
mermaid: {
|
||||
options: {
|
||||
|
|
|
|||
|
|
@ -63,24 +63,62 @@ Make sure to use `remark-math >= 5` and `rehype-katex >= 6` for Docusaurus v3 (u
|
|||
|
||||
:::
|
||||
|
||||
Those 2 plugins are now only available as ESM packages, and you will need to import them dynamically.
|
||||
Those 2 plugins are now [**only available as ES Modules**](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). To simplify usage, it is recommended to use an [**ES Modules**](https://flaviocopes.com/es-modules/) config file:
|
||||
|
||||
First, turn your site config into an async config creator function:
|
||||
```js title="ES module docusaurus.config.js"
|
||||
// highlight-start
|
||||
import remarkMath from 'remark-math';
|
||||
import rehypeKatex from 'rehype-katex';
|
||||
// highlight-end
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
// highlight-start
|
||||
export default {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
path: 'docs',
|
||||
// highlight-start
|
||||
remarkPlugins: [remarkMath],
|
||||
rehypePlugins: [rehypeKatex],
|
||||
// highlight-end
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>Using a [**CommonJS**](https://nodejs.org/api/modules.html#modules-commonjs-modules) config file?</summary>
|
||||
|
||||
If you decide to use a CommonJS config file, it is possible to load those ES module plugins thanks to dynamic imports and an async config creator function:
|
||||
|
||||
```js title="CommonJS module docusaurus.config.js"
|
||||
// highlight-start
|
||||
module.exports = async function createConfigAsync() {
|
||||
// highlight-end
|
||||
return {
|
||||
// your site config...
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
path: 'docs',
|
||||
// highlight-start
|
||||
remarkPlugins: [(await import('remark-math')).default],
|
||||
rehypePlugins: [(await import('rehype-katex')).default],
|
||||
// highlight-end
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
It is now possible to import the plugins dynamically and add them to your content plugin or preset options (usually `@docusaurus/preset-classic` docs options):
|
||||
|
||||
```js
|
||||
remarkPlugins: [(await import('remark-math')).default],
|
||||
rehypePlugins: [(await import('rehype-katex')).default],
|
||||
```
|
||||
</details>
|
||||
|
||||
Include the KaTeX CSS in your config under `stylesheets`:
|
||||
|
||||
|
|
@ -99,36 +137,39 @@ stylesheets: [
|
|||
Overall the changes look like:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = async function createConfigAsync() {
|
||||
return {
|
||||
title: 'Docusaurus',
|
||||
tagline: 'Build optimized websites quickly, focus on your content',
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
path: 'docs',
|
||||
// highlight-start
|
||||
remarkPlugins: [(await import('remark-math')).default],
|
||||
rehypePlugins: [(await import('rehype-katex')).default],
|
||||
// highlight-end
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
// highlight-start
|
||||
stylesheets: [
|
||||
// highlight-start
|
||||
import remarkMath from 'remark-math';
|
||||
import rehypeKatex from 'rehype-katex';
|
||||
// highlight-end
|
||||
|
||||
export default {
|
||||
title: 'Docusaurus',
|
||||
tagline: 'Build optimized websites quickly, focus on your content',
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
|
||||
type: 'text/css',
|
||||
integrity:
|
||||
'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
|
||||
crossorigin: 'anonymous',
|
||||
docs: {
|
||||
path: 'docs',
|
||||
// highlight-start
|
||||
remarkPlugins: [remarkMath],
|
||||
rehypePlugins: [rehypeKatex],
|
||||
// highlight-end
|
||||
},
|
||||
},
|
||||
],
|
||||
// highlight-end
|
||||
};
|
||||
],
|
||||
// highlight-start
|
||||
stylesheets: [
|
||||
{
|
||||
href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
|
||||
type: 'text/css',
|
||||
integrity:
|
||||
'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
|
||||
crossorigin: 'anonymous',
|
||||
},
|
||||
],
|
||||
// highlight-end
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -137,7 +178,7 @@ module.exports = async function createConfigAsync() {
|
|||
Loading stylesheets, fonts, and JavaScript libraries from CDN sources is a good practice for popular libraries and assets, since it reduces the amount of assets you have to host. In case you prefer to self-host the `katex.min.css` (along with required KaTeX fonts), you can download the latest version from [KaTeX GitHub releases](https://github.com/KaTeX/KaTeX/releases), extract and copy `katex.min.css` and `fonts` directory (only `.woff2` font types should be enough) to your site's `static` directory, and in `docusaurus.config.js`, replace the stylesheet's `href` from the CDN URL to your local path (say, `/katex/katex.min.css`).
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
stylesheets: [
|
||||
{
|
||||
href: '/katex/katex.min.css',
|
||||
|
|
|
|||
|
|
@ -59,11 +59,41 @@ Next, the `rehype-katex` operates on the Hypertext AST where everything has been
|
|||
|
||||
:::warning
|
||||
|
||||
Many official Remark/Rehype plugins are using ES Modules, a new JavaScript module system, which Docusaurus doesn't support yet. To work around this issue, we recommend to use dynamic `import()` inside an `async` config creation function.
|
||||
Many official Remark/Rehype plugins are [**ES Modules only**](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c), a JavaScript module system, which Docusaurus supports. We recommend using an [**ES Modules**](https://flaviocopes.com/es-modules/) config file to make it easier to import such packages.
|
||||
|
||||
:::
|
||||
|
||||
Next, add them to the plugin options through plugin or preset config in `docusaurus.config.js`, using dynamic `import()`:
|
||||
Next, import your plugins and add them to the plugin options through plugin or preset config in `docusaurus.config.js`:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
// highlight-start
|
||||
import remarkMath from 'remark-math';
|
||||
import rehypeKatex from 'rehype-katex';
|
||||
// highlight-end
|
||||
|
||||
// highlight-start
|
||||
export default {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
path: 'docs',
|
||||
// highlight-start
|
||||
remarkPlugins: [remarkMath],
|
||||
rehypePlugins: [rehypeKatex],
|
||||
// highlight-end
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>Using a [**CommonJS**](https://nodejs.org/api/modules.html#modules-commonjs-modules) config file?</summary>
|
||||
|
||||
If you decide to use a CommonJS config file, it is possible to load those ES module plugins thanks to dynamic imports and an async config creator function:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
// highlight-start
|
||||
|
|
@ -88,28 +118,30 @@ module.exports = async function createConfigAsync() {
|
|||
};
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## Configuring plugins {#configuring-plugins}
|
||||
|
||||
Some plugins can be configured and accept their own options. In that case, use the `[plugin, pluginOptions]` syntax, like this:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = async function createConfigAsync() {
|
||||
return {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
rehypePlugins: [
|
||||
// highlight-start
|
||||
[(await import('rehype-katex')).default, {strict: false}],
|
||||
// highlight-end
|
||||
],
|
||||
},
|
||||
import rehypeKatex from 'rehype-katex';
|
||||
|
||||
export default {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
rehypePlugins: [
|
||||
// highlight-start
|
||||
[rehypeKatex, {strict: false}],
|
||||
// highlight-end
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
};
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -128,7 +160,7 @@ The writeup below is **not** meant to be a comprehensive guide to creating a plu
|
|||
For example, let's make a plugin that visits every `h2` heading and adds a `Section X. ` prefix. First, create your plugin source file anywhere—you can even publish it as a separate npm package and install it like explained above. We would put ours at `src/remark/section-prefix.js`. A remark/rehype plugin is just a function that receives the `options` and returns a `transformer` that operates on the AST.
|
||||
|
||||
```js "src/remark/section-prefix.js"
|
||||
const visit = require('unist-util-visit');
|
||||
import visit from 'unist-util-visit';
|
||||
|
||||
const plugin = (options) => {
|
||||
const transformer = async (ast) => {
|
||||
|
|
@ -146,16 +178,16 @@ const plugin = (options) => {
|
|||
return transformer;
|
||||
};
|
||||
|
||||
module.exports = plugin;
|
||||
export default plugin;
|
||||
```
|
||||
|
||||
You can now import your plugin in `docusaurus.config.js` and use it just like an installed plugin!
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
// highlight-next-line
|
||||
const sectionPrefix = require('./src/remark/section-prefix');
|
||||
import sectionPrefix from './src/remark/section-prefix';
|
||||
|
||||
module.exports = {
|
||||
export default {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
|
|
@ -195,7 +227,7 @@ Our `transformImage` plugin uses this parameter, for example, to transform relat
|
|||
The default plugins of Docusaurus would operate before the custom remark plugins, and that means the images or links have been converted to JSX with `require()` calls already. For example, in the example above, the table of contents generated is still the same even when all `h2` headings are now prefixed by `Section X.`, because the TOC-generating plugin is called before our custom plugin. If you need to process the MDAST before the default plugins do, use the `beforeDefaultRemarkPlugins` and `beforeDefaultRehypePlugins`.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
export default {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ toc_max_heading_level: 5
|
|||
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 = {
|
||||
export default {
|
||||
themeConfig: {
|
||||
tableOfContents: {
|
||||
// highlight-start
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue