chore: release Docusaurus 3.7.0 (#10812)

website/versioned_docs/version-3.7.0/api/misc/_category_.yml

@@ -0,0 +1,2 @@
+label: Miscellaneous
+position: 4

website/versioned_docs/version-3.7.0/api/misc/create-docusaurus.mdx

@@ -0,0 +1,58 @@
+---
+sidebar_position: 0
+slug: /api/misc/create-docusaurus
+---
+
+# 📦 create-docusaurus
+
+A scaffolding utility to help you instantly set up a functional Docusaurus app.
+
+## Usage {#usage}
+
+```bash
+npx create-docusaurus@latest [name] [template] [rootDir]
+```
+
+The `name` argument will be used as the site's path as well as the `name` field in the created app's package.json. It can be an absolute path, or a path relative to `rootDir`.
+
+The `template` argument can be one of the following:
+
+- `classic`: Uses the classic template (recommended)
+- `facebook`: Uses the Facebook/Meta template, which contains some Meta-specific setup
+- A git repo URL (beginning with `https://` or `git@`), which can be cloned to the destination
+- A local file path relative to CWD, which contains the files to be copied to destination
+
+The `rootDir` will be used to resolve the absolute path to the site directory. The default is CWD.
+
+:::warning
+
+This command should be preferably used in an interactive shell so all features are available.
+
+:::
+
+## Options {#options}
+
+### `-t, --typescript` {#typescript}
+
+Used when the template argument is a recognized name. Currently, only `classic` provides a TypeScript variant.
+
+### `-g, --git-strategy` {#git-strategy}
+
+Used when the template argument is a git repo. It needs to be one of:
+
+- `deep`: preserves full git history
+- `shallow`: clones with `--depth=1`
+- `copy`: does a shallow clone, but does not create a git repo
+- `custom`: enter your custom git clone command. We will prompt you for it. You can write something like `git clone --depth 10`, and we will append the repository URL and destination directory.
+
+### `-p, --package-manager` {#package-manager}
+
+Value should be one of `npm`, `yarn`, `pnpm`, or `bun`. If it's not explicitly provided, Docusaurus will infer one based on:
+
+- The lockfile already present in the CWD (e.g. if you are setting up website in an existing project)
+- The command used to invoke `create-docusaurus` (e.g. `npm init`, `npx`, `yarn create`, `bunx`, etc.)
+- Interactive prompting, in case all heuristics are not present
+
+### `-s, --skip-install` {#skip-install}
+
+If provided, Docusaurus will not automatically install dependencies after creating the app. The `--package-manager` option is only useful when you are actually installing dependencies.

website/versioned_docs/version-3.7.0/api/misc/eslint-plugin/README.mdx

@@ -0,0 +1,74 @@
+---
+sidebar_position: 1
+slug: /api/misc/@docusaurus/eslint-plugin
+---
+
+# 📦 eslint-plugin
+
+[ESLint](https://eslint.org/) is a tool that statically analyzes your code and reports problems or suggests best practices through editor hints and command line. Docusaurus provides an ESLint plugin to enforce best Docusaurus practices.
+
+## Installation
+
+```bash npm2yarn
+npm install --save-dev @docusaurus/eslint-plugin
+```
+
+## Usage
+
+### Recommended config
+
+Add `plugin:@docusaurus/recommended` to the `extends` section of your `.eslintrc` configuration file:
+
+```json title=".eslintrc"
+{
+  "extends": ["plugin:@docusaurus/recommended"]
+}
+```
+
+This will enable the `@docusaurus` eslint plugin and use the `recommended` config. See [Supported rules](#supported-rules) below for a list of rules that this will enable.
+
+### Manual config
+
+For more fine-grained control, you can also enable the plugin manually and configure the rules you want to use directly:
+
+```json title=".eslintrc"
+{
+  "plugins": ["@docusaurus"],
+  "rules": {
+    "@docusaurus/string-literal-i18n-messages": "error",
+    "@docusaurus/no-untranslated-text": "warn"
+  }
+}
+```
+
+## Supported configs
+
+- Recommended: recommended rule set for most Docusaurus sites that should be extended from.
+- All: **all** rules enabled. This will change between minor versions, so you should not use this if you want to avoid unexpected breaking changes.
+
+## Supported rules
+
+| Name | Description |  |
+| --- | --- | --- |
+| [`@docusaurus/no-untranslated-text`](./no-untranslated-text.mdx) | Enforce text labels in JSX to be wrapped by translate calls |  |
+| [`@docusaurus/string-literal-i18n-messages`](./string-literal-i18n-messages.mdx) | Enforce translate APIs to be called on plain text labels | ✅ |
+| [`@docusaurus/no-html-links`](./no-html-links.mdx) | Ensures @docusaurus/Link is used instead of `<a>` tags | ✅ |
+| [`@docusaurus/prefer-docusaurus-heading`](./prefer-docusaurus-heading.mdx) | Ensures @theme/Heading is used instead of `<hn>` tags for headings | ✅ |
+
+✅ = recommended
+
+## Example configuration
+
+Here's an example configuration:
+
+```js title=".eslintrc.js"
+module.exports = {
+  extends: ['plugin:@docusaurus/recommended'],
+  rules: {
+    '@docusaurus/no-untranslated-text': [
+      'warn',
+      {ignoredStrings: ['·', '—', '×']},
+    ],
+  },
+};
+```

website/versioned_docs/version-3.7.0/api/misc/eslint-plugin/no-html-links.mdx

@@ -0,0 +1,47 @@
+---
+slug: /api/misc/@docusaurus/eslint-plugin/no-html-links
+---
+
+# no-html-links
+
+import APITable from '@site/src/components/APITable';
+
+Ensure that the Docusaurus [`<Link>`](../../../docusaurus-core.mdx#link) component is used instead of `<a>` tags.
+
+The `<Link>` component has prefetching and preloading built-in. It also does build-time broken link detection, and helps Docusaurus understand your site's structure better.
+
+## Rule Details {#details}
+
+Examples of **incorrect** code for this rule:
+
+```html
+<a href="/page">go to page!</a>
+
+<a href="https://x.com/docusaurus" target="_blank">X</a>
+```
+
+Examples of **correct** code for this rule:
+
+```js
+import Link from '@docusaurus/Link'
+
+<Link to="/page">go to page!</Link>
+
+<Link to="https://x.com/docusaurus">X</Link>
+```
+
+## Rule Configuration {#configuration}
+
+Accepted fields:
+
+```mdx-code-block
+<APITable>
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ignoreFullyResolved` | `boolean` | `false` | Set to true will not report any `<a>` tags with absolute URLs including a protocol. |
+
+```mdx-code-block
+</APITable>
+```

website/versioned_docs/version-3.7.0/api/misc/eslint-plugin/no-untranslated-text.mdx

@@ -0,0 +1,54 @@
+---
+slug: /api/misc/@docusaurus/eslint-plugin/no-untranslated-text
+---
+
+# no-untranslated-text
+
+import APITable from '@site/src/components/APITable';
+
+Enforce text labels in JSX to be wrapped by translate calls.
+
+When the [i18n feature](../../../i18n/i18n-introduction.mdx) is used, this rule ensures that all labels appearing on the website are translatable, so no string accidentally slips through untranslated.
+
+## Rule Details {#details}
+
+Examples of **incorrect** code for this rule:
+
+```js
+// Hello World is not translated
+<Component>Hello World</Component>
+```
+
+Examples of **correct** code for this rule:
+
+```js
+// Hello World is translated
+<Component>
+  <Translate>Hello World</Translate>
+</Component>
+```
+
+## Rule Configuration {#configuration}
+
+Accepted fields:
+
+```mdx-code-block
+<APITable>
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ignoredStrings` | `string[]` | `[]` | Text labels that only contain strings in this list will not be reported. |
+
+```mdx-code-block
+</APITable>
+```
+
+## When Not To Use It {#when-not-to-use}
+
+If you're not using the [i18n feature](../../../i18n/i18n-introduction.mdx), you can disable this rule. You can also disable this rule where the text is not supposed to be translated.
+
+## Further Reading {#further-reading}
+
+- https://docusaurus.io/docs/docusaurus-core#translate
+- https://docusaurus.io/docs/docusaurus-core#translate-imperative

website/versioned_docs/version-3.7.0/api/misc/eslint-plugin/prefer-docusaurus-heading.mdx

@@ -0,0 +1,31 @@
+---
+slug: /api/misc/@docusaurus/eslint-plugin/prefer-docusaurus-heading
+---
+
+# prefer-docusaurus-heading
+
+Ensures that the `@theme/Heading` theme component provided by Docusaurus [`theme-classic`](../../themes/theme-classic.mdx) is used instead of `<hn>` tags for headings.
+
+## Rule Details {#details}
+
+Examples of **incorrect** code for this rule:
+
+```html
+<h1>This is heading 1</h1>
+
+<h2>This is heading 2</h2>
+
+<h3>This is heading 3</h3>
+```
+
+Examples of **correct** code for this rule:
+
+```javascript
+import Heading from '@theme/Heading'
+
+<Heading as='h1'>This is heading 1</Heading>
+
+<Heading as='h2'>This is heading 2</Heading>
+
+<Heading as='h3'>This is heading 3</Heading>
+```

website/versioned_docs/version-3.7.0/api/misc/eslint-plugin/string-literal-i18n-messages.mdx

@@ -0,0 +1,50 @@
+---
+slug: /api/misc/@docusaurus/eslint-plugin/string-literal-i18n-messages
+---
+
+# string-literal-i18n-messages
+
+Enforce translate APIs to be called on plain text labels.
+
+Docusaurus offers the [`docusaurus write-translations`](../../../cli.mdx#docusaurus-write-translations-sitedir) API, which statically extracts the text labels marked as translatable. Dynamic values used in `<Translate>` or `translate()` calls will fail to be extracted. This rule will ensure that all translate calls are statically extractable.
+
+## Rule Details {#details}
+
+Examples of **incorrect** code for this rule:
+
+```js
+const text = 'Some text to be translated'
+
+// Invalid <Translate> child
+<Translate>{text}</Translate>
+
+// Invalid message attribute
+translate({message: text})
+```
+
+Examples of **correct** code for this rule:
+
+```js
+// Valid <Translate> child
+<Translate>Some text to be translated</Translate>
+
+// Valid message attribute
+translate({message: 'Some text to be translated'})
+
+// Valid <Translate> child using values object as prop
+<Translate values={{firstName: 'Sébastien'}}>
+  {'Welcome, {firstName}! How are you?'}
+</Translate>
+
+// Valid message attribute using values object as second argument
+translate({message: 'The logo of site {siteName}'}, {siteName: 'Docusaurus'})
+```
+
+## When Not To Use It {#when-not-to-use}
+
+If you're not using the [i18n feature](../../../i18n/i18n-introduction.mdx), you can disable this rule.
+
+## Further Reading {#further-reading}
+
+- https://docusaurus.io/docs/docusaurus-core#translate
+- https://docusaurus.io/docs/docusaurus-core#translate-imperative

website/versioned_docs/version-3.7.0/api/misc/logger/logger.mdx

@@ -0,0 +1,71 @@
+---
+sidebar_position: 2
+slug: /api/misc/@docusaurus/logger
+---
+
+# 📦 logger
+
+An encapsulated logger for semantically formatting console messages.
+
+Authors of packages in the Docusaurus ecosystem are encouraged to use this package to provide unified log formats.
+
+## APIs
+
+It exports a single object as default export: `logger`. `logger` has the following properties:
+
+- Some useful colors.
+  - `red`
+  - `yellow`
+  - `green`
+  - `bold`
+  - `dim`
+- Formatters. These functions all have the signature `(msg: unknown) => string`. Note that their implementations are not guaranteed. You should only care about their semantics.
+  - `path`: formats a file path.
+  - `url`: formats a URL.
+  - `name`: formats an identifier.
+  - `code`: formats a code snippet.
+  - `subdue`: subdues the text.
+  - `num`: formats a number.
+- The `interpolate` function. It is a template literal tag. The syntax can be found below.
+- Logging functions. All logging functions can both be used as normal functions (similar to the `console.log` family, but only accepts one parameter) or template literal tags.
+  - `info`: prints information.
+  - `warn`: prints a warning that should be paid attention to.
+  - `error`: prints an error (not necessarily halting the program) that signals significant problems.
+  - `success`: prints a success message.
+- The `report` function. It takes a `ReportingSeverity` value (`ignore`, `log`, `warn`, `throw`) and reports a message according to the severity.
+
+:::warning A word on the `error` formatter
+
+Beware that an `error` message, even when it doesn't hang the program, is likely going to cause confusion. When users inspect logs and find an `[ERROR]`, even when the build succeeds, they will assume something is going wrong. Use it sparingly.
+
+Docusaurus only uses `logger.error` when printing messages immediately before throwing an error, or when user has set the reporting severity of `onBrokenLink`, etc. to `"error"`.
+
+In addition, `warn` and `error` will color the **entire** message for better attention. If you are printing large blocks of help text about an error, better use `logger.info`.
+
+:::
+
+### Using the template literal tag
+
+The template literal tag evaluates the template and expressions embedded. `interpolate` returns a new string, while other logging functions prints it. Below is a typical usage:
+
+```js
+import logger from '@docusaurus/logger';
+
+logger.info`Hello name=${name}! You have number=${money} dollars. Here are the ${
+  items.length > 1 ? 'items' : 'item'
+} on the shelf: ${items}
+To buy anything, enter code=${'buy x'} where code=${'x'} is the item's name; to quit, press code=${'Ctrl + C'}.`;
+```
+
+An embedded expression is optionally preceded by a flag in the form `[a-z]+=` (a few lowercase letters, followed by an equals sign, directly preceding the embedded expression). If the expression is not preceded by any flag, it's printed out as-is. Otherwise, it's formatted with one of the formatters:
+
+- `path=`: `path`
+- `url=`: `url`
+- `name=`: `name`
+- `code=`: `code`
+- `subdue=`: `subdue`
+- `number=`: `num`
+
+If the expression is an array, it's formatted by `` `\n- ${array.join('\n- ')}\n` `` (note it automatically gets a leading line end). Each member is formatted by itself and the bullet is not formatted. So you would see the above message printed as:
+
+![Some text output in the terminal, containing array, code, name, and number formatting](./demo.png)