3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-06-24 21:48:02 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat(core): support TypeScript + ESM configuration (#9317)

Browse source 
Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
This commit is contained in:
Chongyi Zheng 2023-10-13 20:46:03 -04:00 • committed by GitHub
parent 336a44f3ea
commit 45f1a669b5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
126 changed files with 2054 additions and 914 deletions
Download patch file Download diff file Expand all files Collapse all files

4
website/docs/guides/markdown-features/markdown-features-admonitions.mdx
View file

@ -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: [
[

16
website/docs/guides/markdown-features/markdown-features-code-blocks.mdx
View file

@ -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: [
[

6
website/docs/guides/markdown-features/markdown-features-diagrams.mdx
View file

@ -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: {

117
website/docs/guides/markdown-features/markdown-features-math-equations.mdx
View file

@ -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',

76
website/docs/guides/markdown-features/markdown-features-plugins.mdx
View file

@ -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',

2
website/docs/guides/markdown-features/markdown-features-toc.mdx
View file

@ -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