mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-03 16:59:06 +02:00
feat: upgrade to MDX v2 (#8288)
Co-authored-by: Armano <armano2@users.noreply.github.com>
This commit is contained in:
Sébastien Lorber
GitHub
parent
10f161d578
commit
bf913aea2a
161 changed files with 4028 additions and 2821 deletions
|
|
@ -7,7 +7,7 @@ toc_max_heading_level: 4
|
|||
tags: [paginated-tag]
|
||||
---
|
||||
|
||||
<!-- truncate -->
|
||||
{/* truncate */}
|
||||
|
||||
import Content, {
|
||||
toc as ContentToc,
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ hide_reading_time: true
|
|||
|
||||
Some MDX tests, mostly to test how the RSS feed render those
|
||||
|
||||
<!-- truncate -->
|
||||
{/* truncate */}
|
||||
|
||||
## Imports
|
||||
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ tags:
|
|||
|
||||
Some MDX tests, mostly to test how the RSS feed render those
|
||||
|
||||
<!-- truncate -->
|
||||
{/* truncate */}
|
||||
|
||||
Test MDX with require calls
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ tags: [paginated-tag, blog, docusaurus]
|
|||
|
||||
Did you know you can use multiple instances of the same plugin?
|
||||
|
||||
<!--truncate-->
|
||||
{/* truncate */}
|
||||
|
||||
:::tip
|
||||
|
||||
|
|
|
|||
|
|
@ -16,24 +16,22 @@
|
|||
|
||||
## Large font icon
|
||||
|
||||
import Admonition from '@theme/Admonition';
|
||||
|
||||
```mdx-code-block
|
||||
<admonition
|
||||
<Admonition
|
||||
type="tip"
|
||||
icon={<span style={{fontSize: 60}}>💡</span>}
|
||||
title="Did you know...">
|
||||
<p>
|
||||
content
|
||||
</p>
|
||||
</admonition>
|
||||
</Admonition>
|
||||
|
||||
<admonition
|
||||
<Admonition
|
||||
type="info"
|
||||
icon={<span style={{fontSize: 40}}>ℹ️</span>}
|
||||
title="Did you know...">
|
||||
<p>
|
||||
content
|
||||
</p>
|
||||
</admonition>
|
||||
</Admonition>
|
||||
```
|
||||
|
||||
## Large svg icon
|
||||
|
|
@ -41,21 +39,17 @@
|
|||
```mdx-code-block
|
||||
import InfoIcon from "@theme/Admonition/Icon/Info"
|
||||
|
||||
<admonition
|
||||
<Admonition
|
||||
type="tip"
|
||||
icon={<InfoIcon style={{width: 60, height: 60}}/>}
|
||||
title="Did you know...">
|
||||
<p>
|
||||
content
|
||||
</p>
|
||||
</admonition>
|
||||
</Admonition>
|
||||
|
||||
<admonition
|
||||
<Admonition
|
||||
type="info"
|
||||
icon={<InfoIcon style={{width: 40, height: 40}}/>}
|
||||
title="Did you know...">
|
||||
<p>
|
||||
content
|
||||
</p>
|
||||
</admonition>
|
||||
</Admonition>
|
||||
```
|
||||
|
|
|
|||
|
|
@ -5,6 +5,14 @@ import TabItem from '@theme/TabItem';
|
|||
|
||||
# Code block tests
|
||||
|
||||
:::danger legacy test page - MDX v1
|
||||
|
||||
This test page is quite outdated: MDX v2 lowercase tags are not substituted anymore in the same way as they were in v1.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
```java
|
||||
class HelloWorld {
|
||||
public static void main(String args[]) {
|
||||
|
|
@ -27,7 +35,7 @@ Multi-line text inside `pre` will turn into one-liner, but it's okay (https://gi
|
|||
|
||||
<pre>1 2 3</pre>
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
<pre>
|
||||
1
|
||||
2
|
||||
|
|
|
|||
|
|
@ -18,6 +18,11 @@ import Readme from "../README.mdx"
|
|||
<Readme />
|
||||
```
|
||||
|
||||
### Markdown tests
|
||||
|
||||
- [Markdown tests MDX](/tests/pages/markdown-tests-mdx)
|
||||
- [Markdown tests MD](/tests/pages/markdown-tests-md)
|
||||
|
||||
### Other tests
|
||||
|
||||
- [Crash test](/tests/pages/crashTest)
|
||||
|
|
@ -25,8 +30,6 @@ import Readme from "../README.mdx"
|
|||
- [Link tests](/tests/pages/link-tests)
|
||||
- [Error boundary tests](/tests/pages/error-boundary-tests)
|
||||
- [Hydration tests](/tests/pages/hydration-tests)
|
||||
- [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)
|
||||
|
|
|
|||
44
website/_dogfooding/_pages tests/markdown-tests-md.md
Normal file
44
website/_dogfooding/_pages tests/markdown-tests-md.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
title: Markdown Page tests title
|
||||
description: Markdown Page tests description
|
||||
wrapperClassName: docusaurus-markdown-example
|
||||
---
|
||||
|
||||
# Markdown .md tests
|
||||
|
||||
This file should be interpreted in a more CommonMark compliant way
|
||||
|
||||
## Comment
|
||||
|
||||
Html comment: <!-- comment -->
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
MDX comment: {/* comment */}
|
||||
|
||||
## JSX syntax
|
||||
|
||||
import BrowserWindow from '@site/src/components/BrowserWindow';
|
||||
|
||||
<BrowserWindow>
|
||||
|
||||
BrowserWindow content
|
||||
|
||||
<BrowserWindow/>
|
||||
|
||||
export const answer = 42;
|
||||
|
||||
Test {xyz}
|
||||
|
||||
## Admonition
|
||||
|
||||
Admonitions still work
|
||||
|
||||
:::note[title]
|
||||
|
||||
note
|
||||
|
||||
:::
|
||||
|
||||
## Heading Id {#custom-heading-id}
|
||||
|
||||
Custom heading syntax `{#custom-heading-id}` still works
|
||||
|
|
@ -4,7 +4,7 @@ description: Markdown Page tests description
|
|||
wrapperClassName: docusaurus-markdown-example
|
||||
---
|
||||
|
||||
# Markdown page tests
|
||||
# Markdown .mdx tests
|
||||
|
||||
This is a page generated from Markdown to illustrate the Markdown page feature and test some edge cases.
|
||||
|
||||
|
|
@ -51,20 +51,12 @@ import TabItem from '@theme/TabItem';
|
|||
MDX comments can be used with
|
||||
|
||||
```mdx
|
||||
<!--
|
||||
|
||||
My comment
|
||||
|
||||
-->
|
||||
{/* My comment */}
|
||||
```
|
||||
|
||||
See, nothing is displayed:
|
||||
|
||||
<!--
|
||||
|
||||
My comment
|
||||
|
||||
-->
|
||||
{/* My comment */}
|
||||
|
||||
## Import code block from source code file
|
||||
|
||||
|
|
@ -180,7 +172,7 @@ function Clock(props) {
|
|||
|
||||
### Weird heading {#a b}
|
||||
|
||||
### Weird heading {#a{b}
|
||||
### Weird heading {#a\{b}
|
||||
|
||||
## Pipe
|
||||
|
||||
|
|
@ -247,9 +239,19 @@ Can be arbitrarily nested:
|
|||
- [ ] Task
|
||||
- [ ] Task
|
||||
|
||||
## Emojis
|
||||
|
||||
Emojis in this text will be replaced with [remark-emoji](https://www.npmjs.com/package/remark-emoji): :dog: :+1:
|
||||
|
||||
## Admonitions
|
||||
|
||||
:::caution Interpolated `title` with a <button style={{color: "red"}} onClick={() => alert("it works")}>button</button>
|
||||
:::caution Interpolated `title` with a <button style={{color: "red"}} onClick={() => alert("it works")}>button</button> (old syntax)
|
||||
|
||||
Admonition body
|
||||
|
||||
:::
|
||||
|
||||
:::caution[Interpolated `title` with a <button style={{color: "red"}} onClick={() => alert("it works")}>button</button> (directive label syntax)]
|
||||
|
||||
Admonition body
|
||||
|
||||
|
|
@ -281,4 +283,60 @@ hey
|
|||
|
||||
:::::
|
||||
|
||||
after admonition
|
||||
::::tip[Use tabs in admonitions]
|
||||
|
||||
:::info[Admonition nested]
|
||||
|
||||
test
|
||||
|
||||
:::
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">
|
||||
|
||||
:::note[Admonition in tab]
|
||||
|
||||
test
|
||||
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="orange" label="Orange">This is an orange 🍊</TabItem>
|
||||
<TabItem value="banana" label="Banana">This is a banana 🍌</TabItem>
|
||||
</Tabs>
|
||||
|
||||
::::
|
||||
|
||||
## Linking
|
||||
|
||||
This is a test page to see if Docusaurus Markdown features are working properly
|
||||
|
||||
### Linking to assets
|
||||
|
||||
See [#3337](https://github.com/facebook/docusaurus/issues/3337)
|
||||
|
||||
- [/someFile.pdf](/someFile.pdf)
|
||||
|
||||
- [/someFile.xyz](/someFile.xyz)
|
||||
|
||||
- [@site/\_dogfooding/\_asset-tests/someFile.pdf](@site/_dogfooding/_asset-tests/someFile.pdf)
|
||||
|
||||
- [@site/\_dogfooding/\_asset-tests/someFile.xyz](@site/_dogfooding/_asset-tests/someFile.xyz)
|
||||
|
||||
### Linking to non-SPA page hosted within website
|
||||
|
||||
See [#3309](https://github.com/facebook/docusaurus/issues/3309)
|
||||
|
||||
- [pathname:///dogfooding/javadoc](pathname:///dogfooding/javadoc)
|
||||
|
||||
- [pathname:///dogfooding/javadoc/index.html](pathname:///dogfooding/javadoc/index.html)
|
||||
|
||||
- [pathname://../dogfooding/javadoc](pathname://../dogfooding/javadoc)
|
||||
|
||||
- [pathname://../dogfooding/javadoc/index.html](pathname://../dogfooding/javadoc/index.html)
|
||||
|
||||
### Linking to JSON
|
||||
|
||||
- [./script.js](./_script.js)
|
||||
|
||||
- [./data.json](./data.json)
|
||||
|
|
@ -1,33 +0,0 @@
|
|||
# Markdown tests
|
||||
|
||||
This is a test page to see if Docusaurus Markdown features are working properly
|
||||
|
||||
## Linking to assets
|
||||
|
||||
See [#3337](https://github.com/facebook/docusaurus/issues/3337)
|
||||
|
||||
- [/someFile.pdf](/someFile.pdf)
|
||||
|
||||
- [/someFile.xyz](/someFile.xyz)
|
||||
|
||||
- [@site/\_dogfooding/\_asset-tests/someFile.pdf](@site/_dogfooding/_asset-tests/someFile.pdf)
|
||||
|
||||
- [@site/\_dogfooding/\_asset-tests/someFile.xyz](@site/_dogfooding/_asset-tests/someFile.xyz)
|
||||
|
||||
## Linking to non-SPA page hosted within website
|
||||
|
||||
See [#3309](https://github.com/facebook/docusaurus/issues/3309)
|
||||
|
||||
- [pathname:///dogfooding/javadoc](pathname:///dogfooding/javadoc)
|
||||
|
||||
- [pathname:///dogfooding/javadoc/index.html](pathname:///dogfooding/javadoc/index.html)
|
||||
|
||||
- [pathname://../dogfooding/javadoc](pathname://../dogfooding/javadoc)
|
||||
|
||||
- [pathname://../dogfooding/javadoc/index.html](pathname://../dogfooding/javadoc/index.html)
|
||||
|
||||
## Linking to JSON
|
||||
|
||||
- [./script.js](./_script.js)
|
||||
|
||||
- [./data.json](./data.json)
|
||||
|
|
@ -21,15 +21,12 @@ It all started with this [RFC issue](https://github.com/facebook/docusaurus/issu
|
|||
<blockquote>
|
||||
<h4>
|
||||
<a href="https://github.com/facebook/docusaurus/issues/789">
|
||||
[RFC] Docusaurus v2 · Issue #789 · facebook/docusaurus
|
||||
{'[RFC] Docusaurus v2 · Issue #789 · facebook/docusaurus'}
|
||||
</a>
|
||||
</h4>
|
||||
<p>
|
||||
These are some of the problems I'm seeing in Docusaurus now and also how we
|
||||
can address them in v2. A number of the ideas here were inspired by VuePress
|
||||
and other static site generators. In the current static site generators
|
||||
ecosystem, t...
|
||||
</p>
|
||||
These are some of the problems I'm seeing in Docusaurus now and also how we can
|
||||
address them in v2. A number of the ideas here were inspired by VuePress and other
|
||||
static site generators. In the current static site generators ecosystem, t...
|
||||
</blockquote>
|
||||
|
||||
Most of the suggested improvements are mentioned in the issue; I will provide details on some of issues in Docusaurus 1 and how we are going to address them in Docusaurus 2.
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ After **4 years of work, [75 alphas](https://github.com/facebook/docusaurus/rele
|
|||
|
||||
|
||||
|
||||
<!--truncate-->
|
||||
{/* truncate */}
|
||||
|
||||
:::info We are on [ProductHunt](https://www.producthunt.com/posts/docusaurus-2-0) and [Hacker News](https://news.ycombinator.com/item?id=32303052)!
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ The upgrade should be easy: as explained in our [release process documentation](
|
|||
|
||||
|
||||
|
||||
<!--truncate-->
|
||||
{/* truncate */}
|
||||
|
||||
## Highlights
|
||||
|
||||
|
|
|
|||
|
|
@ -123,7 +123,7 @@ The i18n configuration object to [localize your site](../i18n/i18n-introduction.
|
|||
|
||||
Example:
|
||||
|
||||
<!-- cSpell:ignore فارسی -->
|
||||
{/* cSpell:ignore فارسی */}
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ Accepted fields:
|
|||
| `rehypePlugins` | `any[]` | `[]` | Rehype plugins passed to MDX. |
|
||||
| `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. |
|
||||
| `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. |
|
||||
| `truncateMarker` | `RegExp` | `/<!--\s*(truncate)\s*-->/` | Truncate marker marking where the summary ends. |
|
||||
| `truncateMarker` | `RegExp` | `/<!--\s*truncate\s*-->/` \| `\{\/\*\s*truncate\s*\*\/\}/` | Truncate marker marking where the summary ends. |
|
||||
| `showReadingTime` | `boolean` | `true` | Show estimated reading time for the blog post. |
|
||||
| `readingTime` | `ReadingTimeFn` | The default reading time | A callback to customize the reading time number displayed. |
|
||||
| `authorsMapPath` | `string` | `'authors.yml'` | Path to the authors map file, relative to the blog content directory. |
|
||||
|
|
@ -69,7 +69,7 @@ Accepted fields:
|
|||
| `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.description` | `string` | <code>\`$\{siteConfig.title} Blog\`</code> | Description of the feed. |
|
||||
| `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
|
||||
| `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. |
|
||||
| `sortPosts` | <code>'descending' \| 'ascending' </code> | `'descending'` | Governs the direction of blog post sorting. |
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ hide_table_of_contents: false
|
|||
|
||||
Welcome to this blog. This blog is created with [**Docusaurus 2**](https://docusaurus.io/).
|
||||
|
||||
<!--truncate-->
|
||||
<!-- truncate -->
|
||||
|
||||
This is my first post on Docusaurus 2.
|
||||
|
||||
|
|
@ -78,22 +78,31 @@ The blog's index page (by default, it is at `/blog`) is the _blog list page_, wh
|
|||
|
||||
Use the `<!--truncate-->` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `<!--truncate-->` will be part of the summary. For example:
|
||||
|
||||
```md
|
||||
```md title="website/blog/my-post.md" {7}
|
||||
---
|
||||
title: Truncation Example
|
||||
title: Markdown blog truncation example
|
||||
---
|
||||
|
||||
All these will be part of the blog post summary.
|
||||
|
||||
Even this.
|
||||
|
||||
<!--truncate-->
|
||||
<!-- truncate -->
|
||||
|
||||
But anything from here on down will not be.
|
||||
```
|
||||
|
||||
Not this.
|
||||
For files using the `.mdx` extension, use a [MDX](https://mdxjs.com/) comment `{/* truncate */}` instead:
|
||||
|
||||
Or this.
|
||||
{/* prettier-ignore */}
|
||||
```md title="website/blog/my-post.mdx" {7}
|
||||
---
|
||||
title: MDX blog truncation Example
|
||||
---
|
||||
|
||||
All these will be part of the blog post summary.
|
||||
|
||||
{/* truncate */}
|
||||
|
||||
But anything from here on down will not be.
|
||||
```
|
||||
|
||||
By default, 10 posts are shown on each blog list page, but you can control pagination with the `postsPerPage` option in the plugin configuration. If you set `postsPerPage: 'ALL'`, pagination will be disabled and all posts will be displayed on the first page. You can also add a meta description to the blog list page for better SEO:
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@ Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
|
|||
|
||||
If you use [Prettier](https://prettier.io) to format your Markdown files, Prettier might auto-format your code to invalid admonition syntax. To avoid this problem, add empty lines around the starting and ending directives. This is also why the examples we show here all have empty lines around the content.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```md
|
||||
<!-- Prettier doesn't change this -->
|
||||
:::note
|
||||
|
|
@ -110,9 +110,9 @@ Hello world
|
|||
You may also specify an optional title.
|
||||
|
||||
```md
|
||||
:::note Your Title
|
||||
:::note[Your Title **with** some _Markdown_ `syntax`!]
|
||||
|
||||
Some **content** with _Markdown_ `syntax`.
|
||||
Some **content** with some _Markdown_ `syntax`.
|
||||
|
||||
:::
|
||||
```
|
||||
|
|
@ -120,9 +120,9 @@ Some **content** with _Markdown_ `syntax`.
|
|||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
||||
:::note Your Title
|
||||
:::note[Your Title **with** some _Markdown_ `syntax`!]
|
||||
|
||||
Some **content** with _Markdown_ `syntax`.
|
||||
Some **content** with some _Markdown_ `syntax`.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -186,7 +186,7 @@ import Tabs from '@theme/Tabs';
|
|||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
:::tip Use tabs in admonitions
|
||||
:::tip[Use tabs in admonitions]
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
|
||||
|
|
@ -200,7 +200,7 @@ import TabItem from '@theme/TabItem';
|
|||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
||||
:::tip Use tabs in admonitions
|
||||
:::tip[Use tabs in admonitions]
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
|
||||
|
|
@ -235,20 +235,16 @@ The types that are accepted are the same as above: `note`, `tip`, `danger`, `inf
|
|||
|
||||
```jsx title="MyReactPage.jsx"
|
||||
<Admonition type="tip" icon="💡" title="Did you know...">
|
||||
<p>
|
||||
Use plugins to introduce shorter syntax for the most commonly used JSX
|
||||
elements in your project.
|
||||
</p>
|
||||
Use plugins to introduce shorter syntax for the most commonly used JSX
|
||||
elements in your project.
|
||||
</Admonition>
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<Admonition type="tip" icon="💡" title="Did you know...">
|
||||
<p>
|
||||
Use plugins to introduce shorter syntax for the most commonly used JSX
|
||||
elements in your project.
|
||||
</p>
|
||||
Use plugins to introduce shorter syntax for the most commonly used JSX
|
||||
elements in your project.
|
||||
</Admonition>
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
|
@ -286,7 +282,6 @@ module.exports = {
|
|||
{
|
||||
docs: {
|
||||
admonitions: {
|
||||
tag: ':::',
|
||||
keywords: ['note', 'tip', 'info', 'caution', 'danger'],
|
||||
extendDefaults: true,
|
||||
},
|
||||
|
|
@ -299,9 +294,8 @@ module.exports = {
|
|||
|
||||
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`.
|
||||
- `extendDefaults`: Should the provided options (such as `keywords`) be merged into the existing defaults. Defaults to `true`.
|
||||
|
||||
The `keyword` will be passed as the `type` prop of the `Admonition` component.
|
||||
|
||||
|
|
@ -321,7 +315,6 @@ module.exports = {
|
|||
// ...
|
||||
docs: {
|
||||
admonitions: {
|
||||
tag: ':::',
|
||||
keywords: ['my-custom-admonition'],
|
||||
extendDefaults: true,
|
||||
},
|
||||
|
|
@ -361,7 +354,7 @@ 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
|
||||
:::my-custom-admonition[My Title]
|
||||
|
||||
It works!
|
||||
|
||||
|
|
@ -370,7 +363,7 @@ It works!
|
|||
|
||||
<BrowserWindow>
|
||||
|
||||
:::my-custom-admonition Custom Admonition
|
||||
:::my-custom-admonition[My Title]
|
||||
|
||||
It works!
|
||||
|
||||
|
|
|
|||
|
|
@ -54,27 +54,32 @@ $$
|
|||
To enable KaTeX, you need to install `remark-math` and `rehype-katex` plugins.
|
||||
|
||||
```bash npm2yarn
|
||||
npm install --save remark-math@3 rehype-katex@5 hast-util-is-element@1.1.0
|
||||
npm install --save remark-math@5 rehype-katex@6
|
||||
```
|
||||
|
||||
:::caution
|
||||
|
||||
Use the exact same versions. The latest versions are incompatible with Docusaurus 2.
|
||||
Make sure to use `remark-math >= 5` and `rehype-katex >= 6` for Docusaurus v3 (using MDX v2).
|
||||
|
||||
:::
|
||||
|
||||
Import the plugins in `docusaurus.config.js`:
|
||||
Those 2 plugins are now only available as ESM packages, and you will need to import them dynamically.
|
||||
|
||||
```js
|
||||
const math = require('remark-math');
|
||||
const katex = require('rehype-katex');
|
||||
First, turn your site config into an async config creator function:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = async function createConfigAsync() {
|
||||
return {
|
||||
// your site config...
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Add them to your content plugin or preset options (usually `@docusaurus/preset-classic` docs options):
|
||||
It is now possible to import the plugins dynamically and add them to your content plugin or preset options (usually `@docusaurus/preset-classic` docs options):
|
||||
|
||||
```js
|
||||
remarkPlugins: [math],
|
||||
rehypePlugins: [katex],
|
||||
remarkPlugins: [(await import('remark-math')).default],
|
||||
rehypePlugins: [(await import('rehype-katex')).default],
|
||||
```
|
||||
|
||||
Include the KaTeX CSS in your config under `stylesheets`:
|
||||
|
|
@ -94,39 +99,36 @@ stylesheets: [
|
|||
Overall the changes look like:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
// highlight-start
|
||||
const math = require('remark-math');
|
||||
const katex = require('rehype-katex');
|
||||
// highlight-end
|
||||
|
||||
module.exports = {
|
||||
title: 'Docusaurus',
|
||||
tagline: 'Build optimized websites quickly, focus on your content',
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
path: 'docs',
|
||||
// highlight-start
|
||||
remarkPlugins: [math],
|
||||
rehypePlugins: [katex],
|
||||
// highlight-end
|
||||
module.exports = async function createConfigAsync() {
|
||||
return {
|
||||
title: 'Docusaurus',
|
||||
tagline: 'Build optimized websites quickly, focus on your content',
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
path: 'docs',
|
||||
// highlight-start
|
||||
remarkPlugins: [(await import('remark-math')).default],
|
||||
rehypePlugins: [(await import('rehype-katex')).default],
|
||||
// highlight-end
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
// highlight-start
|
||||
stylesheets: [
|
||||
{
|
||||
href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
|
||||
type: 'text/css',
|
||||
integrity:
|
||||
'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
|
||||
crossorigin: 'anonymous',
|
||||
},
|
||||
],
|
||||
],
|
||||
// highlight-start
|
||||
stylesheets: [
|
||||
{
|
||||
href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
|
||||
type: 'text/css',
|
||||
integrity:
|
||||
'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
|
||||
crossorigin: 'anonymous',
|
||||
},
|
||||
],
|
||||
// highlight-end
|
||||
// highlight-end
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -144,67 +146,3 @@ module.exports = {
|
|||
],
|
||||
};
|
||||
```
|
||||
|
||||
## Upgrading rehype-katex beyond recommended version {#upgrading-rehype-katex-beyond-recommended-version}
|
||||
|
||||
:::tip
|
||||
|
||||
Only use the latest version if you actually need the bleeding-edge features of $\KaTeX$. Most users should find the older versions work just as well.
|
||||
|
||||
:::
|
||||
|
||||
The latest versions of `rehype-katex` (starting from `v6.0.0`) has moved to ES Modules, a new module system of JavaScript, which Docusaurus doesn't officially support yet. However, it is possible to import `rehype-katex` dynamically, using an async config creator. Docusaurus will call this creator function and wait for it to return the config object.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
async function createConfig() {
|
||||
// ES Modules are imported with `import()` instead of `require()`, and are imported asynchronously
|
||||
// highlight-next-line
|
||||
const katex = (await import('rehype-katex')).default;
|
||||
return {
|
||||
// ...
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
In this case, the overall configuration changes will look like:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
// highlight-next-line
|
||||
const math = require('remark-math');
|
||||
|
||||
async function createConfig() {
|
||||
// highlight-next-line
|
||||
const katex = (await import('rehype-katex')).default;
|
||||
return {
|
||||
title: 'Docusaurus',
|
||||
tagline: 'Build optimized websites quickly, focus on your content',
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
path: 'docs',
|
||||
// highlight-start
|
||||
remarkPlugins: [math],
|
||||
rehypePlugins: [katex],
|
||||
// highlight-end
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
// highlight-start
|
||||
stylesheets: [
|
||||
{
|
||||
href: 'https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css',
|
||||
type: 'text/css',
|
||||
integrity:
|
||||
'sha384-MlJdn/WNKDGXveldHDdyRP1R4CTHr3FeuDNfhsLPYrq2t0UBkUdK2jyTnXPEK1NQ',
|
||||
crossorigin: 'anonymous',
|
||||
},
|
||||
],
|
||||
// highlight-end
|
||||
};
|
||||
}
|
||||
|
||||
module.exports = createConfig;
|
||||
```
|
||||
|
|
|
|||
|
|
@ -64,8 +64,8 @@ export const Highlight = ({children, color}) => (
|
|||
|
||||
<BrowserWindow minHeight={240}>
|
||||
|
||||
<Highlight color="#25c2a0">Docusaurus green</Highlight>
|
||||
{` `}and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
|
||||
<><Highlight color="#25c2a0">Docusaurus green</Highlight>
|
||||
{` `}and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.</>
|
||||
|
||||
I can write **Markdown** alongside my _JSX_!
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ I can write **Markdown** alongside my _JSX_!
|
|||
|
||||
Since all doc files are parsed using MDX, anything that looks like HTML is actually JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
/* Instead of this: */
|
||||
<span style="background-color: red">Foo</span>
|
||||
|
|
@ -94,7 +94,7 @@ In addition, MDX is not [100% compatible with CommonMark](https://github.com/fac
|
|||
|
||||
You can also import your own components defined in other files or third-party components installed via npm.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```md
|
||||
<!-- Docusaurus theme component -->
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
|
@ -341,7 +341,7 @@ Use JSX within JSX tag, or move the Markdown to the outer layer:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
**Bold still doesn't work**
|
||||
|
|
@ -367,7 +367,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -397,7 +397,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -427,7 +427,7 @@ Don't indent:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -463,14 +463,13 @@ npm install --save raw-loader
|
|||
|
||||
Now you can import code snippets from another file as it is:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="myMarkdownFile.mdx"
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
import MyComponentSource from '!!raw-loader!./myComponent';
|
||||
|
||||
<CodeBlock language="jsx">{MyComponentSource}</CodeBlock>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
|
|
@ -509,13 +508,12 @@ By convention, using the **`_` filename prefix** will not create any doc page an
|
|||
This is text some content from `_markdown-partial-example.mdx`.
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="someOtherDoc.mdx"
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
||||
<PartialExample name="Sebastien" />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ import styles from './markdown-features-tabs-styles.module.css';
|
|||
|
||||
Docusaurus provides the `<Tabs>` component that you can use in Markdown thanks to [MDX](./markdown-features-react.mdx):
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
|
@ -32,7 +32,6 @@ import TabItem from '@theme/TabItem';
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
|
@ -250,7 +249,7 @@ You might want to customize the appearance of a certain set of tabs. You can pas
|
|||
|
||||
You can also customize each tab heading independently by using the `attributes` field. The extra props can be passed to the headings either through the `values` prop in `Tabs`, or props of each `TabItem`—in the same way as you declare `label`.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="some-doc.mdx"
|
||||
import styles from './styles.module.css';
|
||||
|
||||
|
|
@ -266,7 +265,6 @@ import styles from './styles.module.css';
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```css title="styles.module.css"
|
||||
.red {
|
||||
|
|
|
|||
|
|
@ -43,8 +43,8 @@ Generated IDs have **some limitations**:
|
|||
|
||||
A special Markdown syntax lets you set an **explicit heading id**:
|
||||
|
||||
```md
|
||||
### Hello World {#my-explicit-id}
|
||||
```mdx-code-block
|
||||
<Code language="md">{'### Hello World \u007B#my-explicit-id}\n'}</Code>
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
|
@ -102,7 +102,7 @@ It is also possible to display an inline table of contents directly inside a Mar
|
|||
|
||||
The `toc` variable is available in any MDX document and contains all the headings of an MDX document. By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel` for individual `TOCInline` components.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
|
|
@ -129,7 +129,7 @@ declare const toc: {
|
|||
|
||||
Note that the `toc` global is a flat array, so you can easily cut out unwanted nodes or insert extra nodes, and create a new TOC tree.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
|
|
|
|||
|
|
@ -351,7 +351,8 @@ We recommend extracting the complex embedded JSX code as separate standalone com
|
|||
|
||||
To deploy Docusaurus, run the following command:
|
||||
|
||||
````mdx-code-block
|
||||
````mdx-code-block
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
|
|
|||
|
|
@ -50,12 +50,13 @@ Or read the **[5-minute tutorial](https://tutorial.docusaurus.io)** online.
|
|||
|
||||
In this presentation at [Algolia Community Event](https://www.algolia.com/), [Meta Open Source team](https://opensource.facebook.com/) shared a brief walk-through of Docusaurus. They covered how to get started with the project, enable plugins, and set up functionalities like documentation and blogging.
|
||||
|
||||
{/* cSpell:ignore Yhyx Sksg */}
|
||||
|
||||
```mdx-code-block
|
||||
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
|
||||
|
||||
<div className="video-container">
|
||||
<LiteYouTubeEmbed
|
||||
// cSpell:ignore Yhyx Sksg
|
||||
id="Yhyx7otSksg"
|
||||
params="autoplay=1&autohide=1&showinfo=0&rel=0"
|
||||
title="Docusaurus: Documentation Made Easy"
|
||||
|
|
@ -129,18 +130,6 @@ Docusaurus 2 is born to be compassionately accessible to all your users, and lig
|
|||
|
||||
We believe that, as developers, knowing how a library works helps us become better at using it. Hence we're dedicating effort to explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.
|
||||
|
||||
<!--
|
||||
|
||||
Explain the principles that guide the development of Docusaurus.
|
||||
|
||||
References
|
||||
---
|
||||
- https://www.gatsbyjs.org/docs/behind-the-scenes/
|
||||
- https://reactjs.org/docs/design-principles.html
|
||||
- https://v1.vuepress.vuejs.org/miscellaneous/design-concepts.html
|
||||
|
||||
-->
|
||||
|
||||
## Comparison with other tools {#comparison-with-other-tools}
|
||||
|
||||
Across all static site generators, Docusaurus has a unique focus on documentation sites and has many out-of-the-box features.
|
||||
|
|
|
|||
|
|
@ -247,7 +247,7 @@ Still, you can reuse the [Infima CSS variables](styling-layout.mdx#styling-your-
|
|||
|
||||
### Customizing the Algolia search behavior {#customizing-the-algolia-search-behavior}
|
||||
|
||||
<!-- TODO: update options link once the documentation is available on the DocSearch website -->
|
||||
{/* TODO: update options link once the documentation is available on the DocSearch website */}
|
||||
|
||||
Algolia DocSearch supports a [list of options](https://autocomplete-experimental.netlify.app/docs/DocSearchModal#reference) that you can pass to the `algolia` field in the `docusaurus.config.js` file.
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,6 @@
|
|||
// @ts-check
|
||||
|
||||
const path = require('path');
|
||||
const math = require('remark-math');
|
||||
const npm2yarn = require('@docusaurus/remark-plugin-npm2yarn');
|
||||
const versions = require('./versions.json');
|
||||
const VersionsArchived = require('./versionsArchived.json');
|
||||
|
|
@ -140,6 +139,20 @@ module.exports = async function createConfigAsync() {
|
|||
},
|
||||
markdown: {
|
||||
mermaid: true,
|
||||
mdx1Compat: {
|
||||
// comments: false,
|
||||
},
|
||||
preprocessor: ({filePath, fileContent}) => {
|
||||
if (isDev) {
|
||||
// "vscode://file/${projectPath}${filePath}:${line}:${column}",
|
||||
// "webstorm://open?file=${projectPath}${filePath}&line=${line}&column=${column}",
|
||||
const vscodeLink = `vscode://file/${filePath}`;
|
||||
const webstormLink = `webstorm://open?file=${filePath}`;
|
||||
const intellijLink = `idea://open?file=${filePath}`;
|
||||
return `${fileContent}\n\n---\n\n**DEV**: open this file in [VSCode](<${vscodeLink}>) | [WebStorm](<${webstormLink}>) | [IntelliJ](<${intellijLink}>)\n`;
|
||||
}
|
||||
return fileContent;
|
||||
},
|
||||
},
|
||||
onBrokenLinks: 'throw',
|
||||
onBrokenMarkdownLinks: 'warn',
|
||||
|
|
@ -331,13 +344,12 @@ module.exports = async function createConfigAsync() {
|
|||
},
|
||||
admonitions: {
|
||||
keywords: ['my-custom-admonition'],
|
||||
extendDefaults: true,
|
||||
},
|
||||
showLastUpdateAuthor: true,
|
||||
showLastUpdateTime: true,
|
||||
remarkPlugins: [
|
||||
math,
|
||||
[npm2yarn, {sync: true}],
|
||||
(await import('remark-math')).default,
|
||||
(await import('./src/remark/configTabs.mjs')).default,
|
||||
],
|
||||
rehypePlugins: [(await import('rehype-katex')).default],
|
||||
|
|
@ -346,6 +358,7 @@ module.exports = async function createConfigAsync() {
|
|||
isDev || isDeployPreview || isBranchDeploy
|
||||
? 'current'
|
||||
: undefined,
|
||||
|
||||
onlyIncludeVersions: (() => {
|
||||
if (isBuildFast) {
|
||||
return ['current'];
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@
|
|||
"react-medium-image-zoom": "^5.1.3",
|
||||
"react-popper": "^2.3.0",
|
||||
"rehype-katex": "^6.0.2",
|
||||
"remark-math": "^3.0.1",
|
||||
"remark-math": "^5.1.1",
|
||||
"swc-loader": "^0.2.3",
|
||||
"unist-util-visit": "^2.0.3",
|
||||
"webpack": "^5.76.0",
|
||||
|
|
|
|||
|
|
@ -67,6 +67,8 @@ function processSection(section) {
|
|||
return {
|
||||
title: title.replace(/ \(.*\)/, ''),
|
||||
content: `---
|
||||
mdx:
|
||||
format: md
|
||||
date: ${`${date}T${hour}:00`}${
|
||||
authors
|
||||
? `
|
||||
|
|
|
|||
|
|
@ -36,26 +36,59 @@ export default function plugin() {
|
|||
.replace(pluginMeta, '')
|
||||
.trim()
|
||||
.replace(/^.*?= /, '')
|
||||
.replace(/;$/, '')
|
||||
// eslint-disable-next-line prefer-named-capture-group
|
||||
.replace(/([`$\\])/g, '\\$1');
|
||||
.replace(/;$/, '');
|
||||
|
||||
parent.children.splice(
|
||||
index,
|
||||
1,
|
||||
{
|
||||
type: 'import',
|
||||
value: `import ConfigTabs from "@site/src/components/ConfigTabs";`,
|
||||
const importNode = {
|
||||
type: 'mdxjsEsm',
|
||||
value: 'import ConfigTabs from "@site/src/components/ConfigTabs"',
|
||||
data: {
|
||||
estree: {
|
||||
type: 'Program',
|
||||
body: [
|
||||
{
|
||||
type: 'ImportDeclaration',
|
||||
specifiers: [
|
||||
{
|
||||
type: 'ImportDefaultSpecifier',
|
||||
local: {type: 'Identifier', name: 'ConfigTabs'},
|
||||
},
|
||||
],
|
||||
source: {
|
||||
type: 'Literal',
|
||||
value: '@site/src/components/ConfigTabs',
|
||||
raw: "'@site/src/components/ConfigTabs'",
|
||||
},
|
||||
},
|
||||
],
|
||||
sourceType: 'module',
|
||||
},
|
||||
},
|
||||
{
|
||||
type: 'jsx',
|
||||
value: `<ConfigTabs
|
||||
pluginName="${pluginName.trim()}"
|
||||
presetOptionName="${presetOptionName.trim()}"
|
||||
code={\`${config}\`}
|
||||
/>`,
|
||||
},
|
||||
);
|
||||
};
|
||||
|
||||
const jsxNode = {
|
||||
type: 'mdxJsxFlowElement',
|
||||
name: 'ConfigTabs',
|
||||
attributes: [
|
||||
{
|
||||
type: 'mdxJsxAttribute',
|
||||
name: 'pluginName',
|
||||
value: pluginName.trim(),
|
||||
},
|
||||
{
|
||||
type: 'mdxJsxAttribute',
|
||||
name: 'presetOptionName',
|
||||
value: presetOptionName.trim(),
|
||||
},
|
||||
{
|
||||
type: 'mdxJsxAttribute',
|
||||
name: 'code',
|
||||
value: config,
|
||||
},
|
||||
],
|
||||
children: [],
|
||||
};
|
||||
|
||||
parent.children.splice(index, 1, importNode, jsxNode);
|
||||
});
|
||||
};
|
||||
return transformer;
|
||||
|
|
|
|||
|
|
@ -6,11 +6,13 @@
|
|||
*/
|
||||
|
||||
import MDXComponents from '@theme-original/MDXComponents';
|
||||
import Code from '@theme/MDXComponents/Code';
|
||||
import Highlight from '@site/src/components/Highlight';
|
||||
import TweetQuote from '@site/src/components/TweetQuote';
|
||||
|
||||
export default {
|
||||
...MDXComponents,
|
||||
Code,
|
||||
Highlight,
|
||||
TweetQuote,
|
||||
};
|
||||
|
|
|
|||
|
|
@ -123,7 +123,7 @@ The i18n configuration object to [localize your site](../i18n/i18n-introduction.
|
|||
|
||||
Example:
|
||||
|
||||
<!-- cSpell:ignore فارسی -->
|
||||
{/* cSpell:ignore فارسی */}
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ Accepted fields:
|
|||
| `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.title` | `string` | `siteConfig.title` | Title of the feed. |
|
||||
| `feedOptions.description` | `string` | <code>\`${siteConfig.title} Blog\`</code> | Description of the feed. |
|
||||
| `feedOptions.description` | `string` | <code>\`$\{siteConfig.title} Blog\`</code> | Description of the feed. |
|
||||
| `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
|
||||
| `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. |
|
||||
| `sortPosts` | <code>'descending' \| 'ascending' </code> | `'descending'` | Governs the direction of blog post sorting. |
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ hide_table_of_contents: false
|
|||
|
||||
Welcome to this blog. This blog is created with [**Docusaurus 2**](https://docusaurus.io/).
|
||||
|
||||
<!--truncate-->
|
||||
<!-- truncate -->
|
||||
|
||||
This is my first post on Docusaurus 2.
|
||||
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@ Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
|
|||
|
||||
If you use [Prettier](https://prettier.io) to format your Markdown files, Prettier might auto-format your code to invalid admonition syntax. To avoid this problem, add empty lines around the starting and ending directives. This is also why the examples we show here all have empty lines around the content.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```md
|
||||
<!-- Prettier doesn't change this -->
|
||||
:::note
|
||||
|
|
@ -110,7 +110,7 @@ Hello world
|
|||
You may also specify an optional title.
|
||||
|
||||
```md
|
||||
:::note Your Title
|
||||
:::note Your Title
|
||||
|
||||
Some **content** with _Markdown_ `syntax`.
|
||||
|
||||
|
|
@ -138,7 +138,9 @@ import Tabs from '@theme/Tabs';
|
|||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
:::tip Use tabs in admonitions
|
||||
:::tip
|
||||
|
||||
Use tabs in admonitions
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
|
||||
|
|
@ -152,7 +154,9 @@ import TabItem from '@theme/TabItem';
|
|||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
||||
:::tip Use tabs in admonitions
|
||||
:::tip
|
||||
|
||||
Use tabs in admonitions
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ I can write **Markdown** alongside my _JSX_!
|
|||
|
||||
Since all doc files are parsed using MDX, anything that looks like HTML is actually JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
/* Instead of this: */
|
||||
<span style="background-color: red">Foo</span>
|
||||
|
|
@ -94,7 +94,7 @@ In addition, MDX is not [100% compatible with CommonMark](https://github.com/fac
|
|||
|
||||
You can also import your own components defined in other files or third-party components installed via npm.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```md
|
||||
<!-- Docusaurus theme component -->
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
|
@ -341,7 +341,7 @@ Use JSX within JSX tag, or move the Markdown to the outer layer:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
**Bold still doesn't work**
|
||||
|
|
@ -367,7 +367,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -397,7 +397,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -427,7 +427,7 @@ Don't indent:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -463,14 +463,13 @@ npm install --save raw-loader
|
|||
|
||||
Now you can import code snippets from another file as it is:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="myMarkdownFile.mdx"
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
import MyComponentSource from '!!raw-loader!./myComponent';
|
||||
|
||||
<CodeBlock language="jsx">{MyComponentSource}</CodeBlock>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
|
|
@ -509,13 +508,12 @@ By convention, using the **`_` filename prefix** will not create any doc page an
|
|||
This is text some content from `_markdown-partial-example.mdx`.
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="someOtherDoc.mdx"
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
||||
<PartialExample name="Sebastien" />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ import styles from './markdown-features-tabs-styles.module.css';
|
|||
|
||||
Docusaurus provides the `<Tabs>` component that you can use in Markdown thanks to [MDX](./markdown-features-react.mdx):
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
|
@ -32,7 +32,6 @@ import TabItem from '@theme/TabItem';
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
|
@ -250,7 +249,7 @@ You might want to customize the appearance of a certain set of tabs. You can pas
|
|||
|
||||
You can also customize each tab heading independently by using the `attributes` field. The extra props can be passed to the headings either through the `values` prop in `Tabs`, or props of each `TabItem`—in the same way as you declare `label`.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="some-doc.mdx"
|
||||
import styles from './styles.module.css';
|
||||
|
||||
|
|
@ -266,7 +265,6 @@ import styles from './styles.module.css';
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```css title="styles.module.css"
|
||||
.red {
|
||||
|
|
|
|||
|
|
@ -43,8 +43,8 @@ Generated IDs have **some limitations**:
|
|||
|
||||
A special Markdown syntax lets you set an **explicit heading id**:
|
||||
|
||||
```md
|
||||
### Hello World {#my-explicit-id}
|
||||
```mdx-code-block
|
||||
<Code language="md">{'### Hello World \u007B#my-explicit-id}\n'}</Code>
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
|
@ -102,7 +102,7 @@ It is also possible to display an inline table of contents directly inside a Mar
|
|||
|
||||
The `toc` variable is available in any MDX document and contains all the headings of an MDX document. By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel` for individual `TOCInline` components.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
|
|
@ -129,7 +129,7 @@ declare const toc: {
|
|||
|
||||
Note that the `toc` global is a flat array, so you can easily cut out unwanted nodes or insert extra nodes, and create a new TOC tree.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
|
|
|
|||
|
|
@ -351,7 +351,7 @@ We recommend extracting the complex embedded JSX code as separate standalone com
|
|||
|
||||
To deploy Docusaurus, run the following command:
|
||||
|
||||
````mdx-code-block
|
||||
````mdx-code-block
|
||||
import Tabs from '@theme/Tabs';
|
||||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
|
|
|||
|
|
@ -55,7 +55,6 @@ import LiteYouTubeEmbed from 'react-lite-youtube-embed';
|
|||
|
||||
<div className="video-container">
|
||||
<LiteYouTubeEmbed
|
||||
// cSpell:ignore Yhyx Sksg
|
||||
id="Yhyx7otSksg"
|
||||
params="autoplay=1&autohide=1&showinfo=0&rel=0"
|
||||
title="Docusaurus: Documentation Made Easy"
|
||||
|
|
@ -129,18 +128,6 @@ Docusaurus 2 is born to be compassionately accessible to all your users, and lig
|
|||
|
||||
We believe that, as developers, knowing how a library works helps us become better at using it. Hence we're dedicating effort to explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.
|
||||
|
||||
<!--
|
||||
|
||||
Explain the principles that guide the development of Docusaurus.
|
||||
|
||||
References
|
||||
---
|
||||
- https://www.gatsbyjs.org/docs/behind-the-scenes/
|
||||
- https://reactjs.org/docs/design-principles.html
|
||||
- https://v1.vuepress.vuejs.org/miscellaneous/design-concepts.html
|
||||
|
||||
-->
|
||||
|
||||
## Comparison with other tools {#comparison-with-other-tools}
|
||||
|
||||
Across all static site generators, Docusaurus has a unique focus on documentation sites and has many out-of-the-box features.
|
||||
|
|
|
|||
|
|
@ -241,7 +241,7 @@ Still, you can reuse the [Infima CSS variables](styling-layout.mdx#styling-your-
|
|||
|
||||
### Customizing the Algolia search behavior {#customizing-the-algolia-search-behavior}
|
||||
|
||||
<!-- TODO: update options link once the documentation is available on the DocSearch website -->
|
||||
{/* TODO: update options link once the documentation is available on the DocSearch website */}
|
||||
|
||||
Algolia DocSearch supports a [list of options](https://autocomplete-experimental.netlify.app/docs/DocSearchModal#reference) that you can pass to the `algolia` field in the `docusaurus.config.js` file.
|
||||
|
||||
|
|
|
|||
|
|
@ -123,7 +123,7 @@ The i18n configuration object to [localize your site](../i18n/i18n-introduction.
|
|||
|
||||
Example:
|
||||
|
||||
<!-- cSpell:ignore فارسی -->
|
||||
{/* cSpell:ignore فارسی */}
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ Accepted fields:
|
|||
| `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.title` | `string` | `siteConfig.title` | Title of the feed. |
|
||||
| `feedOptions.description` | `string` | <code>\`${siteConfig.title} Blog\`</code> | Description of the feed. |
|
||||
| `feedOptions.description` | `string` | <code>\`$\{siteConfig.title} Blog\`</code> | Description of the feed. |
|
||||
| `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
|
||||
| `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. |
|
||||
| `sortPosts` | <code>'descending' \| 'ascending' </code> | `'descending'` | Governs the direction of blog post sorting. |
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ hide_table_of_contents: false
|
|||
|
||||
Welcome to this blog. This blog is created with [**Docusaurus 2**](https://docusaurus.io/).
|
||||
|
||||
<!--truncate-->
|
||||
<!-- truncate -->
|
||||
|
||||
This is my first post on Docusaurus 2.
|
||||
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@ Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
|
|||
|
||||
If you use [Prettier](https://prettier.io) to format your Markdown files, Prettier might auto-format your code to invalid admonition syntax. To avoid this problem, add empty lines around the starting and ending directives. This is also why the examples we show here all have empty lines around the content.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```md
|
||||
<!-- Prettier doesn't change this -->
|
||||
:::note
|
||||
|
|
@ -110,7 +110,7 @@ Hello world
|
|||
You may also specify an optional title.
|
||||
|
||||
```md
|
||||
:::note Your Title
|
||||
:::note Your Title
|
||||
|
||||
Some **content** with _Markdown_ `syntax`.
|
||||
|
||||
|
|
@ -138,7 +138,9 @@ import Tabs from '@theme/Tabs';
|
|||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
:::tip Use tabs in admonitions
|
||||
:::tip
|
||||
|
||||
Use tabs in admonitions
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
|
||||
|
|
@ -152,7 +154,9 @@ import TabItem from '@theme/TabItem';
|
|||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
||||
:::tip Use tabs in admonitions
|
||||
:::tip
|
||||
|
||||
Use tabs in admonitions
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ I can write **Markdown** alongside my _JSX_!
|
|||
|
||||
Since all doc files are parsed using MDX, anything that looks like HTML is actually JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
/* Instead of this: */
|
||||
<span style="background-color: red">Foo</span>
|
||||
|
|
@ -94,7 +94,7 @@ In addition, MDX is not [100% compatible with CommonMark](https://github.com/fac
|
|||
|
||||
You can also import your own components defined in other files or third-party components installed via npm.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```md
|
||||
<!-- Docusaurus theme component -->
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
|
@ -341,7 +341,7 @@ Use JSX within JSX tag, or move the Markdown to the outer layer:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
**Bold still doesn't work**
|
||||
|
|
@ -367,7 +367,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -397,7 +397,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -427,7 +427,7 @@ Don't indent:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -463,14 +463,13 @@ npm install --save raw-loader
|
|||
|
||||
Now you can import code snippets from another file as it is:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="myMarkdownFile.mdx"
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
import MyComponentSource from '!!raw-loader!./myComponent';
|
||||
|
||||
<CodeBlock language="jsx">{MyComponentSource}</CodeBlock>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
|
|
@ -509,13 +508,12 @@ By convention, using the **`_` filename prefix** will not create any doc page an
|
|||
This is text some content from `_markdown-partial-example.mdx`.
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="someOtherDoc.mdx"
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
||||
<PartialExample name="Sebastien" />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ import styles from './markdown-features-tabs-styles.module.css';
|
|||
|
||||
Docusaurus provides the `<Tabs>` component that you can use in Markdown thanks to [MDX](./markdown-features-react.mdx):
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
|
@ -32,7 +32,6 @@ import TabItem from '@theme/TabItem';
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
|
@ -250,7 +249,7 @@ You might want to customize the appearance of a certain set of tabs. You can pas
|
|||
|
||||
You can also customize each tab heading independently by using the `attributes` field. The extra props can be passed to the headings either through the `values` prop in `Tabs`, or props of each `TabItem`—in the same way as you declare `label`.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="some-doc.mdx"
|
||||
import styles from './styles.module.css';
|
||||
|
||||
|
|
@ -266,7 +265,6 @@ import styles from './styles.module.css';
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```css title="styles.module.css"
|
||||
.red {
|
||||
|
|
|
|||
|
|
@ -43,8 +43,8 @@ Generated IDs have **some limitations**:
|
|||
|
||||
A special Markdown syntax lets you set an **explicit heading id**:
|
||||
|
||||
```md
|
||||
### Hello World {#my-explicit-id}
|
||||
```mdx-code-block
|
||||
<Code language="md">{'### Hello World \u007B#my-explicit-id}\n'}</Code>
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
|
@ -102,7 +102,7 @@ It is also possible to display an inline table of contents directly inside a Mar
|
|||
|
||||
The `toc` variable is available in any MDX document and contains all the headings of an MDX document. By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel` for individual `TOCInline` components.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
|
|
@ -129,7 +129,7 @@ declare const toc: {
|
|||
|
||||
Note that the `toc` global is a flat array, so you can easily cut out unwanted nodes or insert extra nodes, and create a new TOC tree.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
|
|
|
|||
|
|
@ -351,7 +351,7 @@ We recommend extracting the complex embedded JSX code as separate standalone com
|
|||
|
||||
To deploy Docusaurus, run the following command:
|
||||
|
||||
````mdx-code-block
|
||||
````mdx-code-block
|
||||
import Tabs from '@theme/Tabs';
|
||||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
|
|
|||
|
|
@ -55,7 +55,6 @@ import LiteYouTubeEmbed from 'react-lite-youtube-embed';
|
|||
|
||||
<div className="video-container">
|
||||
<LiteYouTubeEmbed
|
||||
// cSpell:ignore Yhyx Sksg
|
||||
id="Yhyx7otSksg"
|
||||
params="autoplay=1&autohide=1&showinfo=0&rel=0"
|
||||
title="Docusaurus: Documentation Made Easy"
|
||||
|
|
@ -129,18 +128,6 @@ Docusaurus 2 is born to be compassionately accessible to all your users, and lig
|
|||
|
||||
We believe that, as developers, knowing how a library works helps us become better at using it. Hence we're dedicating effort to explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.
|
||||
|
||||
<!--
|
||||
|
||||
Explain the principles that guide the development of Docusaurus.
|
||||
|
||||
References
|
||||
---
|
||||
- https://www.gatsbyjs.org/docs/behind-the-scenes/
|
||||
- https://reactjs.org/docs/design-principles.html
|
||||
- https://v1.vuepress.vuejs.org/miscellaneous/design-concepts.html
|
||||
|
||||
-->
|
||||
|
||||
## Comparison with other tools {#comparison-with-other-tools}
|
||||
|
||||
Across all static site generators, Docusaurus has a unique focus on documentation sites and has many out-of-the-box features.
|
||||
|
|
|
|||
|
|
@ -241,7 +241,7 @@ Still, you can reuse the [Infima CSS variables](styling-layout.mdx#styling-your-
|
|||
|
||||
### Customizing the Algolia search behavior {#customizing-the-algolia-search-behavior}
|
||||
|
||||
<!-- TODO: update options link once the documentation is available on the DocSearch website -->
|
||||
{/* TODO: update options link once the documentation is available on the DocSearch website */}
|
||||
|
||||
Algolia DocSearch supports a [list of options](https://autocomplete-experimental.netlify.app/docs/DocSearchModal#reference) that you can pass to the `algolia` field in the `docusaurus.config.js` file.
|
||||
|
||||
|
|
|
|||
|
|
@ -123,7 +123,7 @@ The i18n configuration object to [localize your site](../i18n/i18n-introduction.
|
|||
|
||||
Example:
|
||||
|
||||
<!-- cSpell:ignore فارسی -->
|
||||
{/* cSpell:ignore فارسی */}
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ Accepted fields:
|
|||
| `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.title` | `string` | `siteConfig.title` | Title of the feed. |
|
||||
| `feedOptions.description` | `string` | <code>\`${siteConfig.title} Blog\`</code> | Description of the feed. |
|
||||
| `feedOptions.description` | `string` | <code>\`$\{siteConfig.title} Blog\`</code> | Description of the feed. |
|
||||
| `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
|
||||
| `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. |
|
||||
| `sortPosts` | <code>'descending' \| 'ascending' </code> | `'descending'` | Governs the direction of blog post sorting. |
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ hide_table_of_contents: false
|
|||
|
||||
Welcome to this blog. This blog is created with [**Docusaurus 2**](https://docusaurus.io/).
|
||||
|
||||
<!--truncate-->
|
||||
<!-- truncate -->
|
||||
|
||||
This is my first post on Docusaurus 2.
|
||||
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@ Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
|
|||
|
||||
If you use [Prettier](https://prettier.io) to format your Markdown files, Prettier might auto-format your code to invalid admonition syntax. To avoid this problem, add empty lines around the starting and ending directives. This is also why the examples we show here all have empty lines around the content.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```md
|
||||
<!-- Prettier doesn't change this -->
|
||||
:::note
|
||||
|
|
@ -110,7 +110,7 @@ Hello world
|
|||
You may also specify an optional title.
|
||||
|
||||
```md
|
||||
:::note Your Title
|
||||
:::note Your Title
|
||||
|
||||
Some **content** with _Markdown_ `syntax`.
|
||||
|
||||
|
|
@ -138,7 +138,9 @@ import Tabs from '@theme/Tabs';
|
|||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
:::tip Use tabs in admonitions
|
||||
:::tip
|
||||
|
||||
Use tabs in admonitions
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
|
||||
|
|
@ -152,7 +154,9 @@ import TabItem from '@theme/TabItem';
|
|||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
||||
:::tip Use tabs in admonitions
|
||||
:::tip
|
||||
|
||||
Use tabs in admonitions
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ I can write **Markdown** alongside my _JSX_!
|
|||
|
||||
Since all doc files are parsed using MDX, anything that looks like HTML is actually JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
/* Instead of this: */
|
||||
<span style="background-color: red">Foo</span>
|
||||
|
|
@ -94,7 +94,7 @@ In addition, MDX is not [100% compatible with CommonMark](https://github.com/fac
|
|||
|
||||
You can also import your own components defined in other files or third-party components installed via npm.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```md
|
||||
<!-- Docusaurus theme component -->
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
|
@ -341,7 +341,7 @@ Use JSX within JSX tag, or move the Markdown to the outer layer:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
**Bold still doesn't work**
|
||||
|
|
@ -367,7 +367,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -397,7 +397,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -427,7 +427,7 @@ Don't indent:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -463,14 +463,13 @@ npm install --save raw-loader
|
|||
|
||||
Now you can import code snippets from another file as it is:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
<!-- prettier-ignore -->
|
||||
```jsx title="myMarkdownFile.mdx"
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
import MyComponentSource from '!!raw-loader!./myComponent';
|
||||
|
||||
<CodeBlock language="jsx">{MyComponentSource}</CodeBlock>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
|
|
@ -509,13 +508,12 @@ By convention, using the **`_` filename prefix** will not create any doc page an
|
|||
This is text some content from `_markdown-partial-example.mdx`.
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="someOtherDoc.mdx"
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
||||
<PartialExample name="Sebastien" />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ import styles from './markdown-features-tabs-styles.module.css';
|
|||
|
||||
Docusaurus provides the `<Tabs>` component that you can use in Markdown thanks to [MDX](./markdown-features-react.mdx):
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
|
@ -32,7 +32,6 @@ import TabItem from '@theme/TabItem';
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
|
@ -250,7 +249,7 @@ You might want to customize the appearance of a certain set of tabs. You can pas
|
|||
|
||||
You can also customize each tab heading independently by using the `attributes` field. The extra props can be passed to the headings either through the `values` prop in `Tabs`, or props of each `TabItem`—in the same way as you declare `label`.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="some-doc.mdx"
|
||||
import styles from './styles.module.css';
|
||||
|
||||
|
|
@ -266,7 +265,6 @@ import styles from './styles.module.css';
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```css title="styles.module.css"
|
||||
.red {
|
||||
|
|
|
|||
|
|
@ -43,8 +43,8 @@ Generated IDs have **some limitations**:
|
|||
|
||||
A special Markdown syntax lets you set an **explicit heading id**:
|
||||
|
||||
```md
|
||||
### Hello World {#my-explicit-id}
|
||||
```mdx-code-block
|
||||
<Code language="md">{'### Hello World \u007B#my-explicit-id}\n'}</Code>
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
|
@ -102,7 +102,7 @@ It is also possible to display an inline table of contents directly inside a Mar
|
|||
|
||||
The `toc` variable is available in any MDX document and contains all the headings of an MDX document. By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel` for individual `TOCInline` components.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
|
|
@ -129,7 +129,7 @@ declare const toc: {
|
|||
|
||||
Note that the `toc` global is a flat array, so you can easily cut out unwanted nodes or insert extra nodes, and create a new TOC tree.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
|
|
|
|||
|
|
@ -351,7 +351,7 @@ We recommend extracting the complex embedded JSX code as separate standalone com
|
|||
|
||||
To deploy Docusaurus, run the following command:
|
||||
|
||||
````mdx-code-block
|
||||
````mdx-code-block
|
||||
import Tabs from '@theme/Tabs';
|
||||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
|
|
|||
|
|
@ -55,7 +55,6 @@ import LiteYouTubeEmbed from 'react-lite-youtube-embed';
|
|||
|
||||
<div className="video-container">
|
||||
<LiteYouTubeEmbed
|
||||
// cSpell:ignore Yhyx Sksg
|
||||
id="Yhyx7otSksg"
|
||||
params="autoplay=1&autohide=1&showinfo=0&rel=0"
|
||||
title="Docusaurus: Documentation Made Easy"
|
||||
|
|
@ -129,18 +128,6 @@ Docusaurus 2 is born to be compassionately accessible to all your users, and lig
|
|||
|
||||
We believe that, as developers, knowing how a library works helps us become better at using it. Hence we're dedicating effort to explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.
|
||||
|
||||
<!--
|
||||
|
||||
Explain the principles that guide the development of Docusaurus.
|
||||
|
||||
References
|
||||
---
|
||||
- https://www.gatsbyjs.org/docs/behind-the-scenes/
|
||||
- https://reactjs.org/docs/design-principles.html
|
||||
- https://v1.vuepress.vuejs.org/miscellaneous/design-concepts.html
|
||||
|
||||
-->
|
||||
|
||||
## Comparison with other tools {#comparison-with-other-tools}
|
||||
|
||||
Across all static site generators, Docusaurus has a unique focus on documentation sites and has many out-of-the-box features.
|
||||
|
|
|
|||
|
|
@ -241,7 +241,7 @@ Still, you can reuse the [Infima CSS variables](styling-layout.mdx#styling-your-
|
|||
|
||||
### Customizing the Algolia search behavior {#customizing-the-algolia-search-behavior}
|
||||
|
||||
<!-- TODO: update options link once the documentation is available on the DocSearch website -->
|
||||
{/* TODO: update options link once the documentation is available on the DocSearch website */}
|
||||
|
||||
Algolia DocSearch supports a [list of options](https://autocomplete-experimental.netlify.app/docs/DocSearchModal#reference) that you can pass to the `algolia` field in the `docusaurus.config.js` file.
|
||||
|
||||
|
|
|
|||
|
|
@ -123,7 +123,7 @@ The i18n configuration object to [localize your site](../i18n/i18n-introduction.
|
|||
|
||||
Example:
|
||||
|
||||
<!-- cSpell:ignore فارسی -->
|
||||
{/* cSpell:ignore فارسی */}
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
|
|
|
|||
|
|
@ -69,7 +69,7 @@ Accepted fields:
|
|||
| `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.description` | `string` | <code>\`$\{siteConfig.title} Blog\`</code> | Description of the feed. |
|
||||
| `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
|
||||
| `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. |
|
||||
| `sortPosts` | <code>'descending' \| 'ascending' </code> | `'descending'` | Governs the direction of blog post sorting. |
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@ Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
|
|||
|
||||
If you use [Prettier](https://prettier.io) to format your Markdown files, Prettier might auto-format your code to invalid admonition syntax. To avoid this problem, add empty lines around the starting and ending directives. This is also why the examples we show here all have empty lines around the content.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```md
|
||||
<!-- Prettier doesn't change this -->
|
||||
:::note
|
||||
|
|
@ -110,7 +110,7 @@ Hello world
|
|||
You may also specify an optional title.
|
||||
|
||||
```md
|
||||
:::note Your Title
|
||||
:::note Your Title
|
||||
|
||||
Some **content** with _Markdown_ `syntax`.
|
||||
|
||||
|
|
@ -138,7 +138,9 @@ import Tabs from '@theme/Tabs';
|
|||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
:::tip Use tabs in admonitions
|
||||
:::tip
|
||||
|
||||
Use tabs in admonitions
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
|
||||
|
|
@ -152,7 +154,9 @@ import TabItem from '@theme/TabItem';
|
|||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
||||
:::tip Use tabs in admonitions
|
||||
:::tip
|
||||
|
||||
Use tabs in admonitions
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
|
||||
|
|
@ -197,10 +201,8 @@ The types that are accepted are the same as above: `note`, `tip`, `danger`, `inf
|
|||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<Admonition type="tip" icon="💡" title="Did you know...">
|
||||
<p>
|
||||
Use plugins to introduce shorter syntax for the most commonly used JSX
|
||||
elements in your project.
|
||||
</p>
|
||||
Use plugins to introduce shorter syntax for the most commonly used JSX
|
||||
elements in your project.
|
||||
</Admonition>
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
|
|
|||
|
|
@ -64,8 +64,8 @@ export const Highlight = ({children, color}) => (
|
|||
|
||||
<BrowserWindow minHeight={240}>
|
||||
|
||||
<Highlight color="#25c2a0">Docusaurus green</Highlight>
|
||||
{` `}and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
|
||||
<><Highlight color="#25c2a0">Docusaurus green</Highlight>
|
||||
{` `}and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.</>
|
||||
|
||||
I can write **Markdown** alongside my _JSX_!
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ I can write **Markdown** alongside my _JSX_!
|
|||
|
||||
Since all doc files are parsed using MDX, anything that looks like HTML is actually JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
/* Instead of this: */
|
||||
<span style="background-color: red">Foo</span>
|
||||
|
|
@ -94,7 +94,7 @@ In addition, MDX is not [100% compatible with CommonMark](https://github.com/fac
|
|||
|
||||
You can also import your own components defined in other files or third-party components installed via npm.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```md
|
||||
<!-- Docusaurus theme component -->
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
|
@ -341,7 +341,7 @@ Use JSX within JSX tag, or move the Markdown to the outer layer:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
**Bold still doesn't work**
|
||||
|
|
@ -367,7 +367,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -397,7 +397,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -427,7 +427,7 @@ Don't indent:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -463,14 +463,13 @@ npm install --save raw-loader
|
|||
|
||||
Now you can import code snippets from another file as it is:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="myMarkdownFile.mdx"
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
import MyComponentSource from '!!raw-loader!./myComponent';
|
||||
|
||||
<CodeBlock language="jsx">{MyComponentSource}</CodeBlock>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
|
|
@ -509,13 +508,12 @@ By convention, using the **`_` filename prefix** will not create any doc page an
|
|||
This is text some content from `_markdown-partial-example.mdx`.
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="someOtherDoc.mdx"
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
||||
<PartialExample name="Sebastien" />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ import styles from './markdown-features-tabs-styles.module.css';
|
|||
|
||||
Docusaurus provides the `<Tabs>` component that you can use in Markdown thanks to [MDX](./markdown-features-react.mdx):
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
|
@ -32,7 +32,6 @@ import TabItem from '@theme/TabItem';
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
|
@ -250,7 +249,7 @@ You might want to customize the appearance of a certain set of tabs. You can pas
|
|||
|
||||
You can also customize each tab heading independently by using the `attributes` field. The extra props can be passed to the headings either through the `values` prop in `Tabs`, or props of each `TabItem`—in the same way as you declare `label`.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="some-doc.mdx"
|
||||
import styles from './styles.module.css';
|
||||
|
||||
|
|
@ -266,7 +265,6 @@ import styles from './styles.module.css';
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```css title="styles.module.css"
|
||||
.red {
|
||||
|
|
|
|||
|
|
@ -43,8 +43,8 @@ Generated IDs have **some limitations**:
|
|||
|
||||
A special Markdown syntax lets you set an **explicit heading id**:
|
||||
|
||||
```md
|
||||
### Hello World {#my-explicit-id}
|
||||
```mdx-code-block
|
||||
<Code language="md">{'### Hello World \u007B#my-explicit-id}\n'}</Code>
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
|
@ -102,7 +102,7 @@ It is also possible to display an inline table of contents directly inside a Mar
|
|||
|
||||
The `toc` variable is available in any MDX document and contains all the headings of an MDX document. By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel` for individual `TOCInline` components.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
|
|
@ -129,7 +129,7 @@ declare const toc: {
|
|||
|
||||
Note that the `toc` global is a flat array, so you can easily cut out unwanted nodes or insert extra nodes, and create a new TOC tree.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
|
|
|
|||
|
|
@ -351,7 +351,7 @@ We recommend extracting the complex embedded JSX code as separate standalone com
|
|||
|
||||
To deploy Docusaurus, run the following command:
|
||||
|
||||
````mdx-code-block
|
||||
````mdx-code-block
|
||||
import Tabs from '@theme/Tabs';
|
||||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
|
|
|||
|
|
@ -53,9 +53,10 @@ In this presentation at [Algolia Community Event](https://www.algolia.com/), [Me
|
|||
```mdx-code-block
|
||||
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
|
||||
|
||||
{/* cSpell:ignore Yhyx Sksg */}
|
||||
|
||||
<div className="video-container">
|
||||
<LiteYouTubeEmbed
|
||||
// cSpell:ignore Yhyx Sksg
|
||||
id="Yhyx7otSksg"
|
||||
params="autoplay=1&autohide=1&showinfo=0&rel=0"
|
||||
title="Docusaurus: Documentation Made Easy"
|
||||
|
|
@ -129,18 +130,6 @@ Docusaurus 2 is born to be compassionately accessible to all your users, and lig
|
|||
|
||||
We believe that, as developers, knowing how a library works helps us become better at using it. Hence we're dedicating effort to explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.
|
||||
|
||||
<!--
|
||||
|
||||
Explain the principles that guide the development of Docusaurus.
|
||||
|
||||
References
|
||||
---
|
||||
- https://www.gatsbyjs.org/docs/behind-the-scenes/
|
||||
- https://reactjs.org/docs/design-principles.html
|
||||
- https://v1.vuepress.vuejs.org/miscellaneous/design-concepts.html
|
||||
|
||||
-->
|
||||
|
||||
## Comparison with other tools {#comparison-with-other-tools}
|
||||
|
||||
Across all static site generators, Docusaurus has a unique focus on documentation sites and has many out-of-the-box features.
|
||||
|
|
|
|||
|
|
@ -247,7 +247,7 @@ Still, you can reuse the [Infima CSS variables](styling-layout.mdx#styling-your-
|
|||
|
||||
### Customizing the Algolia search behavior {#customizing-the-algolia-search-behavior}
|
||||
|
||||
<!-- TODO: update options link once the documentation is available on the DocSearch website -->
|
||||
{/* TODO: update options link once the documentation is available on the DocSearch website */}
|
||||
|
||||
Algolia DocSearch supports a [list of options](https://autocomplete-experimental.netlify.app/docs/DocSearchModal#reference) that you can pass to the `algolia` field in the `docusaurus.config.js` file.
|
||||
|
||||
|
|
|
|||
|
|
@ -69,7 +69,7 @@ Accepted fields:
|
|||
| `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.description` | `string` | <code>\`$\{siteConfig.title} Blog\`</code> | Description of the feed. |
|
||||
| `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
|
||||
| `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. |
|
||||
| `sortPosts` | <code>'descending' \| 'ascending' </code> | `'descending'` | Governs the direction of blog post sorting. |
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@ Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
|
|||
|
||||
If you use [Prettier](https://prettier.io) to format your Markdown files, Prettier might auto-format your code to invalid admonition syntax. To avoid this problem, add empty lines around the starting and ending directives. This is also why the examples we show here all have empty lines around the content.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```md
|
||||
<!-- Prettier doesn't change this -->
|
||||
:::note
|
||||
|
|
@ -110,7 +110,7 @@ Hello world
|
|||
You may also specify an optional title.
|
||||
|
||||
```md
|
||||
:::note Your Title
|
||||
:::note Your Title
|
||||
|
||||
Some **content** with _Markdown_ `syntax`.
|
||||
|
||||
|
|
@ -138,7 +138,9 @@ import Tabs from '@theme/Tabs';
|
|||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
:::tip Use tabs in admonitions
|
||||
:::tip
|
||||
|
||||
Use tabs in admonitions
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
|
||||
|
|
@ -152,7 +154,9 @@ import TabItem from '@theme/TabItem';
|
|||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
||||
:::tip Use tabs in admonitions
|
||||
:::tip
|
||||
|
||||
Use tabs in admonitions
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
|
||||
|
|
@ -197,10 +201,8 @@ The types that are accepted are the same as above: `note`, `tip`, `danger`, `inf
|
|||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<Admonition type="tip" icon="💡" title="Did you know...">
|
||||
<p>
|
||||
Use plugins to introduce shorter syntax for the most commonly used JSX
|
||||
elements in your project.
|
||||
</p>
|
||||
Use plugins to introduce shorter syntax for the most commonly used JSX
|
||||
elements in your project.
|
||||
</Admonition>
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
|
|
|||
|
|
@ -64,8 +64,8 @@ export const Highlight = ({children, color}) => (
|
|||
|
||||
<BrowserWindow minHeight={240}>
|
||||
|
||||
<Highlight color="#25c2a0">Docusaurus green</Highlight>
|
||||
{` `}and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
|
||||
<><Highlight color="#25c2a0">Docusaurus green</Highlight>
|
||||
{` `}and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.</>
|
||||
|
||||
I can write **Markdown** alongside my _JSX_!
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ I can write **Markdown** alongside my _JSX_!
|
|||
|
||||
Since all doc files are parsed using MDX, anything that looks like HTML is actually JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
/* Instead of this: */
|
||||
<span style="background-color: red">Foo</span>
|
||||
|
|
@ -94,7 +94,7 @@ In addition, MDX is not [100% compatible with CommonMark](https://github.com/fac
|
|||
|
||||
You can also import your own components defined in other files or third-party components installed via npm.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```md
|
||||
<!-- Docusaurus theme component -->
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
|
@ -341,7 +341,7 @@ Use JSX within JSX tag, or move the Markdown to the outer layer:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
**Bold still doesn't work**
|
||||
|
|
@ -367,7 +367,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -397,7 +397,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -427,7 +427,7 @@ Don't indent:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -463,14 +463,13 @@ npm install --save raw-loader
|
|||
|
||||
Now you can import code snippets from another file as it is:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="myMarkdownFile.mdx"
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
import MyComponentSource from '!!raw-loader!./myComponent';
|
||||
|
||||
<CodeBlock language="jsx">{MyComponentSource}</CodeBlock>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
|
|
@ -509,13 +508,12 @@ By convention, using the **`_` filename prefix** will not create any doc page an
|
|||
This is text some content from `_markdown-partial-example.mdx`.
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="someOtherDoc.mdx"
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
||||
<PartialExample name="Sebastien" />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ import styles from './markdown-features-tabs-styles.module.css';
|
|||
|
||||
Docusaurus provides the `<Tabs>` component that you can use in Markdown thanks to [MDX](./markdown-features-react.mdx):
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
|
@ -32,7 +32,6 @@ import TabItem from '@theme/TabItem';
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
|
@ -250,7 +249,7 @@ You might want to customize the appearance of a certain set of tabs. You can pas
|
|||
|
||||
You can also customize each tab heading independently by using the `attributes` field. The extra props can be passed to the headings either through the `values` prop in `Tabs`, or props of each `TabItem`—in the same way as you declare `label`.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx title="some-doc.mdx"
|
||||
import styles from './styles.module.css';
|
||||
|
||||
|
|
@ -266,7 +265,6 @@ import styles from './styles.module.css';
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
```css title="styles.module.css"
|
||||
.red {
|
||||
|
|
|
|||
|
|
@ -43,8 +43,8 @@ Generated IDs have **some limitations**:
|
|||
|
||||
A special Markdown syntax lets you set an **explicit heading id**:
|
||||
|
||||
```md
|
||||
### Hello World {#my-explicit-id}
|
||||
```mdx-code-block
|
||||
<Code language="md">{'### Hello World \u007B#my-explicit-id}\n'}</Code>
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
|
@ -102,7 +102,7 @@ It is also possible to display an inline table of contents directly inside a Mar
|
|||
|
||||
The `toc` variable is available in any MDX document and contains all the headings of an MDX document. By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel` for individual `TOCInline` components.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
|
|
@ -129,7 +129,7 @@ declare const toc: {
|
|||
|
||||
Note that the `toc` global is a flat array, so you can easily cut out unwanted nodes or insert extra nodes, and create a new TOC tree.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
|
|
|
|||
|
|
@ -351,7 +351,7 @@ We recommend extracting the complex embedded JSX code as separate standalone com
|
|||
|
||||
To deploy Docusaurus, run the following command:
|
||||
|
||||
````mdx-code-block
|
||||
````mdx-code-block
|
||||
import Tabs from '@theme/Tabs';
|
||||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
|
|
|||
|
|
@ -50,12 +50,13 @@ Or read the **[5-minute tutorial](https://tutorial.docusaurus.io)** online.
|
|||
|
||||
In this presentation at [Algolia Community Event](https://www.algolia.com/), [Meta Open Source team](https://opensource.facebook.com/) shared a brief walk-through of Docusaurus. They covered how to get started with the project, enable plugins, and set up functionalities like documentation and blogging.
|
||||
|
||||
{/* cSpell:ignore Yhyx Sksg */}
|
||||
|
||||
```mdx-code-block
|
||||
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
|
||||
|
||||
<div className="video-container">
|
||||
<LiteYouTubeEmbed
|
||||
// cSpell:ignore Yhyx Sksg
|
||||
id="Yhyx7otSksg"
|
||||
params="autoplay=1&autohide=1&showinfo=0&rel=0"
|
||||
title="Docusaurus: Documentation Made Easy"
|
||||
|
|
@ -129,18 +130,6 @@ Docusaurus 2 is born to be compassionately accessible to all your users, and lig
|
|||
|
||||
We believe that, as developers, knowing how a library works helps us become better at using it. Hence we're dedicating effort to explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.
|
||||
|
||||
<!--
|
||||
|
||||
Explain the principles that guide the development of Docusaurus.
|
||||
|
||||
References
|
||||
---
|
||||
- https://www.gatsbyjs.org/docs/behind-the-scenes/
|
||||
- https://reactjs.org/docs/design-principles.html
|
||||
- https://v1.vuepress.vuejs.org/miscellaneous/design-concepts.html
|
||||
|
||||
-->
|
||||
|
||||
## Comparison with other tools {#comparison-with-other-tools}
|
||||
|
||||
Across all static site generators, Docusaurus has a unique focus on documentation sites and has many out-of-the-box features.
|
||||
|
|
|
|||
|
|
@ -247,7 +247,7 @@ Still, you can reuse the [Infima CSS variables](styling-layout.mdx#styling-your-
|
|||
|
||||
### Customizing the Algolia search behavior {#customizing-the-algolia-search-behavior}
|
||||
|
||||
<!-- TODO: update options link once the documentation is available on the DocSearch website -->
|
||||
{/* TODO: update options link once the documentation is available on the DocSearch website */}
|
||||
|
||||
Algolia DocSearch supports a [list of options](https://autocomplete-experimental.netlify.app/docs/DocSearchModal#reference) that you can pass to the `algolia` field in the `docusaurus.config.js` file.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue