mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-10 15:47:23 +02:00
feat: details/summary theme / MDX component (#5216)
* Details component * polish arrow animation * fix text selection bug * fix some edge cases + polish * example of overriding baseClassName * Move Details component to theme-common * make component work even when JS is disabled or failed to load * update arrow transform * Details component: better handling of no-JS fallback mode: avoid delaying arrow navigation when JS (see review) * prefix css vars with --docusaurus * improve css arrow styling * slightly change details/summary design * better md doc + include quotes and details in doc
This commit is contained in:
Sébastien Lorber
GitHub
parent
798f634007
commit
dc4664b489
13 changed files with 378 additions and 21 deletions
|
|
@ -0,0 +1,3 @@
|
|||
<span>Hello {props.name}</span>
|
||||
|
||||
This is text some content from `_markdown-partial-example.md`.
|
||||
|
|
@ -1,23 +1,115 @@
|
|||
---
|
||||
id: introduction
|
||||
title: Markdown Features introduction
|
||||
title: Markdown Features
|
||||
sidebar_label: Introduction
|
||||
description: Docusaurus uses GitHub Flavored Markdown (GFM). Find out more about Docusaurus-specific features when writing Markdown.
|
||||
slug: /markdown-features
|
||||
---
|
||||
|
||||
```mdx-code-block
|
||||
import BrowserWindow from '@site/src/components/BrowserWindow';
|
||||
```
|
||||
|
||||
Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible.
|
||||
|
||||
Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.
|
||||
|
||||
In this section, we'd like to introduce you to the tools we've picked that we believe will help you build a powerful documentation. Let us walk you through with an example.
|
||||
|
||||
Markdown is a syntax that enables you to write formatted content in a readable syntax.
|
||||
|
||||
The [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax) is supported, and we use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing Markdown, like rendering React components inside your documents.
|
||||
|
||||
:::important
|
||||
|
||||
This section assumes you are using the official Docusaurus content plugins.
|
||||
|
||||
:::
|
||||
|
||||
## Standard features
|
||||
|
||||
Markdown is a syntax that enables you to write formatted content in a readable syntax.
|
||||
|
||||
The [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax) is supported, and we use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing Markdown, like rendering React components inside your documents.
|
||||
|
||||
```md
|
||||
### My Doc Section
|
||||
|
||||
Hello world message with some **bold** text, some _italic_ text and a [link](/)
|
||||
|
||||
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
||||
<h2>My Doc Section</h2>
|
||||
|
||||
Hello world message with some **bold** text, some _italic_ text and a [link](/)
|
||||
|
||||
|
||||
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
## Quotes
|
||||
|
||||
Markdown quotes are beautifully styled:
|
||||
|
||||
```md
|
||||
> This is a quote
|
||||
```
|
||||
|
||||
> This is a quote
|
||||
|
||||
## Details
|
||||
|
||||
Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) HTML elements are beautifully styled:
|
||||
|
||||
```md
|
||||
### Details element example
|
||||
|
||||
<details>
|
||||
<summary>Toggle me!</summary>
|
||||
<div>
|
||||
<div>This is the detailed content</div>
|
||||
<details>
|
||||
<summary>
|
||||
<div>Nested toggle!</div>
|
||||
<div>Some surprise inside...</div>
|
||||
</summary>
|
||||
<div>
|
||||
😲😲😲😲😲
|
||||
</div>
|
||||
</details>
|
||||
</div>
|
||||
</details>
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
||||
<h3>Details element example</h3>
|
||||
|
||||
<details>
|
||||
<summary>Toggle me!</summary>
|
||||
<div>
|
||||
<div>This is the detailed content</div>
|
||||
<details>
|
||||
<summary>
|
||||
<div>Nested toggle!</div>
|
||||
<div>Some surprise inside...</div>
|
||||
</summary>
|
||||
<div>
|
||||
😲😲😲😲😲
|
||||
</div>
|
||||
</details>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
</BrowserWindow>
|
||||
|
||||
<br/>
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
In practice, those are not really HTML elements, but React JSX elements, which we'll cover next!
|
||||
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -1,11 +1,13 @@
|
|||
---
|
||||
id: react
|
||||
title: Using React
|
||||
title: MDX and React
|
||||
description: Using the power of React in Docusaurus Markdown documents, thanks to MDX
|
||||
slug: /markdown-features/react
|
||||
---
|
||||
|
||||
```mdx-code-block
|
||||
import BrowserWindow from '@site/src/components/BrowserWindow';
|
||||
```
|
||||
|
||||
## Using JSX in Markdown {#using-jsx-in-markdown}
|
||||
|
||||
|
|
@ -17,6 +19,14 @@ While both `.md` and `.mdx` files are parsed using MDX, some of the syntax are t
|
|||
|
||||
:::
|
||||
|
||||
:::caution
|
||||
|
||||
MDX is not [100% compatible with CommonMark](https://github.com/facebook/docusaurus/issues/3018).
|
||||
|
||||
Use the **[MDX playground](https://mdxjs.com/playground)** to ensure that your syntax is valid MDX.
|
||||
|
||||
:::
|
||||
|
||||
Try this block here:
|
||||
|
||||
```jsx
|
||||
|
|
@ -126,21 +136,27 @@ This feature is experimental and might be subject to API breaking changes in the
|
|||
|
||||
## Importing Markdown {#importing-markdown}
|
||||
|
||||
You can use Markdown files as components and import them elsewhere, either in Markdown files or in React pages. Below we are importing from [another file](./markdown-features-intro.mdx) and inserting it as a component.
|
||||
You can use Markdown files as components and import them elsewhere, either in Markdown files or in React pages.
|
||||
|
||||
```jsx
|
||||
import Intro from './markdown-features-intro.mdx';
|
||||
By convention, using the **`_` filename prefix** will not create any doc page and means the markdown file is a **"partial"**, to be imported by other files.
|
||||
|
||||
<Intro />;
|
||||
```md title="_markdown-partial-example.mdx"
|
||||
<span>Hello {props.name}</span>
|
||||
|
||||
This is text some content from `_markdown-partial-example.mdx`.
|
||||
```
|
||||
|
||||
```jsx title="someOtherDoc.mdx"
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
||||
<PartialExample name="Sebastien" />;
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
import Intro from './markdown-features-intro.mdx';
|
||||
import PartialExample from './_markdown-partial-example.mdx';
|
||||
|
||||
<BrowserWindow url="http://localhost:3000">
|
||||
|
||||
<Intro />
|
||||
|
||||
<PartialExample name="Sebastien" />
|
||||
</BrowserWindow>
|
||||
|
||||
<br />
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue