3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-21 04:57:05 +02:00
Code Issues Projects Releases Packages Wiki Activity

fix(cli): allow passing a list of file names to write-heading-ids (#6500)

Browse source
This commit is contained in:
Joshua Chen 2022-01-29 12:21:15 +08:00 • committed by GitHub
parent 9af7aae9e2
commit c1e3801ee7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
28 changed files with 74 additions and 74 deletions
Download patch file Download diff file Expand all files Collapse all files

2
packages/docusaurus/bin/docusaurus.js
View file

@ -208,7 +208,7 @@ cli
); );
cli cli
.command('write-heading-ids [contentDir] [files]') .command('write-heading-ids [siteDir] [files...]')
.description('Generate heading ids in Markdown content.') .description('Generate heading ids in Markdown content.')
.option( .option(
'--maintain-case', '--maintain-case',

4
packages/docusaurus/src/commands/writeHeadingIds.ts
View file

@ -133,11 +133,11 @@ async function getPathsToWatch(siteDir: string): Promise<string[]> {
export default async function writeHeadingIds( export default async function writeHeadingIds(
siteDir: string, siteDir: string,
files?: string, files?: string[],
options?: Options, options?: Options,
): Promise<void> { ): Promise<void> {
const markdownFiles = await safeGlobby( const markdownFiles = await safeGlobby(
files ? [files] : await getPathsToWatch(siteDir), files ?? (await getPathsToWatch(siteDir)),
{ {
expandDirectories: ['**/*.{md,mdx}'], expandDirectories: ['**/*.{md,mdx}'],
}, },

4
website/docs/advanced/plugins.md
View file

@ -80,11 +80,11 @@ Plugins come as several types:
You can access them on the client side with `useDocusaurusContext().siteMetadata.pluginVersions`. You can access them on the client side with `useDocusaurusContext().siteMetadata.pluginVersions`.
## Plugin design ## Plugin design {#plugin-design}
Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but is not limited to) extending the webpack config, modifying the data loaded, and creating new components to be used in a page. Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but is not limited to) extending the webpack config, modifying the data loaded, and creating new components to be used in a page.
### Theme design ### Theme design {#theme-design}
When plugins have loaded their content, the data is made available to the client side through actions like [`createData` + `addRoute`](../api/plugin-methods/lifecycle-apis.md#addRoute) or [`setGlobalData`](../api/plugin-methods/lifecycle-apis.md#setGlobalData). This data has to be _serialized_ to plain strings, because [plugins and themes run in different environments](./architecture.md). Once the data arrives on the client side, the rest becomes familiar to React developers: data is passed along components, components are bundled with Webpack, and rendered to the window through `ReactDOM.render`... When plugins have loaded their content, the data is made available to the client side through actions like [`createData` + `addRoute`](../api/plugin-methods/lifecycle-apis.md#addRoute) or [`setGlobalData`](../api/plugin-methods/lifecycle-apis.md#setGlobalData). This data has to be _serialized_ to plain strings, because [plugins and themes run in different environments](./architecture.md). Once the data arrives on the client side, the rest becomes familiar to React developers: data is passed along components, components are bundled with Webpack, and rendered to the window through `ReactDOM.render`...

16
website/docs/advanced/routing.md
View file

@ -13,7 +13,7 @@ import BrowserWindow from '@site/src/components/BrowserWindow';
Docusaurus' routing system follows single-page application conventions: one route, one component. In this section, we will begin by talking about routing within the three content plugins (docs, blog, and pages), and then go beyond to talk about the underlying routing system. Docusaurus' routing system follows single-page application conventions: one route, one component. In this section, we will begin by talking about routing within the three content plugins (docs, blog, and pages), and then go beyond to talk about the underlying routing system.
## Routing in content plugins ## Routing in content plugins {#routing-in-content-plugins}
Every content plugin provides a `routeBasePath` option. It defines where the plugins append their routes to. By default, the docs plugin puts its routes under `/docs`; the blog plugin, `/blog`; and the pages plugin, `/`. You can think about the route structure like this: Every content plugin provides a `routeBasePath` option. It defines where the plugins append their routes to. By default, the docs plugin puts its routes under `/docs`; the blog plugin, `/blog`; and the pages plugin, `/`. You can think about the route structure like this:
@ -25,13 +25,13 @@ Changing `routeBasePath` can effectively alter your site's route structure. For
Next, let's look at how the three plugins structure their own "boxes of subroutes". Next, let's look at how the three plugins structure their own "boxes of subroutes".
### Pages routing ### Pages routing {#pages-routing}
Pages routing are straightforward: the file paths directly map to URLs, without any other way to customize. See the [pages docs](../guides/creating-pages.md#routing) for more information. Pages routing are straightforward: the file paths directly map to URLs, without any other way to customize. See the [pages docs](../guides/creating-pages.md#routing) for more information.
The component used for Markdown pages is `@theme/MDXPage`. React pages are directly used as the route's component. The component used for Markdown pages is `@theme/MDXPage`. React pages are directly used as the route's component.
### Blog routing ### Blog routing {#blog-routing}
The blog creates the following routes: The blog creates the following routes:
@ -52,7 +52,7 @@ The blog creates the following routes:
- The route is customizable through the `archiveBasePath` option. - The route is customizable through the `archiveBasePath` option.
- The component is `@theme/BlogArchivePage`. - The component is `@theme/BlogArchivePage`.
### Docs routing ### Docs routing {#docs-routing}
The docs is the only plugin that creates **nested routes**. At the top, it registers [**version paths**](../guides/docs/versioning.md): `/`, `/next`, `/2.0.0-beta.13`... which provide the version context, including the layout and sidebar. This ensures that when switching between individual docs, the sidebar's state is preserved, and that you can switch between versions through the navbar dropdown while staying on the same doc. The component used is `@theme/DocPage`. The docs is the only plugin that creates **nested routes**. At the top, it registers [**version paths**](../guides/docs/versioning.md): `/`, `/next`, `/2.0.0-beta.13`... which provide the version context, including the layout and sidebar. This ensures that when switching between individual docs, the sidebar's state is preserved, and that you can switch between versions through the navbar dropdown while staying on the same doc. The component used is `@theme/DocPage`.
@ -69,7 +69,7 @@ The individual docs are rendered in the remaining space after the navbar, footer
The doc's `slug` front matter customizes the last part of the route, but the base route is always defined by the plugin's `routeBasePath` and the version's `path`. The doc's `slug` front matter customizes the last part of the route, but the base route is always defined by the plugin's `routeBasePath` and the version's `path`.
### File paths and URL paths ### File paths and URL paths {#file-paths-and-url-paths}
Throughout the documentation, we always try to be unambiguous about whether we are talking about file paths or URL paths. Content plugins usually map file paths directly to URL paths, for example, `./docs/advanced/routing.md` will become `/docs/advanced/routing`. However, with `slug`, you can make URLs totally decoupled from the file structure. Throughout the documentation, we always try to be unambiguous about whether we are talking about file paths or URL paths. Content plugins usually map file paths directly to URL paths, for example, `./docs/advanced/routing.md` will become `/docs/advanced/routing`. However, with `slug`, you can make URLs totally decoupled from the file structure.
@ -128,7 +128,7 @@ The following directory structure may help you visualize this file -> URL mappin
So much about content plugins. Let's take one step back and talk about how routing works in a Docusaurus app in general. So much about content plugins. Let's take one step back and talk about how routing works in a Docusaurus app in general.
## Routes become HTML files ## Routes become HTML files {#routes-become-html-files}
Because Docusaurus is a server-side rendering framework, all routes generated will be server-side rendered into static HTML files. If you are familiar with the behavior of HTTP servers like [Apache2](https://httpd.apache.org/docs/trunk/getting-started.html), you will understand how this is done: when the browser sends a request to the route `/docs/advanced/routing`, the server interprets that as request for the HTML file `/docs/advanced/routing/index.html`, and returns that. Because Docusaurus is a server-side rendering framework, all routes generated will be server-side rendered into static HTML files. If you are familiar with the behavior of HTTP servers like [Apache2](https://httpd.apache.org/docs/trunk/getting-started.html), you will understand how this is done: when the browser sends a request to the route `/docs/advanced/routing`, the server interprets that as request for the HTML file `/docs/advanced/routing/index.html`, and returns that.
@ -202,7 +202,7 @@ For example, the emitted HTML would contain links like `<link rel="preload" href
Localized sites have the locale as part of the base URL as well. For example, `https://docusaurus.io/zh-CN/docs/advanced/routing/` has base URL `/zh-CN/`. Localized sites have the locale as part of the base URL as well. For example, `https://docusaurus.io/zh-CN/docs/advanced/routing/` has base URL `/zh-CN/`.
## Generating and accessing routes ## Generating and accessing routes {#generating-and-accessing-routes}
The `addRoute` lifecycle action is used to generate routes. It registers a piece of route config to the route tree, giving a route, a component, and props that the component needs. The props and the component are both provided as paths for the bundler to `require`, because as explained in the [architecture overview](architecture.md), server and client only communicate through temp files. The `addRoute` lifecycle action is used to generate routes. It registers a piece of route config to the route tree, giving a route, a component, and props that the component needs. The props and the component are both provided as paths for the bundler to `require`, because as explained in the [architecture overview](architecture.md), server and client only communicate through temp files.
@ -244,7 +244,7 @@ export function PageRoute() {
</BrowserWindow> </BrowserWindow>
``` ```
## Escaping from SPA redirects ## Escaping from SPA redirects {#escaping-from-spa-redirects}
Docusaurus builds a [single-page application](https://developer.mozilla.org/en-US/docs/Glossary/SPA), where route transitions are done through the `history.push()` method of React router. This operation is done on the client side. However, the prerequisite for a route transition to happen this way is that the target URL is known to our router. Otherwise, the router catches this path and displays a 404 page instead. Docusaurus builds a [single-page application](https://developer.mozilla.org/en-US/docs/Glossary/SPA), where route transitions are done through the `history.push()` method of React router. This operation is done on the client side. However, the prerequisite for a route transition to happen this way is that the target URL is known to our router. Otherwise, the router catches this path and displays a 404 page instead.

12
website/docs/advanced/ssg.md
View file

@ -92,7 +92,7 @@ export default function expensiveComp() {
</Tabs> </Tabs>
</details> </details>
## Understanding SSR ## Understanding SSR {#understanding-ssr}
React is not just a dynamic UI runtime—it's also a templating engine. Because Docusaurus sites mostly contain static contents, it should be able to work without any JavaScript (which React runs in), but only plain HTML/CSS. And that's what server-side rendering offers: statically rendering your React code into HTML, without any dynamic content. An HTML file has no concept of client state (it's purely markup), hence it shouldn't rely on browser APIs. React is not just a dynamic UI runtime—it's also a templating engine. Because Docusaurus sites mostly contain static contents, it should be able to work without any JavaScript (which React runs in), but only plain HTML/CSS. And that's what server-side rendering offers: statically rendering your React code into HTML, without any dynamic content. An HTML file has no concept of client state (it's purely markup), hence it shouldn't rely on browser APIs.
@ -100,7 +100,7 @@ These HTML files are the first to arrive at the user's browser screen when a URL
In CSR-only apps, all DOM elements are generated on client side with React, and the HTML file only ever contains one root element for React to mount DOM to; in SSR, React is already facing a fully built HTML page, and it only needs to correlate the DOM elements with the virtual DOM in its model. This step is called "hydration". After React has hydrated the static markup, the app starts to work as any normal React app. In CSR-only apps, all DOM elements are generated on client side with React, and the HTML file only ever contains one root element for React to mount DOM to; in SSR, React is already facing a fully built HTML page, and it only needs to correlate the DOM elements with the virtual DOM in its model. This step is called "hydration". After React has hydrated the static markup, the app starts to work as any normal React app.
## Escape hatches ## Escape hatches {#escape-hatches}
If you want to render any dynamic content on your screen that relies on the browser API to be functional at all, for example: If you want to render any dynamic content on your screen that relies on the browser API to be functional at all, for example:
@ -122,7 +122,7 @@ You can read more about this pitfall in [The Perils of Rehydration](https://www.
We provide several more reliable ways to escape SSR. We provide several more reliable ways to escape SSR.
### `<BrowserOnly>` ### `<BrowserOnly>` {#browseronly}
If you need to render some component in browser only (for example, because the component relies on browser specifics to be functional at all), one common approach is to wrap your component with [`<BrowserOnly>`](../docusaurus-core.md#browseronly) to make sure it's invisible during SSR and only rendered in CSR. If you need to render some component in browser only (for example, because the component relies on browser specifics to be functional at all), one common approach is to wrap your component with [`<BrowserOnly>`](../docusaurus-core.md#browseronly) to make sure it's invisible during SSR and only rendered in CSR.
@ -163,7 +163,7 @@ function MyComponent() {
While you may expect that `BrowserOnly` hides away the children during server-side rendering, it actually can't. When the React renderer tries to render this JSX tree, it does see the `{window.location.href}` variable as a node of this tree and tries to render it, although it's actually not used! Using a function ensures that we only let the renderer see the browser-only component when it's needed. While you may expect that `BrowserOnly` hides away the children during server-side rendering, it actually can't. When the React renderer tries to render this JSX tree, it does see the `{window.location.href}` variable as a node of this tree and tries to render it, although it's actually not used! Using a function ensures that we only let the renderer see the browser-only component when it's needed.
### `useIsBrowser` ### `useIsBrowser` {#useisbrowser}
You can also use the `useIsBrowser()` hook to test if the component is currently in a browser environment. It returns `false` in SSR and `true` is CSR, after first client render. Use this hook if you only need to perform certain conditional operations on client-side, but not render an entirely different UI. You can also use the `useIsBrowser()` hook to test if the component is currently in a browser environment. It returns `false` in SSR and `true` is CSR, after first client render. Use this hook if you only need to perform certain conditional operations on client-side, but not render an entirely different UI.
@ -177,7 +177,7 @@ function MyComponent() {
} }
``` ```
### `useEffect` ### `useEffect` {#useeffect}
Lastly, you can put your logic in `useEffect()` to delay its execution until after first CSR. This is most appropriate if you are only performing side-effects but don't _get_ data from the client state. Lastly, you can put your logic in `useEffect()` to delay its execution until after first CSR. This is most appropriate if you are only performing side-effects but don't _get_ data from the client state.
@ -191,7 +191,7 @@ function MyComponent() {
} }
``` ```
### `ExecutionEnvironment` ### `ExecutionEnvironment` {#executionenvironment}
The [`ExecutionEnvironment`](../docusaurus-core.md#executionenvironment) namespace contains several values, and `canUseDOM` is an effective way to detect browser environment. The [`ExecutionEnvironment`](../docusaurus-core.md#executionenvironment) namespace contains several values, and `canUseDOM` is an effective way to detect browser environment.

10
website/docs/advanced/swizzling.md
View file

@ -12,7 +12,7 @@ This section is similar to [Styling and Layout](../styling-layout.md), but this
We know you are busy, so we will start with the "how" before going into the "why". We know you are busy, so we will start with the "how" before going into the "why".
## Swizzling ## Swizzling {#swizzling}
```mdx-code-block ```mdx-code-block
import SwizzleWarning from "../_partials/swizzleWarning.mdx" import SwizzleWarning from "../_partials/swizzleWarning.mdx"
@ -22,7 +22,7 @@ import SwizzleWarning from "../_partials/swizzleWarning.mdx"
Docusaurus Themes' components are designed to be replaceable. The replacing is called "swizzle". In Objective C, method swizzling is the process of changing the implementation of an existing selector (method). **In the context of a website, component swizzling means providing an alternative component that takes precedence over the component provided by the theme.** (To gain a deeper understanding of this, you have to understand [how theme components are resolved](#theme-aliases)). To help you get started, we created a command called `docusaurus swizzle`. Docusaurus Themes' components are designed to be replaceable. The replacing is called "swizzle". In Objective C, method swizzling is the process of changing the implementation of an existing selector (method). **In the context of a website, component swizzling means providing an alternative component that takes precedence over the component provided by the theme.** (To gain a deeper understanding of this, you have to understand [how theme components are resolved](#theme-aliases)). To help you get started, we created a command called `docusaurus swizzle`.
### Ejecting theme components ### Ejecting theme components {#ejecting-theme-components}
To eject a component provided by the theme, run the following command in your doc site: To eject a component provided by the theme, run the following command in your doc site:
@ -76,7 +76,7 @@ export default function Footer(props) {
Should you be wondering why we have to use `'@theme-original/Footer'` instead of `'@theme/Footer'`, a short explanation is that once you have the swizzled component, the `'@theme/Footer'` alias will now point to your swizzled component, and thus cause a self-import. For a more in-depth explanation, see [theme aliases](#theme-aliases). Should you be wondering why we have to use `'@theme-original/Footer'` instead of `'@theme/Footer'`, a short explanation is that once you have the swizzled component, the `'@theme/Footer'` alias will now point to your swizzled component, and thus cause a self-import. For a more in-depth explanation, see [theme aliases](#theme-aliases).
## Which component should I swizzle? ## Which component should I swizzle? {#which-component-should-i-swizzle}
Currently, `theme-classic` has about 100 components[^source]! If you want to customize a part of your site's layout, which component should you choose? Currently, `theme-classic` has about 100 components[^source]! If you want to customize a part of your site's layout, which component should you choose?
@ -110,7 +110,7 @@ Use this component to render React Context providers and global stateful logic.
::: :::
## Do I need to swizzle? ## Do I need to swizzle? {#do-i-need-to-swizzle}
Swizzling ultimately means you have to maintain part of the code directly used to build your site, and you have to interact with Docusaurus internal APIs. If you can, think about the following alternatives when customizing your site: Swizzling ultimately means you have to maintain part of the code directly used to build your site, and you have to interact with Docusaurus internal APIs. If you can, think about the following alternatives when customizing your site:
@ -118,7 +118,7 @@ Swizzling ultimately means you have to maintain part of the code directly used t
2. **Use translations.** It may sound surprising, but translations are ultimately just a way to customize the text labels. For example, if your site's default language is `en`, you can still run `yarn write-translations -l en` and edit the `code.json` emitted. Refer to [i18n tutorial](../i18n/i18n-tutorial.md) for more details. 2. **Use translations.** It may sound surprising, but translations are ultimately just a way to customize the text labels. For example, if your site's default language is `en`, you can still run `yarn write-translations -l en` and edit the `code.json` emitted. Refer to [i18n tutorial](../i18n/i18n-tutorial.md) for more details.
3. **The smaller, the better.** If swizzling is inevitable, prefer to swizzle only the relevant part and maintain as little code on your own as possible. Swizzling a small component often means less risk of breaking during upgrade. [Wrapping](#wrapping-theme-components) is also a far safer alternative to [ejecting](#ejecting-theme-components). 3. **The smaller, the better.** If swizzling is inevitable, prefer to swizzle only the relevant part and maintain as little code on your own as possible. Swizzling a small component often means less risk of breaking during upgrade. [Wrapping](#wrapping-theme-components) is also a far safer alternative to [ejecting](#ejecting-theme-components).
## Theme aliases ## Theme aliases {#theme-aliases}
A theme works by exporting a set of components, e.g. `Navbar`, `Layout`, `Footer`, to render the data passed down from plugins. Docusaurus and users use these components by importing them using the `@theme` webpack alias: A theme works by exporting a set of components, e.g. `Navbar`, `Layout`, `Footer`, to render the data passed down from plugins. Docusaurus and users use these components by importing them using the `@theme` webpack alias:

4
website/docs/api/plugin-methods/README.md
View file

@ -8,14 +8,14 @@ This section is a work in progress. Anchor links or even URLs are not guaranteed
Plugin APIs are shared by themes and plugins—themes are loaded just like plugins. Plugin APIs are shared by themes and plugins—themes are loaded just like plugins.
## Plugin module ## Plugin module {#plugin-module}
Every plugin is imported as a module. The module is expected to have the following members: Every plugin is imported as a module. The module is expected to have the following members:
- A **default export**: the constructor function for the plugin. - A **default export**: the constructor function for the plugin.
- **Named exports**: the [static methods](./static-methods.md) called before plugins are initialized. - **Named exports**: the [static methods](./static-methods.md) called before plugins are initialized.
## Plugin constructor ## Plugin constructor {#plugin-constructor}
The plugin module's default export is a constructor function with the signature `(context: LoadContext, options: PluginOptions) => Plugin | Promise<Plugin>`. The plugin module's default export is a constructor function with the signature `(context: LoadContext, options: PluginOptions) => Plugin | Promise<Plugin>`.

6
website/docs/deployment.mdx
View file

@ -54,7 +54,7 @@ Use [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-gui
::: :::
## Using environment variables ## Using environment variables {using-environment-variables}
Putting potentially sensitive information in the environment is common practice. However, in a typical Docusaurus website, the `docusaurus.config.js` file is the only interface to the Node.js environment (see [our architecture overview](advanced/architecture.md)), while everything else—MDX pages, React components... are client side and do not have direct access to the `process` global. In this case, you can consider using [`customFields`](api/docusaurus.config.js.md#customfields) to pass environment variables to the client side. Putting potentially sensitive information in the environment is common practice. However, in a typical Docusaurus website, the `docusaurus.config.js` file is the only interface to the Node.js environment (see [our architecture overview](advanced/architecture.md)), while everything else—MDX pages, React components... are client side and do not have direct access to the `process` global. In this case, you can consider using [`customFields`](api/docusaurus.config.js.md#customfields) to pass environment variables to the client side.
@ -85,7 +85,7 @@ export default function Home() {
} }
``` ```
## Choosing a hosting provider ## Choosing a hosting provider {choosing-a-hosting-provider}
There are a few common hosting options: There are a few common hosting options:
@ -764,6 +764,6 @@ You can deploy any other changes in the future with the command `surge`.
See [docs](https://docs.quantcdn.io/docs/cli/continuous-integration) and [blog](https://www.quantcdn.io/blog) for more examples and use cases for deploying to QuantCDN. See [docs](https://docs.quantcdn.io/docs/cli/continuous-integration) and [blog](https://www.quantcdn.io/blog) for more examples and use cases for deploying to QuantCDN.
## Deploying to Layer0 ## Deploying to Layer0 {#deploying-to-layer0}
[Layer0](https://www.layer0.co) is an all-in-one platform to develop, deploy, preview, experiment on, monitor, and run your headless frontend. It is focused on large, dynamic websites and best-in-class performance through EdgeJS (a JavaScript-based Content Delivery Network), predictive prefetching, and performance monitoring. Layer0 offers a free tier. Get started in just a few minutes by following [Layer0's guide to deploying Docusaurus](https://docs.layer0.co/guides/docusaurus). [Layer0](https://www.layer0.co) is an all-in-one platform to develop, deploy, preview, experiment on, monitor, and run your headless frontend. It is focused on large, dynamic websites and best-in-class performance through EdgeJS (a JavaScript-based Content Delivery Network), predictive prefetching, and performance monitoring. Layer0 offers a free tier. Get started in just a few minutes by following [Layer0's guide to deploying Docusaurus](https://docs.layer0.co/guides/docusaurus).

4
website/docs/guides/docs/sidebar/autogenerated.md
View file

@ -362,7 +362,7 @@ The position metadata is only used **within a sidebar slice**: Docusaurus does n
::: :::
## Using number prefixes ## Using number prefixes {#using-number-prefixes}
A simple way to order an autogenerated sidebar is to prefix docs and folders by number prefixes, which also makes them appear in the file system in the same order when sorted by file name: A simple way to order an autogenerated sidebar is to prefix docs and folders by number prefixes, which also makes them appear in the file system in the same order when sorted by file name:
@ -398,7 +398,7 @@ Updating a number prefix can be annoying, as it can require **updating multiple
::: :::
## Customize the sidebar items generator ## Customize the sidebar items generator {#customize-the-sidebar-items-generator}
You can provide a custom `sidebarItemsGenerator` function in the docs plugin (or preset) config: You can provide a custom `sidebarItemsGenerator` function in the docs plugin (or preset) config:

4
website/docs/guides/docs/sidebar/index.md
View file

@ -117,7 +117,7 @@ type SidebarsFile = {
}; };
``` ```
## Theme configuration ## Theme configuration {#theme-configuration}
### Hideable sidebar {#hideable-sidebar} ### Hideable sidebar {#hideable-sidebar}
@ -133,7 +133,7 @@ module.exports = {
}; };
``` ```
### Auto-collapse sidebar categories ### Auto-collapse sidebar categories {#auto-collapse-sidebar-categories}
The `themeConfig.autoCollapseSidebarCategories` option would collapse all sibling categories when expanding one category. This saves the user from having too many categories open and helps them focus on the selected section. The `themeConfig.autoCollapseSidebarCategories` option would collapse all sibling categories when expanding one category. This saves the user from having too many categories open and helps them focus on the selected section.

2
website/docs/guides/docs/sidebar/items.md
View file

@ -223,7 +223,7 @@ Use `generated-index` links as a quick way to get an introductory document.
::: :::
#### Embedding generated index in doc page #### Embedding generated index in doc page {#embedding-generated-index-in-doc-page}
You can embed the generated cards list in a normal doc page as well, as long as the doc is used as a category index page. To do so, you need to use the `DocCardList` component, paired with the `useCurrentSidebarCategory` hook. You can embed the generated cards list in a normal doc page as well, as long as the doc is used as a category index page. To do so, you need to use the `DocCardList` component, paired with the `useCurrentSidebarCategory` hook.

12
website/docs/guides/docs/versioning.md
View file

@ -21,7 +21,7 @@ Most of the time, you don't need versioning as it will just increase your build
To better understand how versioning works and see if it suits your needs, you can read on below. To better understand how versioning works and see if it suits your needs, you can read on below.
## Overview ## Overview {#overview}
A typical versioned doc site looks like below: A typical versioned doc site looks like below:
@ -67,7 +67,7 @@ By default, the `current` docs version is labeled as `Next` and hosted under `/d
::: :::
### Terminology ### Terminology {#terminology}
Note the terminology we use here. Note the terminology we use here.
@ -80,7 +80,7 @@ Note the terminology we use here.
Current version is defined by the **file system location**, while latest version is defined by the **the navigation behavior**. They may or may not be the same version! (And the default configuration, as shown in the table above, would treat them as different: current version at `/docs/next` and latest at `/docs`.) Current version is defined by the **file system location**, while latest version is defined by the **the navigation behavior**. They may or may not be the same version! (And the default configuration, as shown in the table above, would treat them as different: current version at `/docs/next` and latest at `/docs`.)
## Tutorials ## Tutorials {#tutorials}
### Tagging a new version {#tagging-a-new-version} ### Tagging a new version {#tagging-a-new-version}
@ -157,7 +157,7 @@ Example:
2. Delete the versioned docs directory. Example: `versioned_docs/version-1.8.0`. 2. Delete the versioned docs directory. Example: `versioned_docs/version-1.8.0`.
3. Delete the versioned sidebars file. Example: `versioned_sidebars/version-1.8.0-sidebars.json`. 3. Delete the versioned sidebars file. Example: `versioned_sidebars/version-1.8.0-sidebars.json`.
## Configuring versioning behavior ## Configuring versioning behavior {#configuring-versioning-behavior}
The "current" version is the version name for the `./docs` folder. There are different ways to manage versioning, but two very common patterns are: The "current" version is the version name for the `./docs` folder. There are different ways to manage versioning, but two very common patterns are:
@ -207,7 +207,7 @@ We offer these plugin options to customize versioning behavior:
See [docs plugin configuration](../../api/plugins/plugin-content-docs.md#configuration) for more details. See [docs plugin configuration](../../api/plugins/plugin-content-docs.md#configuration) for more details.
## Navbar items ## Navbar items {#navbar-items}
We offer several navbar items to help you quickly set up navigation without worrying about versioned routes. We offer several navbar items to help you quickly set up navigation without worrying about versioned routes.
@ -249,7 +249,7 @@ Don't use relative paths import within the docs. Because when we cut a version t
+ import Foo from '@site/src/components/Foo'; + import Foo from '@site/src/components/Foo';
``` ```
### Link docs by file paths ### Link docs by file paths {#link-docs-by-file-paths}
Refer to other docs by relative file paths with the `.md` extension, so that Docusaurus can rewrite them to actual URL paths during building. Files will be linked to the correct corresponding version. Refer to other docs by relative file paths with the `.md` extension, so that Docusaurus can rewrite them to actual URL paths during building. Files will be linked to the correct corresponding version.

4
website/docs/guides/markdown-features/markdown-features-admonitions.mdx
View file

@ -124,7 +124,7 @@ Some **content** with _markdown_ `syntax`.
</BrowserWindow> </BrowserWindow>
## Admonitions with MDX ## Admonitions with MDX {#admonitions-with-mdx}
You can use MDX inside admonitions too! You can use MDX inside admonitions too!
@ -160,7 +160,7 @@ import TabItem from '@theme/TabItem';
</BrowserWindow> </BrowserWindow>
## Usage in JSX ## Usage in JSX {#usage-in-jsx}
Outside of Markdown, you can use the `@theme/Admonition` component to get the same output. Outside of Markdown, you can use the `@theme/Admonition` component to get the same output.

2
website/docs/guides/markdown-features/markdown-features-assets.mdx
View file

@ -166,7 +166,7 @@ import ThemedImage from '@theme/ThemedImage';
</BrowserWindow> </BrowserWindow>
``` ```
### GitHub-style themed images ### GitHub-style themed images {#github-style-themed-images}
GitHub uses its own [image theming approach](https://github.blog/changelog/2021-11-24-specify-theme-context-for-images-in-markdown/) with path fragments, which you can easily implement yourself. GitHub uses its own [image theming approach](https://github.blog/changelog/2021-11-24-specify-theme-context-for-images-in-markdown/) with path fragments, which you can easily implement yourself.

2
website/docs/guides/markdown-features/markdown-features-code-blocks.mdx
View file

@ -203,7 +203,7 @@ html[data-theme='dark'] .docusaurus-highlight-code-line {
} }
``` ```
### Highlighting with metadata string ### Highlighting with metadata string {#highlighting-with-metadata-string}
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. 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.

6
website/docs/guides/markdown-features/markdown-features-intro.mdx
View file

@ -18,7 +18,7 @@ This section assumes you are using the official Docusaurus content plugins.
::: :::
## Standard features ## Standard features {#standard-features}
Markdown is a syntax that enables you to write formatted content in a readable syntax. Markdown is a syntax that enables you to write formatted content in a readable syntax.
@ -44,7 +44,7 @@ Hello world message with some **bold** text, some _italic_ text and a [link](/)
</BrowserWindow> </BrowserWindow>
``` ```
## Quotes ## Quotes {#quotes}
Markdown quotes are beautifully styled: Markdown quotes are beautifully styled:
@ -62,7 +62,7 @@ Markdown quotes are beautifully styled:
</BrowserWindow> </BrowserWindow>
## Details ## Details {#details}
Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) HTML elements are beautifully styled: Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) HTML elements are beautifully styled:

12
website/docs/guides/markdown-features/markdown-features-math-equations.mdx
View file

@ -9,11 +9,11 @@ import BrowserWindow from '@site/src/components/BrowserWindow';
Mathematical equations can be rendered using [KaTeX](https://katex.org). Mathematical equations can be rendered using [KaTeX](https://katex.org).
## Usage ## Usage {#usage}
Please read [KaTeX](https://katex.org) documentation for more details. Please read [KaTeX](https://katex.org) documentation for more details.
### Inline ### Inline {#inline}
Write inline math equations by wrapping LaTeX equations between `$`: Write inline math equations by wrapping LaTeX equations between `$`:
@ -29,7 +29,7 @@ Let $f\colon[a,b] \to \R$ be Riemann integrable. Let $F\colon[a,b]\to\R$ be $F(x
</BrowserWindow> </BrowserWindow>
### Blocks ### Blocks {#blocks}
For equation block or display mode, use line breaks and `$$`: For equation block or display mode, use line breaks and `$$`:
@ -47,7 +47,7 @@ $$
</BrowserWindow> </BrowserWindow>
## Configuration ## Configuration {#configuration}
To enable KaTeX, you need to install `remark-math` and `rehype-katex` plugins. To enable KaTeX, you need to install `remark-math` and `rehype-katex` plugins.
@ -128,7 +128,7 @@ module.exports = {
}; };
``` ```
## Self-hosting KaTeX assets ## Self-hosting KaTeX assets {#self-hosting-katex-assets}
Loading stylesheets, fonts, and javascript libraries from CDN sources is a good practice for popular libraries and assets, since it reduces the amount of assets you have to host. In case you prefer to self-host the `katex.min.css` (along with required KaTeX fonts), you can download the latest version from [KaTeX GitHub releases](https://github.com/KaTeX/KaTeX/releases), extract and copy `katex.min.css` and `fonts` directory (only `.woff2` font types should be enough) to your site's `static` directory, and in `docusaurus.config.js`, replace the stylesheet's `href` from the CDN url to your local path (say, `/katex/katex.min.css`). Loading stylesheets, fonts, and javascript libraries from CDN sources is a good practice for popular libraries and assets, since it reduces the amount of assets you have to host. In case you prefer to self-host the `katex.min.css` (along with required KaTeX fonts), you can download the latest version from [KaTeX GitHub releases](https://github.com/KaTeX/KaTeX/releases), extract and copy `katex.min.css` and `fonts` directory (only `.woff2` font types should be enough) to your site's `static` directory, and in `docusaurus.config.js`, replace the stylesheet's `href` from the CDN url to your local path (say, `/katex/katex.min.css`).
@ -143,7 +143,7 @@ module.exports = {
}; };
``` ```
## Upgrading rehype-katex beyond recommended version ## Upgrading rehype-katex beyond recommended version {#upgrading-rehype-katex-beyond-recommended-version}
:::tip :::tip

2
website/docs/guides/markdown-features/markdown-features-plugins.mdx
View file

@ -114,7 +114,7 @@ module.exports = {
You should check your plugin's documentation for the options it supports. You should check your plugin's documentation for the options it supports.
## Creating new rehype/remark plugins ## Creating new rehype/remark plugins {#creating-new-rehyperemark-plugins}
If there isn't an existing package that satisfies your customization need, you can create your own MDX plugin. If there isn't an existing package that satisfies your customization need, you can create your own MDX plugin.

6
website/docs/guides/markdown-features/markdown-features-react.mdx
View file

@ -87,7 +87,7 @@ In addition, MDX is not [100% compatible with CommonMark](https://github.com/fac
::: :::
### Importing components ### Importing components {#importing-components}
You can also import your own components defined in other files or third-party components installed via npm. You can also import your own components defined in other files or third-party components installed via npm.
@ -133,7 +133,7 @@ import Highlight from '@site/src/components/Highlight';
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 other fancy stuff you can do with MDX.
### Markdown and JSX interoperability ### Markdown and JSX interoperability {#markdown-and-jsx-interoperability}
Docusaurus v2 is using MDX v1, which has a lot of known cases where the content fails to be correctly parsed as Markdown. Use the **[MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground)** to ensure that your syntax is valid MDX. Docusaurus v2 is using MDX v1, which has a lot of known cases where the content fails to be correctly parsed as Markdown. Use the **[MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground)** to ensure that your syntax is valid MDX.
@ -419,7 +419,7 @@ The table of contents does not currently contain the imported Markdown headings.
::: :::
## Available exports ## Available exports {#available-exports}
Within the MDX page, the following variables are available as globals: Within the MDX page, the following variables are available as globals:

4
website/docs/guides/markdown-features/markdown-features-tabs.mdx
View file

@ -128,7 +128,7 @@ It is possible to only render the default tab with `<Tabs lazy />`.
::: :::
## Displaying a default tab ## Displaying a default tab {#displaying-a-default-tab}
The first tab is displayed by default, and to override this behavior, you can specify a default tab by adding `default` to one of the tab items. You can also set the `defaultValue` prop of the `Tabs` component to the label value of your choice. For example, in the example above, either setting `default` for the `value="apple"` tab or setting `defaultValue="apple"` for the tabs forces the "Apple" tab to be open by default. The first tab is displayed by default, and to override this behavior, you can specify a default tab by adding `default` to one of the tab items. You can also set the `defaultValue` prop of the `Tabs` component to the label value of your choice. For example, in the example above, either setting `default` for the `value="apple"` tab or setting `defaultValue="apple"` for the tabs forces the "Apple" tab to be open by default.
@ -248,7 +248,7 @@ You might want to customize the appearance of a certain set of tabs. You can pas
</BrowserWindow> </BrowserWindow>
``` ```
### Customizing tab headings ### Customizing tab headings {#customizing-tab-headings}
You can also customize each tab heading independently by using the `attributes` field. The extra props can be passed to the headings either through the `values` prop in `Tabs`, or props of each `TabItem`—in the same way as you declare `label`. You can also customize each tab heading independently by using the `attributes` field. The extra props can be passed to the headings either through the `values` prop in `Tabs`, or props of each `TabItem`—in the same way as you declare `label`.

4
website/docs/i18n/i18n-git.md
View file

@ -30,7 +30,7 @@ Refer to the [Docusaurus i18n RFC](https://github.com/facebook/docusaurus/issues
::: :::
## Initialization ## Initialization {#initialization}
This is a walk-through of using Git to translate a newly initialized English Docusaurus website into French, and assume you already followed the [i18n tutorial](./i18n-tutorial.md). This is a walk-through of using Git to translate a newly initialized English Docusaurus website into French, and assume you already followed the [i18n tutorial](./i18n-tutorial.md).
@ -145,7 +145,7 @@ npm run build -- --locale fr
Follow the same process for each locale you need to support. Follow the same process for each locale you need to support.
## Maintenance ## Maintenance {#maintenance}
Keeping translated files **consistent** with the originals **can be challenging**, in particular for Markdown documents. Keeping translated files **consistent** with the originals **can be challenging**, in particular for Markdown documents.

2
website/docs/i18n/i18n-introduction.md
View file

@ -85,7 +85,7 @@ The choice was made for 2 reasons:
- **Description attribute**: to help translators with additional context - **Description attribute**: to help translators with additional context
- **Widely supported**: [Chrome extensions](https://developer.chrome.com/docs/extensions/mv2/i18n-messages/), [Crowdin](https://support.crowdin.com/file-formats/chrome-json/), [Transifex](https://docs.transifex.com/formats/chrome-json), [Phrase](https://help.phrase.com/help/chrome-json-messages), [Applanga](https://www.applanga.com/docs/formats/chrome_i18n_json), etc. - **Widely supported**: [Chrome extensions](https://developer.chrome.com/docs/extensions/mv2/i18n-messages/), [Crowdin](https://support.crowdin.com/file-formats/chrome-json/), [Transifex](https://docs.transifex.com/formats/chrome-json), [Phrase](https://help.phrase.com/help/chrome-json-messages), [Applanga](https://www.applanga.com/docs/formats/chrome_i18n_json), etc.
#### Data files #### Data files {#data-files}
Some plugins may read from external data files that are localized as a whole. For example, the blog plugin uses an [`authors.yml`](../blog.mdx#global-authors) file that can be translated by creating a copy under `i18n/[locale]/docusaurus-plugin-content-blog/authors.yml`. Some plugins may read from external data files that are localized as a whole. For example, the blog plugin uses an [`authors.yml`](../blog.mdx#global-authors) file that can be translated by creating a copy under `i18n/[locale]/docusaurus-plugin-content-blog/authors.yml`.

6
website/docs/i18n/i18n-tutorial.md
View file

@ -102,7 +102,7 @@ After copying files around, restart your site with `npm run start -- --locale fr
::: :::
### Translate your React code ### Translate your React code {#translate-your-react-code}
For any React code you've written yourself: React pages, React components, etc., you will use the [**translation APIs**](../docusaurus-core.md#translate). For any React code you've written yourself: React pages, React components, etc., you will use the [**translation APIs**](../docusaurus-core.md#translate).
@ -258,7 +258,7 @@ You can see the calls to the translation APIs as purely _markers_ that tell Docu
::: :::
### Translate plugin data ### Translate plugin data {#translate-plugin-data}
JSON translation files are used for everything that is interspersed in your code: JSON translation files are used for everything that is interspersed in your code:
@ -450,7 +450,7 @@ It is also possible to deploy each locale as a separate subdomain, assemble the
- Deploy your site as `fr.docusaurus.io` - Deploy your site as `fr.docusaurus.io`
- Configure a CDN to serve it from `docusaurus.io/fr` - Configure a CDN to serve it from `docusaurus.io/fr`
## Managing translations ## Managing translations {#managing-translations}
Docusaurus doesn't care about how you manage your translations: all it needs is that all translation files (JSON, Markdown, or other data files) are available in the file system during building. However, as site creators, you would need to consider how translations are managed so your translation contributors could collaborate well. Docusaurus doesn't care about how you manage your translations: all it needs is that all translation files (JSON, Markdown, or other data files) are available in the file system during building. However, as site creators, you would need to consider how translations are managed so your translation contributors could collaborate well.

2
website/docs/installation.md
View file

@ -100,7 +100,7 @@ my-website
- `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them - `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them
- `/sidebar.js` - Used by the documentation to specify the order of documents in the sidebar - `/sidebar.js` - Used by the documentation to specify the order of documents in the sidebar
### Monorepos ### Monorepos {#monorepos}
If you are using Docusaurus for documentation of an existing project, a monorepo may be the solution for you. Monorepos allow you to share dependencies between similar projects. For example, your website may use your local packages to showcase the latest features, instead of depending on a released version; your contributors can also conveniently update the docs as they implement features. An example monorepo folder structure is below: If you are using Docusaurus for documentation of an existing project, a monorepo may be the solution for you. Monorepos allow you to share dependencies between similar projects. For example, your website may use your local packages to showcase the latest features, instead of depending on a released version; your contributors can also conveniently update the docs as they implement features. An example monorepo folder structure is below:

2
website/docs/migration/migration-overview.md
View file

@ -8,7 +8,7 @@ This doc guides you through migrating an existing Docusaurus 1 site to Docusauru
We try to make this as easy as possible, and provide a migration cli. We try to make this as easy as possible, and provide a migration cli.
## Main differences ## Main differences {#main-differences}
Docusaurus 1 is a pure documentation site generator, using React as a server-side template engine, but not loading React on the browser. Docusaurus 1 is a pure documentation site generator, using React as a server-side template engine, but not loading React on the browser.

8
website/docs/static-assets.md
View file

@ -24,9 +24,9 @@ module.exports = {
Now, all files in `public` as well as `static` will be copied to the build output. Now, all files in `public` as well as `static` will be copied to the build output.
## Referencing your static asset ## Referencing your static asset {#referencing-your-static-asset}
### In JSX ### In JSX {#in-jsx}
In JSX, you can reference assets from the `static` folder in your code using absolute URLs, but this is not ideal because changing the site `baseUrl` will **break those links**. For the image `<img src="/img/docusaurus.png" />` served at `https://example.com/test`, the browser will try to resolve it from the URL root, i.e. as `https://example.com/img/docusaurus.png`, which will fail because it's actually served at `https://example.com/test/img/docusaurus.png`. In JSX, you can reference assets from the `static` folder in your code using absolute URLs, but this is not ideal because changing the site `baseUrl` will **break those links**. For the image `<img src="/img/docusaurus.png" />` served at `https://example.com/test`, the browser will try to resolve it from the URL root, i.e. as `https://example.com/img/docusaurus.png`, which will fail because it's actually served at `https://example.com/test/img/docusaurus.png`.
@ -58,7 +58,7 @@ import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
<DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />; <DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;
``` ```
### In Markdown ### In Markdown {#in-markdown}
In Markdown, you can stick to using absolute paths when writing links or images **in Markdown syntax** because Docusaurus handles them as `require` calls instead of URLs when parsing the Markdown. See [Markdown static assets](./guides/markdown-features/markdown-features-assets.mdx). In Markdown, you can stick to using absolute paths when writing links or images **in Markdown syntax** because Docusaurus handles them as `require` calls instead of URLs when parsing the Markdown. See [Markdown static assets](./guides/markdown-features/markdown-features-assets.mdx).
@ -74,7 +74,7 @@ Docusaurus will only parse links that are in Markdown syntax. If your asset refe
::: :::
### In CSS ### In CSS {#in-css}
In CSS, the `url()` function is commonly used to reference assets like fonts and images. To reference a static asset, use absolute paths: In CSS, the `url()` function is commonly used to reference assets like fonts and images. To reference a static asset, use absolute paths:

2
website/docs/styling-layout.md
View file

@ -64,7 +64,7 @@ If you want to add CSS to any element, you can open the DevTools in your browser
- **Infima class names**. These class names usually follow the [BEM convention](http://getbem.com/naming/) of `block__element--modifier`. They are usually stable but are still considered implementation details, so you should generally avoid targeting them. However, you can [modify Infima CSS variables](#styling-your-site-with-infima). - **Infima class names**. These class names usually follow the [BEM convention](http://getbem.com/naming/) of `block__element--modifier`. They are usually stable but are still considered implementation details, so you should generally avoid targeting them. However, you can [modify Infima CSS variables](#styling-your-site-with-infima).
- **CSS module class names**. These class names have a hash in production (`codeBlockContainer_RIuc`) and are appended with a long file path in development. They are considered implementation details and you should almost always avoid targeting them in your custom CSS. If you must, you can use an [attribute selector](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors) (`[class*='codeBlockContainer']`) that ignores the hash. - **CSS module class names**. These class names have a hash in production (`codeBlockContainer_RIuc`) and are appended with a long file path in development. They are considered implementation details and you should almost always avoid targeting them in your custom CSS. If you must, you can use an [attribute selector](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors) (`[class*='codeBlockContainer']`) that ignores the hash.
### Theme Class Names ### Theme Class Names {#theme-class-names}
We provide some predefined CSS class names for global layout styling. These names are theme-agnostic and meant to be targeted by custom CSS. We provide some predefined CSS class names for global layout styling. These names are theme-agnostic and meant to be targeted by custom CSS.

4
website/docs/using-plugins.md
View file

@ -112,7 +112,7 @@ At most one plugin instance can be the "default plugin instance", by omitting th
::: :::
## Using themes ## 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](./advanced/swizzling.md#theme-aliases). 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](./advanced/swizzling.md#theme-aliases).
@ -278,7 +278,7 @@ module.exports = {
}; };
``` ```
## Module shorthands ## 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: