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

)

packages/docusaurus/bin/docusaurus.js

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

packages/docusaurus/src/commands/writeHeadingIds.ts

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

website/docs/advanced/plugins.md

@@ -80,11 +80,11 @@ Plugins come as several types:
 
 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.
 
-### 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`...
 

website/docs/advanced/routing.md

@@ -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.
 
-## 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:
 
@@ -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".
 
-### 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.
 
 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:
 
@@ -52,7 +52,7 @@ The blog creates the following routes:
   - The route is customizable through the `archiveBasePath` option.
   - 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`.
 
@@ -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`.
 
-### 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.
 
@@ -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.
 
-## 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.
 
@@ -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/`.
 
-## 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.
 
@@ -244,7 +244,7 @@ export function PageRoute() {
 </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.
 

website/docs/advanced/ssg.md

@@ -92,15 +92,15 @@ export default function expensiveComp() {
 </Tabs>
 </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.
 
 These HTML files are the first to arrive at the user's browser screen when a URL is visited (see [routing](routing.md)). Afterwards, the browser fetches and runs other JS code to provide the "dynamic" parts of your site—anything implemented with JavaScript. However, before that, the main content of your page is already visible, allowing faster loading.
 
 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:
 
@@ -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.
 
-### `<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.
 
@@ -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.
 
-### `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.
 
@@ -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.
 
@@ -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.
 

website/docs/advanced/swizzling.md

@@ -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".
 
-## Swizzling
+## Swizzling {#swizzling}
 
 ```mdx-code-block
 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`.
 
-### 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:
 
@@ -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).
 
-## 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?
 
@@ -110,15 +110,15 @@ 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:
 
 1. **Use CSS.** CSS rules and selectors can often help you achieve a decent degree of customization. Refer to [styling and layout](../styling-layout.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).
 
-## 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:
 

website/docs/api/plugin-methods/README.md

@@ -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 module
+## Plugin module {#plugin-module}
 
 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.
 - **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>`.
 

website/docs/deployment.mdx

@@ -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.
 
@@ -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:
 
@@ -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.
 
-## 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).

website/docs/guides/docs/sidebar/autogenerated.md

@@ -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:
 
@@ -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:
 

website/docs/guides/docs/sidebar/index.md

@@ -117,7 +117,7 @@ type SidebarsFile = {
 };
 ```
 
-## Theme configuration
+## Theme configuration {#theme-configuration}
 
 ### 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.
 

website/docs/guides/docs/sidebar/items.md

@@ -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.
 

website/docs/guides/docs/versioning.md

@@ -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.
 
-## Overview
+## Overview {#overview}
 
 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.
 
@@ -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`.)
 
-## Tutorials
+## Tutorials {#tutorials}
 
 ### 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`.
 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:
 
@@ -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.
 
-## Navbar items
+## Navbar items {#navbar-items}
 
 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';
 ```
 
-### 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.