mirror of
https://github.com/facebook/docusaurus.git
synced 2025-07-19 17:49:19 +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
|
|
@ -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`).
|
||||
|
||||
:::
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue