3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-10 23:57:22 +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

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