mirror of
https://github.com/facebook/docusaurus.git
synced 2025-07-24 12:07:58 +02:00
chore: backport retro compatible commits for the Docusaurus v2.3 release (#8585)
Co-authored-by: stnor <stefan@selessia.com> Co-authored-by: Joshua Chen <sidachen2003@gmail.com> Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com> Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Matija Sirk <matija.sirk@kopit.si> Co-authored-by: AHMET BAYHAN BAYRAMOGLU <49499275+ABB65@users.noreply.github.com> Co-authored-by: Stefan Norberg <stefan@norberg.org> Co-authored-by: Josh Goldberg <git@joshuakgoldberg.com> Co-authored-by: Muhammad Hammad <33136628+mhnaeem@users.noreply.github.com> Co-authored-by: Denis Al-Khelali <denis.al-khelali@itechart-group.com> Co-authored-by: Balthasar Hofer <lebalz@outlook.com> Co-authored-by: Danny Kim <0916dhkim@gmail.com> Co-authored-by: Frieder Bluemle <frieder.bluemle@gmail.com> Co-authored-by: John Reilly <johnny_reilly@hotmail.com> Co-authored-by: Robert Lawrence <62929526+r-lawrence@users.noreply.github.com> Co-authored-by: Sadegh Karimi <sadegh.krmi@gmail.com> Co-authored-by: Lachlan Heywood <lachieh@users.noreply.github.com> Co-authored-by: mturoci <64769322+mturoci@users.noreply.github.com> Co-authored-by: 宋锦丰 <36468758+SJFCS@users.noreply.github.com> Co-authored-by: Nguyễn Thành Nam <namnguyenthanh.work@gmail.com> Co-authored-by: Dongjoon Lee <djunnni@gmail.com> Co-authored-by: Thomas.CA <44041651+Thomascogez@users.noreply.github.com> Co-authored-by: Riccardo <riccardo.odone@gmail.com> Co-authored-by: Lane Goolsby <lanegoolsby@yahoo.com> Co-authored-by: Mariusz Krzaczkowski <m.krzaczkowski@yetiforce.com> Co-authored-by: Matija Sirk <sirkmatija@gmail.com> Co-authored-by: Jiří <zmrhal.j@gmail.com>
This commit is contained in:
Sébastien Lorber
GitHub
parent
de972142a8
commit
c84d779627
173 changed files with 2640 additions and 1199 deletions
|
|
@ -15,15 +15,9 @@ npm install --save-dev @docusaurus/eslint-plugin
|
|||
|
||||
## Usage
|
||||
|
||||
Add `@docusaurus` to the plugins section of your `.eslintrc` configuration file:
|
||||
### Recommended config
|
||||
|
||||
```json title=".eslintrc"
|
||||
{
|
||||
"plugins": ["@docusaurus"]
|
||||
}
|
||||
```
|
||||
|
||||
Then, you can extend one of the configs (e.g. the `recommended` config):
|
||||
Add `plugin:@docusaurus/recommended` to the `extends` section of your `.eslintrc` configuration file:
|
||||
|
||||
```json title=".eslintrc"
|
||||
{
|
||||
|
|
@ -31,10 +25,15 @@ Then, you can extend one of the configs (e.g. the `recommended` config):
|
|||
}
|
||||
```
|
||||
|
||||
Each config contains a set of rules. For more fine-grained control, you can also configure the rules you want to use directly:
|
||||
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"
|
||||
|
|
@ -42,12 +41,12 @@ Each config contains a set of rules. For more fine-grained control, you can also
|
|||
}
|
||||
```
|
||||
|
||||
## Supported Configs
|
||||
## 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
|
||||
## Supported rules
|
||||
|
||||
| Name | Description | |
|
||||
| --- | --- | --- |
|
||||
|
|
@ -63,7 +62,6 @@ Here's an example configuration:
|
|||
```js title=".eslintrc.js"
|
||||
module.exports = {
|
||||
extends: ['plugin:@docusaurus/recommended'],
|
||||
plugins: ['@docusaurus'],
|
||||
rules: {
|
||||
'@docusaurus/no-untranslated-text': [
|
||||
'warn',
|
||||
|
|
|
|||
|
|
@ -67,6 +67,7 @@ Accepted fields:
|
|||
| `authorsMapPath` | `string` | `'authors.yml'` | Path to the authors map file, relative to the blog content directory. |
|
||||
| `feedOptions` | _See below_ | `{type: ['rss', 'atom']}` | Blog feed. |
|
||||
| `feedOptions.type` | <code><a href="#FeedType">FeedType</a> \| <a href="#FeedType">FeedType</a>[] \| 'all' \| null</code> | **Required** | Type of feed to be generated. Use `null` to disable generation. |
|
||||
| `feedOptions.createFeedItems` | <code><a href="#CreateFeedItemsFn">CreateFeedItemsFn</a> \| undefined</code> | `undefined` | An optional function which can be used to transform and / or filter the items in the feed. |
|
||||
| `feedOptions.title` | `string` | `siteConfig.title` | Title of the feed. |
|
||||
| `feedOptions.description` | `string` | <code>\`${siteConfig.title} Blog\`</code> | Description of the feed. |
|
||||
| `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
|
||||
|
|
@ -117,6 +118,17 @@ type ReadingTimeFn = (params: {
|
|||
type FeedType = 'rss' | 'atom' | 'json';
|
||||
```
|
||||
|
||||
#### `CreateFeedItemsFn` {#CreateFeedItemsFn}
|
||||
|
||||
```ts
|
||||
type CreateFeedItemsFn = (params: {
|
||||
blogPosts: BlogPost[];
|
||||
siteConfig: DocusaurusConfig;
|
||||
outDir: string;
|
||||
defaultCreateFeedItemsFn: CreateFeedItemsFn;
|
||||
}) => Promise<BlogFeedItem[]>;
|
||||
```
|
||||
|
||||
### Example configuration {#ex-config}
|
||||
|
||||
You can configure this plugin through preset options or plugin options.
|
||||
|
|
@ -168,6 +180,14 @@ const config = {
|
|||
description: '',
|
||||
copyright: '',
|
||||
language: undefined,
|
||||
createFeedItems: async (params) => {
|
||||
const {blogPosts, defaultCreateFeedItems, ...rest} = params;
|
||||
return defaultCreateFeedItems({
|
||||
// keep only the 10 most recent blog posts in the feed
|
||||
blogPosts: blogPosts.filter((item, index) => index < 10),
|
||||
...rest,
|
||||
});
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
|
|
|||
|
|
@ -9,6 +9,16 @@ import APITable from '@site/src/components/APITable';
|
|||
|
||||
The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. It is a JavaScript library for measuring how users interact with your website **in the production build**. If you are using Google Analytics 4 you might need to consider using [plugin-google-gtag](./plugin-google-gtag.md) instead.
|
||||
|
||||
:::danger Deprecated
|
||||
|
||||
This plugin is **deprecated**, and will become useless on July 1, 2023.
|
||||
|
||||
Google is [moving away from Universal Analytics](https://blog.google/products/marketingplatform/analytics/prepare-for-future-with-google-analytics-4/).
|
||||
|
||||
If you are still using this plugin with a `UA-*` tracking id, you should create a Google Analytics 4 account as soon as possible, and use [`@docusaurus/plugin-google-gtag`](./plugin-google-gtag.md) instead of this plugin. More details [here](https://github.com/facebook/docusaurus/issues/7221).
|
||||
|
||||
:::
|
||||
|
||||
:::caution production only
|
||||
|
||||
This plugin is always inactive in development and **only active in production** to avoid polluting the analytics statistics.
|
||||
|
|
|
|||
71
website/docs/api/plugins/plugin-google-tag-manager.md
Normal file
71
website/docs/api/plugins/plugin-google-tag-manager.md
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
---
|
||||
sidebar_position: 8
|
||||
slug: /api/plugins/@docusaurus/plugin-google-tag-manager
|
||||
---
|
||||
|
||||
# 📦 plugin-google-tag-manager
|
||||
|
||||
import APITable from '@site/src/components/APITable';
|
||||
|
||||
A plugin for adding [Google Tag Manager (gtm.js)](https://developers.google.com/tag-platform/tag-manager) to a Docusaurus site. Use this plugin in conjunction with the standard [gtag plugin](./plugin-google-gtag.md) for in-depth analysis of how users are using your site.
|
||||
|
||||
:::tip
|
||||
|
||||
You can use [Google's Tag Assistant](https://tagassistant.google.com/) tool to check if tag manager is set up correctly!
|
||||
|
||||
:::
|
||||
|
||||
:::caution production only
|
||||
|
||||
This plugin is always inactive in development and **only active in production** to avoid polluting the analytics statistics.
|
||||
|
||||
:::
|
||||
|
||||
## Installation {#installation}
|
||||
|
||||
```bash npm2yarn
|
||||
npm install --save @docusaurus/plugin-google-tag-manager
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
If you use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency.
|
||||
|
||||
You can configure this plugin through the preset options.
|
||||
|
||||
:::
|
||||
|
||||
## Configuration {#configuration}
|
||||
|
||||
Accepted fields:
|
||||
|
||||
```mdx-code-block
|
||||
<APITable>
|
||||
```
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `containerId` | `string` | **Required** | Your Tag Manager container Id (usually starts with `GTM-`). |
|
||||
|
||||
```mdx-code-block
|
||||
</APITable>
|
||||
```
|
||||
|
||||
### Example configuration {#ex-config}
|
||||
|
||||
You can configure this plugin through preset options or plugin options.
|
||||
|
||||
:::tip
|
||||
|
||||
Most Docusaurus users configure this plugin through the preset options.
|
||||
|
||||
:::
|
||||
|
||||
```js config-tabs
|
||||
// Preset Options: googleTagManager
|
||||
// Plugin Options: @docusaurus/plugin-google-tag-manager
|
||||
|
||||
const config = {
|
||||
containerId: 'GTM-12345',
|
||||
};
|
||||
```
|
||||
|
|
@ -511,6 +511,17 @@ type BlogOptions = {
|
|||
description?: string;
|
||||
copyright: string;
|
||||
language?: string; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
|
||||
/** Allow control over the construction of BlogFeedItems */
|
||||
createFeedItems?: (params: {
|
||||
blogPosts: BlogPost[];
|
||||
siteConfig: DocusaurusConfig;
|
||||
outDir: string;
|
||||
defaultCreateFeedItems: (params: {
|
||||
blogPosts: BlogPost[];
|
||||
siteConfig: DocusaurusConfig;
|
||||
outDir: string;
|
||||
}) => Promise<BlogFeedItem[]>;
|
||||
}) => Promise<BlogFeedItem[]>;
|
||||
};
|
||||
};
|
||||
```
|
||||
|
|
@ -529,6 +540,14 @@ module.exports = {
|
|||
feedOptions: {
|
||||
type: 'all',
|
||||
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
|
||||
createFeedItems: async (params) => {
|
||||
const {blogPosts, defaultCreateFeedItems, ...rest} = params;
|
||||
return defaultCreateFeedItems({
|
||||
// keep only the 10 most recent blog posts in the feed
|
||||
blogPosts: blogPosts.filter((item, index) => index < 10),
|
||||
...rest,
|
||||
});
|
||||
},
|
||||
},
|
||||
// highlight-end
|
||||
},
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ import Tabs from '@theme/Tabs';
|
|||
import TabItem from '@theme/TabItem';
|
||||
import Admonition from '@theme/Admonition';
|
||||
|
||||
In addition to the basic Markdown syntax, we use [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) alongside MDX to add support for admonitions. Admonitions are wrapped by a set of 3 colons.
|
||||
In addition to the basic Markdown syntax, we have a special admonitions syntax by wrapping text with a set of 3 colons, followed by a label denoting its type.
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -107,7 +107,7 @@ Hello world
|
|||
|
||||
## Specifying title {#specifying-title}
|
||||
|
||||
You may also specify an optional title
|
||||
You may also specify an optional title.
|
||||
|
||||
```md
|
||||
:::note Your Title
|
||||
|
|
@ -204,3 +204,128 @@ The types that are accepted are the same as above: `note`, `tip`, `danger`, `inf
|
|||
</Admonition>
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
## Customizing admonitions {#customizing-admonitions}
|
||||
|
||||
There are two kinds of customizations possible with admonitions: **parsing** and **rendering**.
|
||||
|
||||
### Customizing rendering behavior {#customizing-rendering-behavior}
|
||||
|
||||
You can customize how each individual admonition type is rendered through [swizzling](../../swizzling.md). You can often achieve your goal through a simple wrapper. For example, in the follow example, we swap out the icon for `info` admonitions only.
|
||||
|
||||
```jsx title="src/theme/Admonition.js"
|
||||
import React from 'react';
|
||||
import Admonition from '@theme-original/Admonition';
|
||||
import MyCustomNoteIcon from '@site/static/img/info.svg';
|
||||
|
||||
export default function AdmonitionWrapper(props) {
|
||||
if (props.type !== 'info') {
|
||||
return <Admonition title="My Custom Admonition Title" {...props} />;
|
||||
}
|
||||
return <Admonition icon={<MyCustomNoteIcon />} {...props} />;
|
||||
}
|
||||
```
|
||||
|
||||
### Customizing parsing behavior {#customizing-parsing-behavior}
|
||||
|
||||
Admonitions are implemented with a [Remark plugin](./markdown-features-plugins.mdx). The plugin is designed to be configurable. To customize the Remark plugin for a specific content plugin (docs, blog, pages), pass the options through the `admonitions` key.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
admonitions: {
|
||||
tag: ':::',
|
||||
keywords: ['note', 'tip', 'info', 'caution', 'danger'],
|
||||
extendDefaults: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
The plugin accepts the following options:
|
||||
|
||||
- `tag`: The tag that encloses the admonition. Defaults to `:::`.
|
||||
- `keywords`: An array of keywords that can be used as the type for the admonition.
|
||||
- `extendDefaults`: Should the provided options (such as `keywords`) be merged into the existing defaults. Defaults to `false`.
|
||||
|
||||
The `keyword` will be passed as the `type` prop of the `Admonition` component.
|
||||
|
||||
### Custom admonition type components {#custom-admonition-type-components}
|
||||
|
||||
By default, the theme doesn't know what do to with custom admonition keywords such as `:::my-custom-admonition`. It is your responsibility to map each admonition keyword to a React component so that the theme knows how to render them.
|
||||
|
||||
If you registered a new admonition type `my-custom-admonition` via the following config:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
'classic',
|
||||
{
|
||||
// ...
|
||||
docs: {
|
||||
admonitions: {
|
||||
tag: ':::',
|
||||
keywords: ['my-custom-admonition'],
|
||||
extendDefaults: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
You can provide the corresponding React component for `:::my-custom-admonition` by creating the following file (unfortunately, since it's not a React component file, it's not swizzlable):
|
||||
|
||||
```js title="src/theme/Admonition/Types.js"
|
||||
import React from 'react';
|
||||
import DefaultAdmonitionTypes from '@theme-original/Admonition/Types';
|
||||
|
||||
function MyCustomAdmonition(props) {
|
||||
return (
|
||||
<div style={{border: 'solid red', padding: 10}}>
|
||||
<h5 style={{color: 'blue', fontSize: 30}}>{props.title}</h5>
|
||||
<div>{props.children}</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
const AdmonitionTypes = {
|
||||
...DefaultAdmonitionTypes,
|
||||
|
||||
// Add all your custom admonition types here...
|
||||
// You can also override the default ones if you want
|
||||
'my-custom-admonition': MyCustomAdmonition,
|
||||
};
|
||||
|
||||
export default AdmonitionTypes;
|
||||
```
|
||||
|
||||
Now you can use your new admonition keyword in a Markdown file, and it will be parsed and rendered with your custom logic:
|
||||
|
||||
```md
|
||||
:::my-custom-admonition Custom Admonition
|
||||
|
||||
It works!
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
<BrowserWindow>
|
||||
|
||||
:::my-custom-admonition Custom Admonition
|
||||
|
||||
It works!
|
||||
|
||||
:::
|
||||
|
||||
</BrowserWindow>
|
||||
|
|
|
|||
|
|
@ -318,3 +318,63 @@ li[role='tab'][data-value='apple'] {
|
|||
```
|
||||
|
||||
:::
|
||||
|
||||
## Query string {#query-string}
|
||||
|
||||
It is possible to persist the selected tab into the url search parameters. This enables deep linking: the ability to share or bookmark a link to a specific tab, that will be pre-selected when the page loads.
|
||||
|
||||
Use the `queryString` prop to enable this feature and define the search param name to use.
|
||||
|
||||
```tsx
|
||||
// highlight-next-line
|
||||
<Tabs queryString="current-os">
|
||||
<TabItem value="android" label="Android">
|
||||
Android
|
||||
</TabItem>
|
||||
<TabItem value="ios" label="iOS">
|
||||
iOS
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<Tabs queryString='current-os'>
|
||||
<TabItem value="android" label="Android">Android</TabItem>
|
||||
<TabItem value="ios" label="iOS">iOS</TabItem>
|
||||
</Tabs>
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
As soon as a tab is clicked, a search parameter is added at the end of the url: `?current-os=android` or `?current-os=ios`.
|
||||
|
||||
:::tip
|
||||
|
||||
`queryString` can be used together with `groupId`.
|
||||
|
||||
For convenience, when the `queryString` prop is `true`, the `groupId` value will be used as a fallback.
|
||||
|
||||
```tsx
|
||||
// highlight-next-line
|
||||
<Tabs groupId="current-os" queryString>
|
||||
<TabItem value="android" label="Android">
|
||||
Android
|
||||
</TabItem>
|
||||
<TabItem value="ios" label="iOS">
|
||||
iOS
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<Tabs queryString groupId="current-os">
|
||||
<TabItem value="android" label="Android">Android</TabItem>
|
||||
<TabItem value="ios" label="iOS">iOS</TabItem>
|
||||
</Tabs>
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
When the page loads, the tab query string choice will be restored in priority over the `groupId` choice (using `localStorage`).
|
||||
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -104,6 +104,12 @@ module.exports = {
|
|||
// Optional: Specify domains where the navigation should occur through window.location instead on history.push. Useful when our Algolia config crawls multiple documentation sites and we want to navigate with window.location.href to them.
|
||||
externalUrlRegex: 'external\\.com|domain\\.com',
|
||||
|
||||
// Optional: Replace parts of the item URLs from Algolia. Useful when using the same search index for multiple deployments using a different baseUrl. You can use regexp or string in the `from` param. For example: localhost:3000 vs myCompany.com/docs
|
||||
replaceSearchResultPathname: {
|
||||
from: '/docs/', // or as RegExp: /\/docs\//
|
||||
to: '/',
|
||||
},
|
||||
|
||||
// Optional: Algolia search parameters
|
||||
searchParameters: {},
|
||||
|
||||
|
|
|
|||
|
|
@ -144,8 +144,9 @@ The classic preset is shipped by default to new Docusaurus websites created with
|
|||
- [`@docusaurus/plugin-content-blog`](./api/plugins/plugin-content-blog.md)
|
||||
- [`@docusaurus/plugin-content-pages`](./api/plugins/plugin-content-pages.md)
|
||||
- [`@docusaurus/plugin-debug`](./api/plugins/plugin-debug.md)
|
||||
- [`@docusaurus/plugin-google-analytics`](./api/plugins/plugin-google-analytics.md)
|
||||
- [`@docusaurus/plugin-google-gtag`](./api/plugins/plugin-google-gtag.md)
|
||||
- [`@docusaurus/plugin-google-tag-manager`](./api/plugins/plugin-google-tag-manager.md)
|
||||
- [`@docusaurus/plugin-google-analytics`](./api/plugins/plugin-google-analytics.md) (**deprecated**)
|
||||
- [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.md)
|
||||
|
||||
The classic preset will relay each option entry to the respective plugin/theme.
|
||||
|
|
@ -172,7 +173,9 @@ module.exports = {
|
|||
sitemap: {},
|
||||
// Will be passed to @docusaurus/plugin-google-gtag (only enabled when explicitly specified)
|
||||
gtag: {},
|
||||
// Will be passed to @docusaurus/plugin-google-analytics (only enabled when explicitly specified)
|
||||
// Will be passed to @docusaurus/plugin-google-tag-manager (only enabled when explicitly specified)
|
||||
googleTagManager: {},
|
||||
// DEPRECATED: Will be passed to @docusaurus/plugin-google-analytics (only enabled when explicitly specified)
|
||||
googleAnalytics: {},
|
||||
},
|
||||
],
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue