3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-10 07:37:19 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: multiple documentation improvements (#7126)

Browse source
This commit is contained in:
Joshua Chen 2022-04-07 16:27:28 +08:00 • committed by GitHub
parent 2c61bf2568
commit 3cdd038d28
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 125 additions and 113 deletions
Download patch file Download diff file Expand all files Collapse all files

8
website/docs/guides/creating-pages.md
View file

@ -7,11 +7,7 @@ sidebar_label: Pages
In this section, we will learn about creating pages in Docusaurus.
This is useful for creating **one-off standalone pages** like a showcase page, playground page, or support page.
The functionality of pages is powered by `@docusaurus/plugin-content-pages`.
You can use React components, or Markdown.
The `@docusaurus/plugin-content-pages` plugin empowers you to create **one-off standalone pages** like a showcase page, playground page, or support page. You can use React components, or Markdown.
:::note
@ -69,7 +65,7 @@ You can also create TypeScript pages with the `.tsx` extension (`helloReact.tsx`
Create a file `/src/pages/helloMarkdown.md`:
```mdx title="/src/pages/helloMarkdown.md"
```md title="/src/pages/helloMarkdown.md"
---
title: my hello page title
description: my hello page description

18
website/docs/guides/markdown-features/markdown-features-intro.mdx
View file

@ -2,7 +2,7 @@
id: introduction
title: Markdown Features
sidebar_label: Introduction
description: Docusaurus uses GitHub Flavored Markdown (GFM). Find out more about Docusaurus-specific features when writing Markdown.
description: Docusaurus uses MDX. Find out more about Docusaurus-specific features when writing Markdown.
slug: /markdown-features
---
@ -22,7 +22,7 @@ This section assumes you are using the official Docusaurus content plugins.
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.
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
@ -35,7 +35,7 @@ Hello world message with some **bold** text, some _italic_ text, and a [link](/)
```mdx-code-block
<BrowserWindow>
<h2>My Doc Section</h2>
<h3>My Doc Section</h3>
Hello world message with some **bold** text, some _italic_ text and a [link](/)
@ -44,6 +44,18 @@ 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., `![Preview](/img/docusaurus.png)` will always become `<img src="/img/docusaurus.png" alt="Preview" />`, as-is. However, _that is not the case_.
The Markdown syntax `![message](url)` 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: