docs: editorial fixes (#6889)

website/docs/advanced/client.md

@@ -1,3 +1,7 @@
+---
+description: How the Docusaurus client is structured
+---
+
 # Client architecture
 
 ## Theme aliases {#theme-aliases}

website/docs/guides/markdown-features/markdown-features-assets.mdx

@@ -6,6 +6,8 @@ slug: /markdown-features/assets
 ---
 
 import BrowserWindow from '@site/src/components/BrowserWindow';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
 Sometimes you want to link to assets (e.g. docx files, images...) directly from Markdown files, and it is convenient to co-locate the asset next to the Markdown file using it.
 
@@ -24,12 +26,18 @@ Let's imagine the following file structure:
 
 You can display images in three different ways: Markdown syntax, CJS require, or ES imports syntax.
 
+<Tabs>
+<TabItem value="Markdown syntax">
+
 Display images using simple Markdown syntax:
 
 ```md
 ![Example banner](./assets/docusaurus-asset-example-banner.png)
 ```
 
+</TabItem>
+<TabItem value="CommonJS require">
+
 Display images using inline CommonJS `require` in JSX image tag:
 
 ```jsx
@@ -39,6 +47,9 @@ Display images using inline CommonJS `require` in JSX image tag:
 />
 ```
 
+</TabItem>
+<TabItem value="Import statement">
+
 Display images using ES `import` syntax and JSX image tag:
 
 ```jsx
@@ -47,7 +58,10 @@ import myImageUrl from './assets/docusaurus-asset-example-banner.png';
 <img src={myImageUrl} alt="Example banner" />;
 ```
 
-This results in displaying the image:
+</TabItem>
+</Tabs>
+
+All of the above result in displaying the image:
 
 <BrowserWindow>
 
@@ -63,7 +77,7 @@ If you are using [@docusaurus/plugin-ideal-image](../../api/plugins/plugin-ideal
 
 ## Files {#files}
 
-In the same way, you can link to existing assets by requiring them and using the returned url in videos, links, etc.
+In the same way, you can link to existing assets by `require`'ing them and using the returned URL in `video`s, `a` anchor links, etc.
 
 ```md
 # My Markdown page
@@ -89,7 +103,7 @@ or
 
 :::info markdown links are always file paths
 
-If you use the Markdown image or link syntax, all asset paths will be resolved as file paths by Docusaurus and automatically converted to `require()` calls. You don't need to use `require()` in Markdown unless you use the JSX syntax.
+If you use the Markdown image or link syntax, all asset paths will be resolved as file paths by Docusaurus and automatically converted to `require()` calls. You don't need to use `require()` in Markdown unless you use the JSX syntax, which you do have to handle yourself.
 
 :::
 

website/docs/guides/markdown-features/markdown-features-code-blocks.mdx

@@ -14,11 +14,13 @@ Code blocks within documentation are super-powered 💪.
 
 You can add a title to the code block by adding a `title` key after the language (leave a space between them).
 
+````md
 ```jsx title="/src/components/HelloCodeTitle.js"
 function HelloCodeTitle(props) {
   return <h1>Hello, {props.name}</h1>;
 }
 ```
+````
 
 <BrowserWindow>
 
@@ -34,9 +36,11 @@ function HelloCodeTitle(props) {
 
 Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for the specifications of MDX.
 
+````md
 ```js
 console.log('Every repo must come with a mascot.');
 ```
+````
 
 Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer).
 
@@ -127,6 +131,7 @@ You can refer to [Prism's official language definitions](https://github.com/Pris
 
 You can use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted.
 
+````md
 ```js
 function HighlightSomeText(highlight) {
   if (highlight) {
@@ -147,6 +152,7 @@ You can use comments with `highlight-next-line`, `highlight-start`, and `highlig
   return 'Nothing highlighted';
 }
 ```
+````
 
 ````mdx-code-block
 <BrowserWindow>
@@ -177,14 +183,14 @@ function HighlightMoreText(highlight) {
 
 Supported commenting syntax:
 
-| Language   | Syntax                   |
+| Style      | Syntax                   |
 | ---------- | ------------------------ |
-| JavaScript | `/* ... */` and `// ...` |
+| C-style    | `/* ... */` and `// ...` |
-| JSX        | `{/* ... */}`            |
+| JSX-style  | `{/* ... */}`            |
-| Python     | `# ...`                  |
+| Bash-style | `# ...`                  |
-| HTML       | `<!-- ... -->`           |
+| HTML-style | `<!-- ... -->`           |
 
-If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome.
+We will do our best to infer which set of comment styles to use based on the language, and default to allowing _all_ comment styles. If there's a comment style that is not currently supported, we are open to adding them! Pull requests welcome.
 
 To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your `src/css/custom.css` with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly.
 
@@ -207,6 +213,7 @@ To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class t
 
 You can also specify highlighted line ranges within the language meta string (leave a space after the language). To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the `parse-number-range` library and you can find [more syntax](https://www.npmjs.com/package/parse-numeric-range) on their project details.
 
+````md
 ```jsx {1,4-6,11}
 import React from 'react';
 
@@ -220,6 +227,7 @@ You can also specify highlighted line ranges within the language meta string (le
 
 export default MyComponent;
 ```
+````
 
 <BrowserWindow>
 
@@ -265,9 +273,7 @@ In the future, we may extend the magic comment system and let you define custom
 
 (Powered by [React Live](https://github.com/FormidableLabs/react-live))
 
-You can create an interactive coding editor with the `@docusaurus/theme-live-codeblock` plugin.
+You can create an interactive coding editor with the `@docusaurus/theme-live-codeblock` plugin. First, add the plugin to your package.
-
-First, add the plugin to your package.
 
 ```bash npm2yarn
 npm install --save @docusaurus/theme-live-codeblock
@@ -285,6 +291,7 @@ module.exports = {
 
 To use the plugin, create a code block with `live` attached to the language meta string.
 
+````md
 ```jsx live
 function Clock(props) {
   const [date, setDate] = useState(new Date());
@@ -307,6 +314,7 @@ To use the plugin, create a code block with `live` attached to the language meta
   );
 }
 ```
+````
 
 The code block will be rendered as an interactive editor. Changes to the code will reflect on the result panel live.
 
@@ -445,9 +453,9 @@ Syntax highlighting only works on plain strings. Docusaurus will not attempt to
 
 With MDX, you can easily create interactive components within your documentation, for example, to display code in multiple programming languages and switch between them using a tabs component.
 
-Instead of implementing a dedicated component for multi-language support code blocks, we've implemented a generic Tabs component in the classic theme so that you can use it for other non-code scenarios as well.
+Instead of implementing a dedicated component for multi-language support code blocks, we've implemented a general-purpose [`<Tabs>`](./markdown-features-tabs.mdx) component in the classic theme so that you can use it for other non-code scenarios as well.
 
-The following example is how you can have multi-language code tabs in your docs. Note that the empty lines above and below each language block are **intentional**. This is a current limitation of MDX: you have to leave empty lines around Markdown syntax for the MDX parser to know that it's Markdown syntax and not JSX.
+The following example is how you can have multi-language code tabs in your docs. Note that the empty lines above and below each language block are **intentional**. This is a [current limitation of MDX](./markdown-features-react.mdx#markdown-and-jsx-interoperability): you have to leave empty lines around Markdown syntax for the MDX parser to know that it's Markdown syntax and not JSX.
 
 ````jsx
 import Tabs from '@theme/Tabs';
@@ -467,7 +475,7 @@ function helloWorld() {
 
 ```py
 def hello_world():
-  print 'Hello, world!'
+  print("Hello, world!")
 ```
 
 </TabItem>
@@ -503,7 +511,7 @@ function helloWorld() {
 
 ```py
 def hello_world():
-  print 'Hello, world!'
+  print("Hello, world!")
 ```
 
 </TabItem>

website/docs/guides/markdown-features/markdown-features-head-metadata.mdx

@@ -7,9 +7,7 @@ slug: /markdown-features/head-metadata
 
 # Head Metadata
 
-Docusaurus automatically sets useful page metadata in `<html>`, `<head>` and `<body>` for you.
+Docusaurus automatically sets useful page metadata in `<html>`, `<head>` and `<body>` for you. It is possible to add extra metadata (or override existing ones) with the `<head>` tag in Markdown files:
-
-It is possible to add extra metadata (or override existing ones) by using the `<head>` tag in Markdown files:
 
 ```md title="markdown-features-head-metadata.mdx"
 ---
@@ -46,22 +44,18 @@ My text
 
 :::tip
 
-This `<head>` declaration has been added to the current Markdown doc, as a demo.
+This `<head>` declaration has been added to the current Markdown doc as a demo. Open your browser DevTools and check how this page's metadata has been affected.
-
-Open your browser DevTools and check how this page's metadata has been affected.
 
 :::
 
-:::tip
+:::tip You don't need this for regular SEO
 
-**You don't always need this for typical SEO needs.** Content plugins (e.g. docs and blog) provide front matter options like `description`, `keywords`, and `image`, which will be automatically applied to both `description` and `og:description`, while you would have to manually declare two metadata tags when using the `<head>` tag.
+Content plugins (e.g. docs and blog) provide front matter options like `description`, `keywords`, and `image`, which will be automatically applied to both `description` and `og:description`, while you would have to manually declare two metadata tags when using the `<head>` tag.
 
 :::
 
 :::note
 
-This feature is built on top of the Docusaurus [`<Head>`](./../../docusaurus-core.md#head) component.
+This feature is built on top of the Docusaurus [`<Head>`](./../../docusaurus-core.md#head) component. Refer to [react-helmet](https://github.com/nfl/react-helmet) for exhaustive documentation.
-
-Refer to [react-helmet](https://github.com/nfl/react-helmet) for exhaustive documentation.
 
 :::

website/docs/guides/markdown-features/markdown-features-inline-toc.mdx

@@ -7,15 +7,11 @@ slug: /markdown-features/inline-toc
 
 import BrowserWindow from '@site/src/components/BrowserWindow';
 
-Each Markdown document displays a tab of content on the top-right corner.
+Each Markdown document displays a table of contents on the top-right corner. But it is also possible to display an inline table of contents directly inside a markdown document, thanks to MDX.
-
-But it is also possible to display an inline table of contents directly inside a markdown document, thanks to MDX.
 
 ## Full table of contents {#full-table-of-contents}
 
-The `toc` variable is available in any MDX document and contains all the headings of an MDX document.
+The `toc` variable is available in any MDX document and contains all the headings of an MDX document. By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel` for individual `TOCInline` components.
-
-By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel`.
 
 ```jsx
 import TOCInline from '@theme/TOCInline';
@@ -27,9 +23,7 @@ import TOCInline from '@theme/TOCInline';
 import TOCInline from '@theme/TOCInline';
 
 <BrowserWindow>
-
 <TOCInline toc={toc} />
-
 </BrowserWindow>
 ```
 
@@ -53,12 +47,19 @@ import TOCInline from '@theme/TOCInline';
 <TOCInline
   // Only show h2 and h4 headings
   toc={toc.filter((node) => node.level === 2 || node.level === 4)}
+  minHeadingLevel={2}
+  // Show h4 headings in addition to the default h2 and h3 headings
+  maxHeadingLevel={4}
 />;
 ```
 
 ```mdx-code-block
 <BrowserWindow>
-<TOCInline toc={toc.filter((node) => node.level === 2 || node.level === 4)} />
+<TOCInline
+  toc={toc.filter((node) => node.level === 2 || node.level === 4)}
+  minHeadingLevel={2}
+  maxHeadingLevel={4}
+/>
 </BrowserWindow>
 ```
 

website/docs/guides/markdown-features/markdown-features-math-equations.mdx

@@ -17,9 +17,10 @@ Please read [KaTeX](https://katex.org) documentation for more details.
 
 Write inline math equations by wrapping LaTeX equations between `$`:
 
-```mdx
+```latex
-Let $f\colon[a,b] \to \R$ be Riemann integrable. Let $F\colon[a,b]\to\R$ be $F(x)=
+Let $f\colon[a,b]\to\R$ be Riemann integrable. Let $F\colon[a,b]\to\R$ be
-\int_{a}^{x} f(t)\,dt$. Then $$F$$ is continuous, and at all $x$ such that $f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$.
+$F(x)=\int_{a}^{x} f(t)\,dt$. Then $F$ is continuous, and at all $x$ such that
+$f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$.
 ```
 
 <BrowserWindow>
@@ -33,7 +34,7 @@ Let $f\colon[a,b] \to \R$ be Riemann integrable. Let $F\colon[a,b]\to\R$ be $F(x
 
 For equation block or display mode, use line breaks and `$$`:
 
-```mdx
+```latex
 $$
 I = \int_0^{2\pi} \sin(x)\,dx
 $$

website/docs/guides/markdown-features/markdown-features-tabs.mdx

@@ -12,7 +12,7 @@ import TabItem from '@theme/TabItem';
 import styles from './markdown-features-tabs-styles.module.css';
 ```
 
-Docusaurus provides `<Tabs>` components that you can use thanks to [MDX](./markdown-features-react.mdx):
+Docusaurus provides the `<Tabs>` component that you can use in Markdown thanks to [MDX](./markdown-features-react.mdx):
 
 <!-- prettier-ignore-start -->
 ```jsx

website/docs/guides/whats-next.md

@@ -6,8 +6,8 @@ Congratulations! You have understood most core features of Docusaurus now. You h
 - [Used the docs plugin](./docs/docs-introduction.md) to create documentation pages. This includes [configuring the sidebar](./docs/sidebar/index.md), and even [versioning](./docs/versioning.md)
 - [Used the blog plugin](../blog.mdx) to create a fully featured blog
 - Tried your hands on [a range of Markdown features](./markdown-features/markdown-features-intro.mdx), which are useful for all content plugins
-- [Used stylesheets](../styling-layout.md) to customize your site's appearance
+- [Used stylesheets](../styling-layout.md) or [swizzling](../swizzling.md) to customize your site's appearance
-- [Put images and other assets](../static-assets.md) in your pages
+- [Included images and other assets](../static-assets.md) in your pages
 - [Added search](../search.md) to your site
 - Understood how [browser support](../browser-support.md) and [SEO](../seo.md) are done through standard Docusaurus APIs
 - Learned about how [individual plugins](../using-plugins.md) are installed and configured

website/docs/installation.md

@@ -41,7 +41,7 @@ If you do not specify `name` or `template`, it will prompt you for them.
 
 We recommend the `classic` template so that you can get started quickly, and it contains features found in Docusaurus 1. The `classic` template contains `@docusaurus/preset-classic` which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus.
 
-The `template` also accepts a git repo URL or a local file path, with the latter evaluated relative to the current working directory. The repo/folder content will be copied to the site directory. If it's a git repository, you can also specify a cloning strategy. Run `npx create-docusaurus@latest --help` for more information.
+The `template` also accepts a git repo URL or a local file path, with the latter evaluated relative to the current working directory. The repo/folder content will be copied to the site directory. If it's a git repository, you can also specify a cloning strategy.
 
 You can also use the template's TypeScript variant by passing the `--typescript` flag.
 
@@ -66,24 +66,24 @@ You can also initialize a new project using your preferred project manager:
 
 ````mdx-code-block
 <Tabs>
-<TabItem value="npm v6+">
+<TabItem value="npm">
 
 ```bash
-npm init docusaurus website classic
+npm init docusaurus
 ```
 
 </TabItem>
 <TabItem value="yarn">
 
 ```bash
-yarn create docusaurus website classic
+yarn create docusaurus
 ```
 
 </TabItem>
 <TabItem value="pnpm">
 
 ```bash
-pnpm create docusaurus website classic
+pnpm create docusaurus
 ```
 
 </TabItem>
@@ -99,11 +99,7 @@ Docusaurus makes best efforts to select a package manager to install dependencie
 npx create-docusaurus@latest my-website classic --package-manager yarn
 ```
 
-If you want to skip installing dependencies, use the `--skip-install` option.
+Run `npx create-docusaurus@latest --help` for more information about all available flags.
-
-```bash
-npx create-docusaurus@latest my-website classic --skip-install
-```
 
 ## Project structure {#project-structure}
 
@@ -137,10 +133,10 @@ my-website
 
 ### Project structure rundown {#project-structure-rundown}
 
-- `/blog/` - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.mdx)
+- `/blog/` - Contains the blog Markdown files. You can delete the directory if you've disabled the blog plugin, or you can change its name after setting the `path` option. More details can be found in the [blog guide](blog.mdx)
-- `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](./guides/docs/docs-markdown-features.mdx)
+- `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. You can delete the directory if you've disabled the docs plugin, or you can change its name after setting the `path` option. More details can be found in the [docs guide](./guides/docs/docs-markdown-features.mdx)
-- `/src/` - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files in here but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing
+- `/src/` - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files here, but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing
-  - `/src/pages` - Any files within this directory will be converted into a website page. More details can be found in the [pages guide](guides/creating-pages.md)
+  - `/src/pages` - Any JSX/TSX/MDX file within this directory will be converted into a website page. More details can be found in the [pages guide](guides/creating-pages.md)
 - `/static/` - Static directory. Any contents inside here will be copied into the root of the final `build` directory
 - `/docusaurus.config.js` - A config file containing the site configuration. This is the equivalent of `siteConfig.js` in Docusaurus v1
 - `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them

website/docs/styling-layout.md

@@ -20,7 +20,7 @@ There are a few approaches/frameworks which will work, depending on your prefere
 
 This is the most traditional way of styling that most developers (including non-front-end developers) would be familiar with. It works fine for small websites that do not have much customization.
 
-If you're using `@docusaurus/preset-classic`, you can create your own CSS files (e.g. `/src/css/custom.css`) and import them globally by passing them as an option into the preset.
+If you're using `@docusaurus/preset-classic`, you can create your own CSS files (e.g. `/src/css/custom.css`) and import them globally by passing them as an option of the classic theme.
 
 ```js title="docusaurus.config.js"
 module.exports = {
@@ -114,7 +114,7 @@ Alternatively, use the following tool to generate the different shades for your
 
 ### Dark Mode {#dark-mode}
 
-In light mode, the `<html>` element has a `data-theme="light"` attribute; and in dark mode, it's `data-theme="dark"`. Therefore, you can scope your CSS to dark-mode-only by targeting `html` with a specific attribute.
+In light mode, the `<html>` element has a `data-theme="light"` attribute; in dark mode, it's `data-theme="dark"`. Therefore, you can scope your CSS to dark-mode-only by targeting `html` with a specific attribute.
 
 ```css
 /* Overriding root Infima variables */
@@ -145,7 +145,7 @@ Docusaurus uses `996px` as the cutoff between mobile screen width and desktop. I
 
 ## CSS modules {#css-modules}
 
-To style your components using [CSS Modules](https://github.com/css-modules/css-modules), name your stylesheet files with the `.module.css` suffix (e.g. `welcome.module.css`). webpack will load such CSS files as CSS modules and you have to reference the class names from the imported CSS module (as opposed to using plain strings). This is similar to the convention used in [Create React App](https://facebook.github.io/create-react-app/docs/adding-a-css-modules-stylesheet).
+To style your components using [CSS Modules](https://github.com/css-modules/css-modules), name your stylesheet files with the `.module.css` suffix (e.g. `welcome.module.css`). Webpack will load such CSS files as CSS modules and you have to reference the class names as properties of the imported CSS module (as opposed to using plain strings). This is similar to the convention used in [Create React App](https://facebook.github.io/create-react-app/docs/adding-a-css-modules-stylesheet).
 
 ```css title="styles.module.css"
 .main {
@@ -180,7 +180,7 @@ The class names will be processed by webpack into a globally unique class name d
 
 :::caution
 
-This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640).
+CSS-in-JS support is a work in progress, so libs like MUI may have display quirks. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640).
 
 :::
 

website/docusaurus.config.js

@@ -353,7 +353,7 @@ const config = {
         // and the YAML front matter is highlighted correctly.
         // TODO after we have forked prism-react-renderer, we should tweak the
         // import order and fix it there
-        additionalLanguages: ['java', 'markdown'],
+        additionalLanguages: ['java', 'markdown', 'latex'],
       },
       image: 'img/docusaurus-soc.png',
       // metadata: [{name: 'twitter:card', content: 'summary'}],