mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-29 10:17:55 +02:00
129 lines
3.8 KiB
Text
129 lines
3.8 KiB
Text
---
|
|
id: introduction
|
|
title: Markdown Features
|
|
sidebar_label: Introduction
|
|
description: Docusaurus uses MDX. Find out more about Docusaurus-specific features when writing Markdown.
|
|
slug: /markdown-features
|
|
---
|
|
|
|
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 documentation 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.
|
|
|
|
:::important
|
|
|
|
This section assumes you are using the official Docusaurus content plugins.
|
|
|
|
:::
|
|
|
|
## Standard features {#standard-features}
|
|
|
|
Markdown is a syntax that enables you to write formatted content in a readable syntax.
|
|
|
|
We use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax), like rendering React components inside your documents as well.
|
|
|
|
```md
|
|
### My Doc Section
|
|
|
|
Hello world message with some **bold** text, some _italic_ text, and a [link](/)
|
|
|
|
|
|
```
|
|
|
|
```mdx-code-block
|
|
<BrowserWindow>
|
|
|
|
<h3>My Doc Section</h3>
|
|
|
|
Hello world message with some **bold** text, some _italic_ text and a [link](/)
|
|
|
|
|
|
|
|
</BrowserWindow>
|
|
```
|
|
|
|
<details>
|
|
|
|
<summary>Markdown is declarative</summary>
|
|
|
|
Some may assume a 1-1 correlation between Markdown and HTML, e.g., `` will always become `<img src="/img/docusaurus.png" alt="Preview" />`, as-is. However, _that is not the case_.
|
|
|
|
The Markdown syntax `` only declaratively tells Docusaurus that an image needs to be inserted here, but we may do other things like transforming a [file path to URL path](./markdown-features-assets.mdx#images), so the generated markup may differ from the output of other Markdown renderers, or a naïve hand-transcription to the equivalent JSX/HTML code.
|
|
|
|
In general, you should only assume the _semantics_ of the markup (` ``` ` fences become [code blocks](./markdown-features-code-blocks.mdx); `>` becomes [quotes](#quotes), etc.), but not the actual compiled output.
|
|
|
|
</details>
|
|
|
|
## Quotes {#quotes}
|
|
|
|
Markdown quotes are beautifully styled:
|
|
|
|
```md
|
|
> Easy to maintain open source documentation websites.
|
|
>
|
|
> — Docusaurus
|
|
```
|
|
|
|
<BrowserWindow>
|
|
|
|
> Easy to maintain open source documentation websites.
|
|
>
|
|
> — Docusaurus
|
|
|
|
</BrowserWindow>
|
|
|
|
## Details {#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>
|
|
<br/>
|
|
<details>
|
|
<summary>
|
|
Nested toggle! Some surprise inside...
|
|
</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>
|
|
<br/>
|
|
<details>
|
|
<summary>
|
|
Nested toggle! Some surprise inside...
|
|
</summary>
|
|
<div>
|
|
😲😲😲😲😲
|
|
</div>
|
|
</details>
|
|
</div>
|
|
</details>
|
|
|
|
</BrowserWindow>
|
|
```
|
|
|
|
:::note
|
|
|
|
In practice, those are not really HTML elements, but React JSX elements, which we'll cover next!
|
|
|
|
:::
|