chore: backport retro compatible commits for the Docusaurus v2.2 release (#8264)

Co-authored-by: Jan Peer Stoecklmair <jan.peer.stoecklmair@dynatrace.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: LittleboyHarry <littleboyharry@qq.com>
Co-authored-by: Mikey O'Toole <mikey@homotechsual.dev>
Co-authored-by: Jan Peer Stöcklmair <jan.oster94@gmail.com>
Co-authored-by: Nguyễn Thành Nam <namnguyenthanh.work@gmail.com>
Co-authored-by: Sanjaiyan Parthipan <parthipankalayini@gmail.com>
Co-authored-by: Ramazan SANCAR <ramazansancar4545@gmail.com>
Co-authored-by: mturoci <64769322+mturoci@users.noreply.github.com>
Co-authored-by: Adnan Hashmi <56730784+adnanhashmi09@users.noreply.github.com>
Co-authored-by: Pranav Joglekar <pranav2000joglekar@gmail.com>
Co-authored-by: forgeRW <20483211+forgeRW@users.noreply.github.com>
Co-authored-by: Masahiko Hara <pasora@sfc.wide.ad.jp>
Co-authored-by: Johan Fagerberg <johanringmann@gmail.com>
Co-authored-by: John Reilly <johnny_reilly@hotmail.com>
Co-authored-by: Sam Wall <oss@samuelwall.co.uk>
Co-authored-by: Jeferson S. Brito <30840709+jeferson-sb@users.noreply.github.com>
Co-authored-by: evan <evanmccarthy@outlook.com>
Co-authored-by: Xabier Lahuerta Vazquez <xlahuerta@protonmail.com>
Co-authored-by: Forresst <forresst17@gmail.com>
Co-authored-by: Shanmughapriyan S <priyanshan03@gmail.com>
Co-authored-by: Alexey Pyltsyn <lex61rus@gmail.com>
This commit is contained in:
Sébastien Lorber 2022-10-29 15:13:42 +02:00 committed by GitHub
parent 7743aa6307
commit de972142a8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
155 changed files with 2822 additions and 563 deletions

View file

@ -0,0 +1,15 @@
---
title: A post with html slug
tags: [paginated-tag]
slug: /x/y/z.html
---
# Hmmm!
This is a blog post with an html slug!
```mdx-code-block
import Partial from "./_partial.mdx"
<Partial />
```

View file

@ -0,0 +1 @@
Dogfood test for https://github.com/facebook/docusaurus/pull/8137

View file

@ -0,0 +1 @@
Dogfood test for https://github.com/facebook/docusaurus/pull/8137

View file

@ -0,0 +1,316 @@
# Diagram Examples
## Sequence Diagram
```mermaid
sequenceDiagram
participant Alice
participant Bob
Alice->>John: Hello John, how are you?
loop Health check
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
```
## Sequence Diagram (forest theme directive)
It is possible to override default config locally with Mermaid text directives such as:
```
%%{init: { "theme": "forest" } }%%
```
```mermaid
%%{init: { "theme": "forest" } }%%
sequenceDiagram
participant Alice
participant Bob
Alice->>John: Hello John, how are you?
loop Health check
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
```
## Gantt Chart
```mermaid
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram to mermaid
excludes weekdays 2014-01-10
section A section
Completed task :done, des1, 2014-01-06,2014-01-08
Active task :active, des2, 2014-01-09, 3d
Future task : des3, after des2, 5d
Future task2 : des4, after des3, 5d
```
## Flow Chart
```mermaid
flowchart TD
A[Start] --> B{Is it?}
B -->|Yes| C[OK]
C --> D[Rethink]
D --> B
B ---->|No| E[End]
```
## Class Diagram
```mermaid
classDiagram
Animal <|-- Duck
Animal <|-- Fish
Animal <|-- Zebra
Animal : +int age
Animal : +String gender
Animal: +isMammal()
Animal: +mate()
class Duck{
+String beakColor
+swim()
+quack()
}
class Fish{
-int sizeInFeet
-canEat()
}
class Zebra{
+bool is_wild
+run()
}
```
## State Diagram
```mermaid
stateDiagram-v2
[*] --> Active
state Active {
[*] --> NumLockOff
NumLockOff --> NumLockOn : EvNumLockPressed
NumLockOn --> NumLockOff : EvNumLockPressed
--
[*] --> CapsLockOff
CapsLockOff --> CapsLockOn : EvCapsLockPressed
CapsLockOn --> CapsLockOff : EvCapsLockPressed
--
[*] --> ScrollLockOff
ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
}
```
## Entity Relationship Diagram
```mermaid
erDiagram
CAR ||--o{ NAMED-DRIVER : allows
CAR {
string registrationNumber
string make
string model
}
PERSON ||--o{ NAMED-DRIVER : is
PERSON {
string firstName
string lastName
int age
}
```
## User Journey
```mermaid
journey
title My working day
section Go to work
Make tea: 5: Me
Go upstairs: 3: Me
Do work: 1: Me, Cat
section Go home
Go downstairs: 5: Me
Sit down: 5: Me
```
:::note
If there's too much space above it's due to a [Mermaid bug](https://github.com/mermaid-js/mermaid/issues/3501)
:::
## Pie Chart
```mermaid
pie showData
title Key elements in Product X
"Calcium" : 42.96
"Potassium" : 50.05
"Magnesium" : 10.01
"Iron" : 5
```
## Requirement Diagram
```mermaid
requirementDiagram
requirement test_req {
id: 1
text: the test text.
risk: high
verifymethod: test
}
functionalRequirement test_req2 {
id: 1.1
text: the second test text.
risk: low
verifymethod: inspection
}
performanceRequirement test_req3 {
id: 1.2
text: the third test text.
risk: medium
verifymethod: demonstration
}
interfaceRequirement test_req4 {
id: 1.2.1
text: the fourth test text.
risk: medium
verifymethod: analysis
}
physicalRequirement test_req5 {
id: 1.2.2
text: the fifth test text.
risk: medium
verifymethod: analysis
}
designConstraint test_req6 {
id: 1.2.3
text: the sixth test text.
risk: medium
verifymethod: analysis
}
element test_entity {
type: simulation
}
element test_entity2 {
type: word doc
docRef: reqs/test_entity
}
element test_entity3 {
type: "test suite"
docRef: github.com/all_the_tests
}
test_entity - satisfies -> test_req2
test_req - traces -> test_req2
test_req - contains -> test_req3
test_req3 - contains -> test_req4
test_req4 - derives -> test_req5
test_req5 - refines -> test_req6
test_entity3 - verifies -> test_req5
test_req <- copies - test_entity2
```
## Gitgraph (Git) Diagram
```mermaid
%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%%
gitGraph
commit
branch hotfix
checkout hotfix
commit
branch develop
checkout develop
commit id:"ash" tag:"abc"
branch featureB
checkout featureB
commit type:HIGHLIGHT
checkout main
checkout hotfix
commit type:NORMAL
checkout develop
commit type:REVERSE
checkout featureB
commit
checkout main
merge hotfix
checkout featureB
commit
checkout develop
branch featureA
commit
checkout develop
merge hotfix
checkout featureA
commit
checkout featureB
commit
checkout develop
merge featureA
branch release
checkout release
commit
checkout main
commit
checkout release
merge main
checkout develop
merge release
```
## Mermaid in tabs
````mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs>
<TabItem value="tab-a">
The following mermaid diagram is shown:
```mermaid
graph LR
a ---> c(10)
b ---> c(10)
```
</TabItem>
<TabItem value="tab-b">
This mermaid diagram is not displayed:
```mermaid
graph LR
d ---> z(42)
e ---> z(42)
```
</TabItem>
</Tabs>
````

View file

@ -27,6 +27,7 @@ import Readme from "../README.md"
- [Asset linking tests](/tests/pages/markdown-tests)
- [General Markdown tests](/tests/pages/markdownPageTests)
- [TOC tests](/tests/pages/page-toc-tests)
- [Diagram tests](/tests/pages/diagrams)
- [Tabs tests](/tests/pages/tabs-tests)
- [z-index tests](/tests/pages/z-index-tests)
- [Head metadata tests](/tests/pages/head-metadata)

View file

@ -45,7 +45,6 @@ See the <a href={require('@docusaurus/useBaseUrl').default('showcase')}>showcase
- [docusaurus-plugin-module-alias](https://github.com/atomicpages/docusaurus-plugin-module-alias) - A Docusaurus v2 plugin for quickly aliasing local modules
- [docusaurus-protobuffet](https://github.com/protobuffet/docusaurus-protobuffet) - Docusaurus toolset for Protobuf contract documentation
- [docusaurus-prince-pdf](https://github.com/signcl/docusaurus-prince-pdf) - Generate PDF with PrinceXML for better font subsetting and ToC features. Support Docusaurus v2 sites
- [mdx-mermaid](https://github.com/sjwall/mdx-mermaid) - A Docusaurus v2 compatible MDX plugin for displaying [Mermaid](https://mermaid-js.github.io/mermaid) diagrams
- [redocusaurus](https://github.com/rohit-gohri/redocusaurus) - A Docusaurus preset for integrating OpenAPI documentation into your docs with [Redoc](https://github.com/redocly/redoc)
- [plugin-image-zoom](https://github.com/flexanalytics/plugin-image-zoom) - An Image Zoom plugin for Docusaurus 2
- [docusaurus-plugin-typedoc](https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/docusaurus-plugin-typedoc) - A Docusaurus 2 plugin to build documentation with [TypeDoc](https://typedoc.org/)

View file

@ -429,6 +429,30 @@ module.exports = {
};
```
### `headTags` {#headTags}
An array of tags that will be inserted in the HTML `<head>`. The values must be objects that contain two properties; `tagName` and `attributes`. `tagName` must be a string that determines the tag being created; eg `"link"`. `attributes` must be an attribute-value map.
- Type: `{ tagName: string; attributes: Object; }[]`
Example:
```js title="docusaurus.config.js"
module.exports = {
headTags: [
{
tagName: 'link',
attributes: {
rel: 'icon',
href: '/img/docusaurus.png',
},
},
],
};
```
This would become `<link rel="icon" href="img/docusaurus.png" />` in the generated HTML.
### `scripts` {#scripts}
An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The `<script>` tags will be inserted in the HTML `<head>`. If you use a plain object, the only required attribute is `src`, and any other attributes are permitted (each one should have boolean/string values).

View file

@ -113,15 +113,16 @@ The swizzle CLI is interactive and will guide you through the whole [swizzle pro
#### Options {#options-swizzle}
| Name | Description |
| --------------- | ---------------------------------------------------- |
| `themeName` | The name of the theme to swizzle from. |
| `componentName` | The name of the theme component to swizzle. |
| `--list` | Display components available for swizzling |
| `--eject` | [Eject](./swizzling.md#ejecting) the theme component |
| `--wrap` | [Wrap](./swizzling.md#wrapping) the theme component |
| `--danger` | Allow immediate swizzling of unsafe components |
| `--typescript` | Swizzle the TypeScript variant component |
| Name | Description |
| --- | --- |
| `themeName` | The name of the theme to swizzle from. |
| `componentName` | The name of the theme component to swizzle. |
| `--list` | Display components available for swizzling |
| `--eject` | [Eject](./swizzling.md#ejecting) the theme component |
| `--wrap` | [Wrap](./swizzling.md#wrapping) the theme component |
| `--danger` | Allow immediate swizzling of unsafe components |
| `--typescript` | Swizzle the TypeScript variant component |
| `--config` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
:::caution

View file

@ -0,0 +1,85 @@
---
id: diagrams
title: Diagrams
description: Writing diagrams with Mermaid
slug: /markdown-features/diagrams
---
# Diagrams
Diagrams can be rendered using [Mermaid](https://mermaid-js.github.io/mermaid/) in a code block.
## Installation {#installation}
```bash npm2yarn
npm install --save @docusaurus/theme-mermaid
```
Enable Mermaid functionality by adding plugin `@docusaurus/theme-mermaid` and setting `markdown.mermaid` to `true` in your `docusaurus.config.js`.
```js title="docusaurus.config.js"
module.exports = {
markdown: {
mermaid: true,
},
themes: ['@docusaurus/theme-mermaid'],
};
```
## Usage {#usage}
Add a code block with language `mermaid`:
````md title="Example Mermaid diagram"
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
````
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
See the [Mermaid syntax documentation](https://mermaid-js.github.io/mermaid/#/./n00b-syntaxReference) for more information on the Mermaid syntax.
## Theming {#theming}
The diagram dark and light themes can be changed by setting `mermaid.theme` values in the `themeConfig` in your `docusaurus.config.js`. You can set themes for both light and dark mode.
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
mermaid: {
theme: {light: 'neutral', dark: 'forest'},
},
},
};
```
See the [Mermaid theme documentation](https://mermaid-js.github.io/mermaid/#/theming) for more information on theming Mermaid diagrams.
## Mermaid Config {#configuration}
Options in `mermaid.mermaidOptions` will be passed directly to `mermaid.initialize`:
```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
mermaid: {
mermaidOptions: {
maxTextSize: 50,
},
},
},
};
```
See the [Mermaid configuration documentation](https://mermaid-js.github.io/mermaid/#/./Setup?id=configuration) for the available config options.

View file

@ -35,12 +35,6 @@ function getNextVersionName() {
return `${expectedPrefix}${version + 1}`;
}
const allDocHomesPaths = [
'/docs/',
'/docs/next/',
...versions.slice(1).map((version) => `/docs/${version}/`),
];
const isDev = process.env.NODE_ENV === 'development';
const isDeployPreview =
@ -114,6 +108,9 @@ const config = {
},
}),
},
markdown: {
mermaid: true,
},
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
favicon: 'img/docusaurus.ico',
@ -180,9 +177,8 @@ const config = {
({
fromExtensions: ['html'],
createRedirects(routePath) {
// Redirect to /docs from /docs/introduction, as introduction has been
// made the home doc
if (allDocHomesPaths.includes(routePath)) {
// Redirect to /docs from /docs/introduction (now docs root doc)
if (routePath === '/docs' || routePath === '/docs/') {
return [`${routePath}/introduction`];
}
return [];
@ -276,6 +272,7 @@ const config = {
],
},
],
'@docusaurus/theme-mermaid',
...dogfoodingPluginInstances,
],
presets: [

View file

@ -1,6 +1,6 @@
{
"name": "website",
"version": "2.1.0",
"version": "2.2.0",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
@ -36,18 +36,19 @@
"dependencies": {
"@crowdin/cli": "^3.7.9",
"@crowdin/crowdin-api-client": "^1.18.2",
"@docusaurus/core": "2.1.0",
"@docusaurus/logger": "2.1.0",
"@docusaurus/plugin-client-redirects": "2.1.0",
"@docusaurus/plugin-ideal-image": "2.1.0",
"@docusaurus/plugin-pwa": "2.1.0",
"@docusaurus/preset-classic": "2.1.0",
"@docusaurus/remark-plugin-npm2yarn": "2.1.0",
"@docusaurus/theme-classic": "2.1.0",
"@docusaurus/theme-common": "2.1.0",
"@docusaurus/theme-live-codeblock": "2.1.0",
"@docusaurus/utils": "2.1.0",
"@docusaurus/utils-common": "2.1.0",
"@docusaurus/core": "2.2.0",
"@docusaurus/logger": "2.2.0",
"@docusaurus/plugin-client-redirects": "2.2.0",
"@docusaurus/plugin-ideal-image": "2.2.0",
"@docusaurus/plugin-pwa": "2.2.0",
"@docusaurus/preset-classic": "2.2.0",
"@docusaurus/remark-plugin-npm2yarn": "2.2.0",
"@docusaurus/theme-classic": "2.2.0",
"@docusaurus/theme-common": "2.2.0",
"@docusaurus/theme-live-codeblock": "2.2.0",
"@docusaurus/theme-mermaid": "2.2.0",
"@docusaurus/utils": "2.2.0",
"@docusaurus/utils-common": "2.2.0",
"@popperjs/core": "^2.11.5",
"@swc/core": "1.2.197",
"clsx": "^1.2.1",
@ -81,7 +82,7 @@
]
},
"devDependencies": {
"@docusaurus/eslint-plugin": "2.1.0",
"@docusaurus/eslint-plugin": "2.2.0",
"@tsconfig/docusaurus": "^1.0.5",
"@types/jest": "^28.1.4",
"cross-env": "^7.0.3",

View file

@ -82,6 +82,7 @@ const sidebars = {
'guides/markdown-features/links',
'guides/markdown-features/plugins',
'guides/markdown-features/math-equations',
'guides/markdown-features/diagrams',
'guides/markdown-features/head-metadata',
],
},