From c396566cc9540f9ccbdea856ea36604847712c6c Mon Sep 17 00:00:00 2001 From: sebastienlorber Date: Fri, 23 Jun 2023 17:52:30 +0200 Subject: [PATCH] Refactor Markdown, MDX and CommonMark docs --- packages/docusaurus-types/src/config.d.ts | 19 ++++--- website/docs/api/docusaurus.config.js.mdx | 42 +++++++++++++++- .../markdown-features-intro.mdx | 50 ++++++++++++++----- .../markdown-features-react.mdx | 17 +------ 4 files changed, 93 insertions(+), 35 deletions(-) diff --git a/packages/docusaurus-types/src/config.d.ts b/packages/docusaurus-types/src/config.d.ts index a4e1b6733370..3a7bb99ae743 100644 --- a/packages/docusaurus-types/src/config.d.ts +++ b/packages/docusaurus-types/src/config.d.ts @@ -16,6 +16,17 @@ export type ThemeConfig = { [key: string]: unknown; }; +export type MarkdownPreprocessor = (args: { + filePath: string; + fileContent: string; +}) => string; + +export type MDX1CompatOptions = { + comments: boolean; + admonitions: boolean; + headingIds: boolean; +}; + export type MarkdownConfig = { /** * The Markdown format to use by default. @@ -51,17 +62,13 @@ export type MarkdownConfig = { * * @param args */ - preprocessor?: (args: {filePath: string; fileContent: string}) => string; + preprocessor?: MarkdownPreprocessor; /** * Set of flags make it easier to upgrade from MDX 1 to MDX 2 * See also https://github.com/facebook/docusaurus/issues/4029 */ - mdx1Compat: { - comments: boolean; - admonitions: boolean; - headingIds: boolean; - }; + mdx1Compat: MDX1CompatOptions; }; /** diff --git a/website/docs/api/docusaurus.config.js.mdx b/website/docs/api/docusaurus.config.js.mdx index d86a697b1a08..4a792231fd61 100644 --- a/website/docs/api/docusaurus.config.js.mdx +++ b/website/docs/api/docusaurus.config.js.mdx @@ -4,6 +4,8 @@ description: API reference for Docusaurus configuration file. slug: /api/docusaurus-config --- +import APITable from '@site/src/components/APITable'; + # `docusaurus.config.js` :::info @@ -400,8 +402,24 @@ The global Docusaurus Markdown config. - Type: `MarkdownConfig` ```ts +type MarkdownPreprocessor = (args: { + filePath: string; + fileContent: string; +}) => string; + +type MDX1CompatOptions = + | boolean + | { + comments: boolean; + admonitions: boolean; + headingIds: boolean; + }; + type MarkdownConfig = { + format: 'mdx' | 'md' | 'detect'; mermaid: boolean; + preprocessor?: MarkdownPreprocessor; + mdx1Compat: MDX1CompatOptions; }; ``` @@ -410,12 +428,34 @@ Example: ```js title="docusaurus.config.js" module.exports = { markdown: { + format: 'mdx', mermaid: true, + preprocessor: ({filePath, fileContent}) => { + return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE'); + }, + mdx1Compat: { + comments: true, + admonitions: true, + headingIds: true, + }, }, }; ``` -- `mermaid`: when `true`, allows Docusaurus to render Markdown code blocks with `mermaid` language as Mermaid diagrams. +```mdx-code-block + +``` + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `format` | `'mdx' \| 'md' \| 'detect'` | `'mdx'` | The default parser format to use for Markdown content. Using 'detect' will select the appropriate format automatically based on file extensions: `.md` vs `.mdx`. | +| `mermaid` | `boolean` | `false` | When `true`, allows Docusaurus to render Markdown code blocks with `mermaid` language as Mermaid diagrams. | +| `preprocessor` | `MarkdownPreprocessor` | `undefined` | Gives you the ability to alter the Markdown content string before parsing. Use it as a last-resort escape hatch or workaround: it is almost always better to implement a Remark/Rehype plugin. | +| `mdx1Compat` | `MDX1CompatOptions` | `{comments: true, admonitions: true, headingIds: true}` | Compatibility options to make it easier to upgrade to Docusaurus v3+. See the [MDX 2 PR for details](https://github.com/facebook/docusaurus/pull/8288). | + +```mdx-code-block + +``` ### `customFields` {#customFields} diff --git a/website/docs/guides/markdown-features/markdown-features-intro.mdx b/website/docs/guides/markdown-features/markdown-features-intro.mdx index 2da413878351..2ab48769c6ea 100644 --- a/website/docs/guides/markdown-features/markdown-features-intro.mdx +++ b/website/docs/guides/markdown-features/markdown-features-intro.mdx @@ -8,13 +8,47 @@ slug: /markdown-features import BrowserWindow from '@site/src/components/BrowserWindow'; -Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible. +Docusaurus uses **[Markdown](https://commonmark.org/)** as its main content authoring format. -Docusaurus 2 uses modern tooling to help you compose your interactive documentation with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users. +:::tip Learn Markdown -:::important +You can [learn Markdown in 10 minutes](https://commonmark.org/help/). -This section assumes you are using the official Docusaurus content plugins. +::: + +Docusaurus uses modern tooling to help you create **interactive documentation**. + +The **[MDX](https://mdxjs.com/)** compiler transforms **Markdown files to React components**, and allows you to use JSX in your Markdown content. This enables you to easily interleave React components within your content, and create delightful learning experiences. + +:::tip Use the MDX Playground + +The **[MDX playground](https://mdxjs.com/playground/)** is your new best friend! + +It is a very helpful debugging tool that shows how the MDX compiler transforms Markdown to React. + +**Options**: select the right format (MDX or CommonMark) and the following plugins Docusaurus uses: `remark-gfm`, `remark-directive`, `rehype-raw`. + +::: + +## MDX vs. CommonMark {#mdx-vs-commonmark} + +Docusaurus compiles both `.md` and `.mdx` files to React components using the MDX compiler, but **the syntax can be interpreted differently** depending on your settings. + +The MDX compiler supports [2 formats](https://mdxjs.com/packages/mdx/#optionsformat): + +- The [MDX format](https://mdxjs.com/docs/what-is-mdx/): a powerful parser allowing the usage of JSX +- The [CommonMark format](https://commonmark.org/): a standard-compliant Markdown parser that does not allow the usage of JSX + +By default, **Docusaurus v3 uses the MDX format for all files** (including `.md` files) for historical reasons. + +It is possible to **opt-in for CommonMark** using the [`siteConfig.markdown.format`](../../api/docusaurus.config.js.mdx#markdown) setting or the `format: md` front matter. + +:::tip how to use CommonMark + +If you plan to use CommonMark, we recommend the [`siteConfig.markdown.format: 'detect'`](../../api/docusaurus.config.js.mdx#markdown) setting. The appropriate format will be selected automatically, based on file extensions: + +- `.md` files will use the CommonMark format +- `.mdx` files will use the MDX format ::: @@ -22,8 +56,6 @@ This section assumes you are using the official Docusaurus content plugins. Markdown is a syntax that enables you to write formatted content in a readable syntax. -We use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax), like rendering React components inside your documents as well. - ```md ### My Doc Section @@ -143,9 +175,3 @@ Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/ ``` - -:::note - -In practice, those are not really HTML elements, but React JSX elements, which we'll cover next! - -::: diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx index 9c1272f9a50b..a8ca44af65a8 100644 --- a/website/docs/guides/markdown-features/markdown-features-react.mdx +++ b/website/docs/guides/markdown-features/markdown-features-react.mdx @@ -13,24 +13,9 @@ import TabItem from '@theme/TabItem'; import styles from './markdown-features-react.module.css'; ``` -## Using JSX in Markdown {#using-jsx-in-markdown} - Docusaurus has built-in support for [MDX v2](https://mdxjs.com/), which allows you to write JSX within your Markdown files and render them as React components. -:::info MDX vs. CommonMark - -Docusaurus parses both `.md` and `.mdx` files using MDX, but **the syntax is interpreted differently based on the file extension**: - -- With the `.md` extension, the parser is compatible with [CommonMark](https://commonmark.org/) and does not allow the usage of JSX. -- With the `.mdx` extension, the parser is stricter than [CommonMark](https://commonmark.org/) and is not 100% compatible with it, but it becomes possible to use JSX. - -It is also possible to override the file extension format with front matter: `format: mdx`. - -The rest of this page assumes usage of the `mdx` format. - -::: - -Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX. +Check out the [MDX docs](https://mdxjs.com/) to see what fancy stuff you can do with MDX. :::tip Debugging MDX