@@ -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.
-
-First, add the plugin to your package.
+You can create an interactive coding editor with the `@docusaurus/theme-live-codeblock` plugin. First, add the plugin to your package.
```bash npm2yarn
npm install --save @docusaurus/theme-live-codeblock
@@ -285,28 +291,30 @@ module.exports = {
To use the plugin, create a code block with `live` attached to the language meta string.
- ```jsx live
- function Clock(props) {
- const [date, setDate] = useState(new Date());
- useEffect(() => {
- var timerID = setInterval(() => tick(), 1000);
+````md
+```jsx live
+function Clock(props) {
+ const [date, setDate] = useState(new Date());
+ useEffect(() => {
+ var timerID = setInterval(() => tick(), 1000);
- return function cleanup() {
- clearInterval(timerID);
- };
- });
+ return function cleanup() {
+ clearInterval(timerID);
+ };
+ });
- function tick() {
- setDate(new Date());
- }
+ function tick() {
+ setDate(new Date());
+ }
- return (
-
-
It is {date.toLocaleTimeString()}.
-
- );
- }
- ```
+ return (
+
+
It is {date.toLocaleTimeString()}.
+
+ );
+}
+```
+````
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 [``](./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!")
```
@@ -503,7 +511,7 @@ function helloWorld() {
```py
def hello_world():
- print 'Hello, world!'
+ print("Hello, world!")
```
diff --git a/website/docs/guides/markdown-features/markdown-features-head-metadata.mdx b/website/docs/guides/markdown-features/markdown-features-head-metadata.mdx
index fa987eb1fe..1a2c04095c 100644
--- a/website/docs/guides/markdown-features/markdown-features-head-metadata.mdx
+++ b/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 ``, `` and `` for you.
-
-It is possible to add extra metadata (or override existing ones) by using the `` tag in Markdown files:
+Docusaurus automatically sets useful page metadata in ``, `` and `` for you. It is possible to add extra metadata (or override existing ones) with the `` tag in Markdown files:
```md title="markdown-features-head-metadata.mdx"
---
@@ -46,22 +44,18 @@ My text
:::tip
-This `` 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.
+This `` 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.
:::
-:::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 `` 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 `` tag.
:::
:::note
-This feature is built on top of the Docusaurus [``](./../../docusaurus-core.md#head) component.
-
-Refer to [react-helmet](https://github.com/nfl/react-helmet) for exhaustive documentation.
+This feature is built on top of the Docusaurus [``](./../../docusaurus-core.md#head) component. Refer to [react-helmet](https://github.com/nfl/react-helmet) for exhaustive documentation.
:::
diff --git a/website/docs/guides/markdown-features/markdown-features-inline-toc.mdx b/website/docs/guides/markdown-features/markdown-features-inline-toc.mdx
index 4a48251ac4..8369a13318 100644
--- a/website/docs/guides/markdown-features/markdown-features-inline-toc.mdx
+++ b/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.
-
-But it is also possible to display an inline table of contents directly inside a markdown document, thanks to MDX.
+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.
## 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.
-
-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`.
+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.
```jsx
import TOCInline from '@theme/TOCInline';
@@ -27,9 +23,7 @@ import TOCInline from '@theme/TOCInline';
import TOCInline from '@theme/TOCInline';
-
-
```
@@ -53,12 +47,19 @@ import TOCInline from '@theme/TOCInline';
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
- node.level === 2 || node.level === 4)} />
+ node.level === 2 || node.level === 4)}
+ minHeadingLevel={2}
+ maxHeadingLevel={4}
+/>
```
diff --git a/website/docs/guides/markdown-features/markdown-features-math-equations.mdx b/website/docs/guides/markdown-features/markdown-features-math-equations.mdx
index d785f3d027..e3281d6fd6 100644
--- a/website/docs/guides/markdown-features/markdown-features-math-equations.mdx
+++ b/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
-Let $f\colon[a,b] \to \R$ be Riemann integrable. Let $F\colon[a,b]\to\R$ be $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)$.
+```latex
+Let $f\colon[a,b]\to\R$ be Riemann integrable. Let $F\colon[a,b]\to\R$ be
+$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)$.
```
@@ -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
$$
diff --git a/website/docs/guides/markdown-features/markdown-features-tabs.mdx b/website/docs/guides/markdown-features/markdown-features-tabs.mdx
index 55ce040ead..062a9abe54 100644
--- a/website/docs/guides/markdown-features/markdown-features-tabs.mdx
+++ b/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 `` components that you can use thanks to [MDX](./markdown-features-react.mdx):
+Docusaurus provides the `` component that you can use in Markdown thanks to [MDX](./markdown-features-react.mdx):
```jsx
diff --git a/website/docs/guides/whats-next.md b/website/docs/guides/whats-next.md
index 17c322a59b..7782f58eeb 100644
--- a/website/docs/guides/whats-next.md
+++ b/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
-- [Put images and other assets](../static-assets.md) in your pages
+- [Used stylesheets](../styling-layout.md) or [swizzling](../swizzling.md) to customize your site's appearance
+- [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
diff --git a/website/docs/installation.md b/website/docs/installation.md
index 0a79f9b3f7..ceee8a5df6 100644
--- a/website/docs/installation.md
+++ b/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
-
+
```bash
-npm init docusaurus website classic
+npm init docusaurus
```
```bash
-yarn create docusaurus website classic
+yarn create docusaurus
```
```bash
-pnpm create docusaurus website classic
+pnpm create docusaurus
```
@@ -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.
-
-```bash
-npx create-docusaurus@latest my-website classic --skip-install
-```
+Run `npx create-docusaurus@latest --help` for more information about all available flags.
## 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)
-- `/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)
-- `/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/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)
+- `/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`. 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 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 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
diff --git a/website/docs/styling-layout.md b/website/docs/styling-layout.md
index 1431b1e158..b6cba21b2e 100644
--- a/website/docs/styling-layout.md
+++ b/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 `` 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 `` 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).
:::
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index c87b30b9c2..437a83bbb4 100644
--- a/website/docusaurus.config.js
+++ b/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'}],