From 3cdd038d28217bb589641c710017ad6fababdb7c Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 7 Apr 2022 16:27:28 +0800 Subject: [PATCH] docs: multiple documentation improvements (#7126) --- website/docs/advanced/routing.md | 4 +- website/docs/guides/creating-pages.md | 8 +- .../markdown-features-intro.mdx | 18 +- website/docs/using-plugins.md | 208 +++++++++--------- 4 files changed, 125 insertions(+), 113 deletions(-) diff --git a/website/docs/advanced/routing.md b/website/docs/advanced/routing.md index 9aca36f249..82c85b7aae 100644 --- a/website/docs/advanced/routing.md +++ b/website/docs/advanced/routing.md @@ -257,14 +257,14 @@ If you put some HTML pages under the `static` folder, they will be copied to the -- /pure-html +- [/pure-html](/pure-html) - [pathname:///pure-html](pathname:///pure-html) :::tip -The first link will trigger a "broken links detected" check during the production build. +The first link will **not** trigger a "broken links detected" check during the production build, because the respective file actually exists. Nevertheless, when you click on the link, a "page not found" will be displayed until you refresh. ::: diff --git a/website/docs/guides/creating-pages.md b/website/docs/guides/creating-pages.md index f8745e6cbf..cdf100cdf9 100644 --- a/website/docs/guides/creating-pages.md +++ b/website/docs/guides/creating-pages.md @@ -7,11 +7,7 @@ sidebar_label: Pages In this section, we will learn about creating pages in Docusaurus. -This is useful for creating **one-off standalone pages** like a showcase page, playground page, or support page. - -The functionality of pages is powered by `@docusaurus/plugin-content-pages`. - -You can use React components, or Markdown. +The `@docusaurus/plugin-content-pages` plugin empowers you to create **one-off standalone pages** like a showcase page, playground page, or support page. You can use React components, or Markdown. :::note @@ -69,7 +65,7 @@ You can also create TypeScript pages with the `.tsx` extension (`helloReact.tsx` Create a file `/src/pages/helloMarkdown.md`: -```mdx title="/src/pages/helloMarkdown.md" +```md title="/src/pages/helloMarkdown.md" --- title: my hello page title description: my hello page description diff --git a/website/docs/guides/markdown-features/markdown-features-intro.mdx b/website/docs/guides/markdown-features/markdown-features-intro.mdx index 77bb79d0fd..afefc966a2 100644 --- a/website/docs/guides/markdown-features/markdown-features-intro.mdx +++ b/website/docs/guides/markdown-features/markdown-features-intro.mdx @@ -2,7 +2,7 @@ id: introduction title: Markdown Features sidebar_label: Introduction -description: Docusaurus uses GitHub Flavored Markdown (GFM). Find out more about Docusaurus-specific features when writing Markdown. +description: Docusaurus uses MDX. Find out more about Docusaurus-specific features when writing Markdown. slug: /markdown-features --- @@ -22,7 +22,7 @@ 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. -The [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax) is supported, and we use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing Markdown, like rendering React components inside your documents. +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 @@ -35,7 +35,7 @@ Hello world message with some **bold** text, some _italic_ text, and a [link](/) ```mdx-code-block -

My Doc Section

+

My Doc Section

Hello world message with some **bold** text, some _italic_ text and a [link](/) @@ -44,6 +44,18 @@ Hello world message with some **bold** text, some _italic_ text and a [link](/) ``` +
+ +Markdown is declarative + +Some may assume a 1-1 correlation between Markdown and HTML, e.g., `![Preview](/img/docusaurus.png)` will always become `Preview`, as-is. However, _that is not the case_. + +The Markdown syntax `![message](url)` only declaratively tells Docusaurus that an image needs to be inserted here, but we may do other things like transforming a [file path to URL path](./markdown-features-assets.mdx#images), so the generated markup may differ from the output of other Markdown renderers, or a naïve hand-transcription to the equivalent JSX/HTML code. + +In general, you should only assume the _semantics_ of the markup (` ``` ` fences become [code blocks](./markdown-features-code-blocks.mdx); `>` becomes [quotes](#quotes), etc.), but not the actual compiled output. + +
+ ## Quotes {#quotes} Markdown quotes are beautifully styled: diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index ac47fa25fe..d845e4bbe6 100644 --- a/website/docs/using-plugins.md +++ b/website/docs/using-plugins.md @@ -29,18 +29,18 @@ module.exports = { Docusaurus can also load plugins from your local directory, with something like the following: ```js title="docusaurus.config.js" -const path = require('path'); - module.exports = { // ... // highlight-next-line - plugins: [path.resolve(__dirname, '/path/to/docusaurus-local-plugin')], + plugins: ['./src/plugins/docusaurus-local-plugin'], }; ``` +Paths should be absolute or relative to the config file. + ## Configuring plugins {#configuring-plugins} -For the most basic usage of plugins, you can provide just the plugin name or the absolute path to the plugin. +For the most basic usage of plugins, you can provide just the plugin name or the path to the plugin. However, plugins can have options specified by wrapping the name and an options object in a two-member tuple inside your config. This style is usually called "Babel Style". @@ -114,7 +114,7 @@ At most one plugin instance can be the "default plugin instance", by omitting th ## Using themes {#using-themes} -Themes are loaded in the exact same way as plugins—the line between them is blurry. From the consumer perspective, the `themes` and `plugins` entries are interchangeable when installing and configuring a plugin. The only nuance is that themes are loaded after plugins, and it's possible for [a theme to override a plugin's default theme components](./swizzling.md#theme-aliases). +Themes are loaded in the exact same way as plugins. From the consumer perspective, the `themes` and `plugins` entries are interchangeable when installing and configuring a plugin. The only nuance is that themes are loaded after plugins, and it's possible for [a theme to override a plugin's default theme components](./swizzling.md#theme-aliases). :::tip @@ -132,101 +132,23 @@ module.exports = { ## Using presets {#using-presets} -A preset is usually an npm package, so you install them like other npm packages using npm. - -```bash npm2yarn -npm install --save @docusaurus/preset-classic -``` - -Then, add it in your site's `docusaurus.config.js`'s `presets` option: - -```js title="docusaurus.config.js" -module.exports = { - // ... - // highlight-next-line - presets: ['@docusaurus/preset-classic'], -}; -``` - -To load presets from your local directory, specify how to resolve them: - -```js title="docusaurus.config.js" -const path = require('path'); - -module.exports = { - // ... - // highlight-next-line - presets: [path.resolve(__dirname, '/path/to/docusaurus-local-preset')], -}; -``` - -Presets are a shorthand function to add plugins and themes to your Docusaurus config. For example, you can specify a preset that includes the following themes and plugins: - -```js title="/path/to/docusaurus-local-preset" -module.exports = function preset(context, opts = {}) { - return { - themes: [['docusaurus-theme-awesome', opts.theme]], - plugins: [ - // Using three docs plugins at the same time! - // Assigning a unique ID for each without asking the user to do it - ['@docusaurus/plugin-content-docs', {...opts.docs1, id: 'docs1'}], - ['@docusaurus/plugin-content-docs', {...opts.docs2, id: 'docs2'}], - ['@docusaurus/plugin-content-docs', {...opts.docs3, id: 'docs3'}], - ], - }; -}; -``` - -then in your Docusaurus config, you may configure the preset instead: - -```js title="docusaurus.config.js" -module.exports = { - presets: [ - // highlight-start - [ - path.resolve(__dirname, '/path/to/docusaurus-local-preset'), - { - theme: {hello: 'world'}, - docs1: {path: '/docs'}, - docs2: {path: '/community'}, - docs3: {path: '/api'}, - }, - ], - // highlight-end - ], -}; -``` - -This is equivalent of doing: - -```js title="docusaurus.config.js" -module.exports = { - themes: [['docusaurus-theme-awesome', {hello: 'world'}]], - plugins: [ - ['@docusaurus/plugin-content-docs', {id: 'docs1', path: '/docs'}], - ['@docusaurus/plugin-content-docs', {id: 'docs2', path: '/community'}], - ['@docusaurus/plugin-content-docs', {id: 'docs3', path: '/api'}], - ], -}; -``` - -This is especially useful when some plugins and themes are intended to be used together. You can even link their options together, e.g. pass one option to multiple plugins. +Presets are bundles of plugins and themes. For example, instead of letting you register and configure `@docusaurus/plugin-content-docs`, `@docusaurus/plugin-content-blog`, etc. one after the other in the config file, we have `@docusaurus/preset-classic` preset allows you to configure them in one centralized place. ### `@docusaurus/preset-classic` {#docusauruspreset-classic} -The classic preset is shipped by default to new Docusaurus website created with [`create-docusaurus`](./installation.md#scaffold-project-website). It is a set of plugins and themes. +The classic preset is shipped by default to new Docusaurus websites created with [`create-docusaurus`](./installation.md#scaffold-project-website). It contains the following themes and plugins: -| Themes | Plugins | -| --- | --- | -| [`@docusaurus/theme-classic`](./api/themes/theme-configuration.md) | [`@docusaurus/plugin-content-docs`](./api/plugins/plugin-content-docs.md) | -| [`@docusaurus/theme-search-algolia`](./api/themes/theme-search-algolia.md) | [`@docusaurus/plugin-content-blog`](./api/plugins/plugin-content-blog.md) | -| | [`@docusaurus/plugin-content-pages`](./api/plugins/plugin-content-pages.md) | -| | [`@docusaurus/plugin-debug`](./api/plugins/plugin-debug.md) | -| | [`@docusaurus/plugin-google-analytics`](./api/plugins/plugin-google-analytics.md) | -| | [`@docusaurus/plugin-google-gtag`](./api/plugins/plugin-google-gtag.md) | -| | [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.md) | +- [`@docusaurus/theme-classic`](./api/themes/theme-configuration.md) +- [`@docusaurus/theme-search-algolia`](./api/themes/theme-search-algolia.md) +- [`@docusaurus/plugin-content-docs`](./api/plugins/plugin-content-docs.md) +- [`@docusaurus/plugin-content-blog`](./api/plugins/plugin-content-blog.md) +- [`@docusaurus/plugin-content-pages`](./api/plugins/plugin-content-pages.md) +- [`@docusaurus/plugin-debug`](./api/plugins/plugin-debug.md) +- [`@docusaurus/plugin-google-analytics`](./api/plugins/plugin-google-analytics.md) +- [`@docusaurus/plugin-google-gtag`](./api/plugins/plugin-google-gtag.md) +- [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.md) -To specify plugin options individually, you can provide the necessary fields to certain plugins, i.e. `customCss` for `@docusaurus/theme-classic`, pass them in the preset field, like this: +The classic preset will relay each option entry to the respective plugin/theme. ```js title="docusaurus.config.js" module.exports = { @@ -278,13 +200,95 @@ module.exports = { }; ``` +### Installing presets {#installing-presets} + +A preset is usually an npm package, so you install them like other npm packages using npm. + +```bash npm2yarn +npm install --save @docusaurus/preset-classic +``` + +Then, add it in your site's `docusaurus.config.js`'s `presets` option: + +```js title="docusaurus.config.js" +module.exports = { + // ... + // highlight-next-line + presets: ['@docusaurus/preset-classic'], +}; +``` + +Preset paths can be relative to the config file: + +```js title="docusaurus.config.js" +module.exports = { + // ... + // highlight-next-line + presets: ['./src/presets/docusaurus-local-preset')], +}; +``` + +### Creating presets {#creating-presets} + +A preset is a function with the same shape as the [plugin constructor](./api/plugin-methods/README.md#plugin-constructor). It should return an object of `{ plugins: PluginConfig[], themes: PluginConfig[] }`, in the same as how they are accepted in the site config. For example, you can specify a preset that includes the following themes and plugins: + +```js title="src/presets/docusaurus-preset-multi-docs.js" +module.exports = function preset(context, opts = {}) { + return { + themes: [['docusaurus-theme-awesome', opts.theme]], + plugins: [ + // Using three docs plugins at the same time! + // Assigning a unique ID for each without asking the user to do it + ['@docusaurus/plugin-content-docs', {...opts.docs1, id: 'docs1'}], + ['@docusaurus/plugin-content-docs', {...opts.docs2, id: 'docs2'}], + ['@docusaurus/plugin-content-docs', {...opts.docs3, id: 'docs3'}], + ], + }; +}; +``` + +Then in your Docusaurus config, you may configure the preset: + +```js title="docusaurus.config.js" +module.exports = { + presets: [ + // highlight-start + [ + './src/presets/docusaurus-preset-multi-docs.js', + { + theme: {hello: 'world'}, + docs1: {path: '/docs'}, + docs2: {path: '/community'}, + docs3: {path: '/api'}, + }, + ], + // highlight-end + ], +}; +``` + +This is equivalent of doing: + +```js title="docusaurus.config.js" +module.exports = { + themes: [['docusaurus-theme-awesome', {hello: 'world'}]], + plugins: [ + ['@docusaurus/plugin-content-docs', {id: 'docs1', path: '/docs'}], + ['@docusaurus/plugin-content-docs', {id: 'docs2', path: '/community'}], + ['@docusaurus/plugin-content-docs', {id: 'docs3', path: '/api'}], + ], +}; +``` + +This is especially useful when some plugins and themes are intended to be used together. You can even link their options together, e.g. pass one option to multiple plugins. + ## Module shorthands {#module-shorthands} -Docusaurus supports shorthands for plugins, themes, and presets. When it sees a plugin / theme / preset name, it tries to load one of the following, in that order: +Docusaurus supports shorthands for plugins, themes, and presets. When it sees a plugin/theme/preset name, it tries to load one of the following, in that order: -- `[name]` -- `@docusaurus/[moduleType]-[name]` -- `docusaurus-[moduleType]-[name]`, +- `[name]` (like `content-docs`) +- `@docusaurus/[moduleType]-[name]` (like `@docusaurus/plugin-content-docs`) +- `docusaurus-[moduleType]-[name]` (like `docusaurus-plugin-content-docs`) where `moduleType` is one of `'preset'`, `'theme'`, `'plugin'`, depending on which field the module name is declared in. The first module name that's successfully found is loaded. @@ -304,10 +308,10 @@ If the name is scoped (beginning with `@`), the name is first split into scope a scope name ``` -If the name is not specified, `{scope}/docusaurus-{type}` is loaded. Otherwise, the following are attempted: +If there is no name (like `@jquery`), `[scope]/docusaurus-[moduleType]` (i.e. `@jquery/docusaurus-plugin`) is loaded. Otherwise, the following are attempted: -- `[scope]/[name]` -- `[scope]/docusaurus-[moduleType]-[name]` +- `[scope]/[name]` (like `@jquery/content-docs`) +- `[scope]/docusaurus-[moduleType]-[name]` (like `@jquery/docusaurus-plugin-content-docs`) Below are some examples, for a plugin registered in the `plugins` field. Note that unlike [ESLint](https://eslint.org/docs/user-guide/configuring/plugins#configuring-plugins) or [Babel](https://babeljs.io/docs/en/options#name-normalization) where a consistent naming convention for plugins is mandated, Docusaurus permits greater naming freedom, so the resolutions are not certain, but follows the priority defined above.