mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-18 03:26:57 +02:00
docs(website): use MDX comments instead of HTML comments (#8516)
This commit is contained in:
Sébastien Lorber
GitHub
parent
5a59378e11
commit
9c9d17d6aa
38 changed files with 79 additions and 151 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
|
||||
|
||||
|
|
|
|||
|
|
@ -27,7 +27,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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 = {
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ The [front matter](./guides/markdown-features/markdown-features-intro.mdx#front-
|
|||
|
||||
The blog's index page (by default, it is at `/blog`) is the _blog list page_, where all blog posts are collectively displayed.
|
||||
|
||||
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:
|
||||
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
|
||||
---
|
||||
|
|
@ -87,7 +87,7 @@ All these will be part of the blog post summary.
|
|||
|
||||
Even this.
|
||||
|
||||
<!--truncate-->
|
||||
<!-- truncate -->
|
||||
|
||||
But anything from here on down will not be.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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';
|
||||
|
|
@ -339,7 +339,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**
|
||||
|
|
@ -365,7 +365,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -395,7 +395,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -425,7 +425,7 @@ Don't indent:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -461,14 +461,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';
|
||||
|
|
@ -507,13 +506,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 {
|
||||
|
|
|
|||
|
|
@ -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';
|
||||
|
||||
|
|
|
|||
|
|
@ -129,18 +129,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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 = {
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ The [front matter](./guides/markdown-features/markdown-features-intro.mdx#front-
|
|||
|
||||
The blog's index page (by default, it is at `/blog`) is the _blog list page_, where all blog posts are collectively displayed.
|
||||
|
||||
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:
|
||||
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
|
||||
---
|
||||
|
|
@ -87,7 +87,7 @@ All these will be part of the blog post summary.
|
|||
|
||||
Even this.
|
||||
|
||||
<!--truncate-->
|
||||
<!-- truncate -->
|
||||
|
||||
But anything from here on down will not be.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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';
|
||||
|
|
@ -339,7 +339,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**
|
||||
|
|
@ -365,7 +365,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -395,7 +395,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -425,7 +425,7 @@ Don't indent:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -461,14 +461,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';
|
||||
|
|
@ -507,13 +506,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 {
|
||||
|
|
|
|||
|
|
@ -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';
|
||||
|
||||
|
|
|
|||
|
|
@ -129,18 +129,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 = {
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ The [front matter](./guides/markdown-features/markdown-features-intro.mdx#front-
|
|||
|
||||
The blog's index page (by default, it is at `/blog`) is the _blog list page_, where all blog posts are collectively displayed.
|
||||
|
||||
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:
|
||||
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
|
||||
---
|
||||
|
|
@ -87,7 +87,7 @@ All these will be part of the blog post summary.
|
|||
|
||||
Even this.
|
||||
|
||||
<!--truncate-->
|
||||
<!-- truncate -->
|
||||
|
||||
But anything from here on down will not be.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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';
|
||||
|
|
@ -339,7 +339,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**
|
||||
|
|
@ -365,7 +365,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -395,7 +395,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -425,7 +425,7 @@ Don't indent:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -461,14 +461,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';
|
||||
|
|
@ -507,13 +506,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 {
|
||||
|
|
|
|||
|
|
@ -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';
|
||||
|
||||
|
|
|
|||
|
|
@ -129,18 +129,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 = {
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ The [front matter](./guides/markdown-features/markdown-features-intro.mdx#front-
|
|||
|
||||
The blog's index page (by default, it is at `/blog`) is the _blog list page_, where all blog posts are collectively displayed.
|
||||
|
||||
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:
|
||||
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
|
||||
---
|
||||
|
|
@ -87,7 +87,7 @@ All these will be part of the blog post summary.
|
|||
|
||||
Even this.
|
||||
|
||||
<!--truncate-->
|
||||
<!-- truncate -->
|
||||
|
||||
But anything from here on down will not be.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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';
|
||||
|
|
@ -339,7 +339,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**
|
||||
|
|
@ -365,7 +365,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -395,7 +395,7 @@ Add an empty new line:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -425,7 +425,7 @@ Don't indent:
|
|||
<div className={styles.wrappingBlock}>
|
||||
```
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
{/* prettier-ignore */}
|
||||
```jsx
|
||||
<div style={{color: 'red'}}>
|
||||
|
||||
|
|
@ -461,14 +461,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';
|
||||
|
|
@ -507,13 +506,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 {
|
||||
|
|
|
|||
|
|
@ -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';
|
||||
|
||||
|
|
|
|||
|
|
@ -129,18 +129,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.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue