docs: use BrowserWindow for Markdown demos (#6215)

This commit is contained in:
Joshua Chen 2021-12-29 13:49:09 +08:00 committed by GitHub
parent 5132ecdeee
commit 0fa091a0c2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
9 changed files with 101 additions and 32 deletions

View file

@ -5,6 +5,8 @@ description: Handling code blocks in Docusaurus Markdown
slug: /markdown-features/code-blocks
---
import BrowserWindow from '@site/src/components/BrowserWindow';
Code blocks within documentation are super-powered 💪.
## Code title {#code-title}
@ -17,12 +19,16 @@ You can add a title to the code block by adding a `title` key after the language
}
```
<BrowserWindow>
```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
```
</BrowserWindow>
## Syntax highlighting {#syntax-highlighting}
Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for the specifications of MDX.
@ -35,10 +41,14 @@ Code blocks are text blocks wrapped around by strings of 3 backticks. You may ch
Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer).
<BrowserWindow>
```jsx
console.log('Every repo must come with a mascot.');
```
</BrowserWindow>
### Theming {#theming}
By default, the Prism [syntax highlighting theme](https://github.com/FormidableLabs/prism-react-renderer#theming) we use is [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js). You can change this to another theme by passing `theme` field in `prism` as `themeConfig` in your docusaurus.config.js.
@ -134,6 +144,9 @@ You can use comments with `highlight-next-line`, `highlight-start`, and `highlig
}
```
````mdx-code-block
<BrowserWindow>
```jsx
function HighlightSomeText(highlight) {
if (highlight) {
@ -155,6 +168,9 @@ function HighlightMoreText(highlight) {
}
```
</BrowserWindow>
````
Supported commenting syntax:
| Language | Syntax |
@ -201,6 +217,8 @@ You can also specify highlighted line ranges within the language meta string (le
export default MyComponent;
```
<BrowserWindow>
```jsx {1,4-6,11}
import React from 'react';
@ -215,6 +233,8 @@ function MyComponent(props) {
export default MyComponent;
```
</BrowserWindow>
:::tip prefer comments
Prefer highlighting with comments where you can. By inlining highlight in the code, you don't have to manually count the lines if your code block becomes long. If you add/remove lines, you also don't have to offset your line ranges.
@ -286,6 +306,8 @@ To use the plugin, create a code block with `live` attached to the language meta
The code block will be rendered as an interactive editor. Changes to the code will reflect on the result panel live.
<BrowserWindow>
```jsx live
function Clock(props) {
const [date, setDate] = useState(new Date());
@ -309,6 +331,8 @@ function Clock(props) {
}
```
</BrowserWindow>
### Imports {#imports}
:::caution react-live and imports
@ -353,6 +377,8 @@ export default ReactLiveScope;
The `ButtonExample` component is now available to use:
<BrowserWindow>
```jsx live
function MyPlayground(props) {
return (
@ -363,6 +389,8 @@ function MyPlayground(props) {
}
```
</BrowserWindow>
## Using JSX markup in code blocks
Code block in Markdown always preserves its content as plain text, meaning you can't do something like:
@ -388,10 +416,12 @@ If you want to embed HTML markup such as anchor links or bold type, you can use
</pre>
```
<pre>
<b>Input: </b>1 2 3 4{'\n'}
<b>Output: </b>"366300745"{'\n'}
</pre>
<BrowserWindow>
<pre>
<b>Input: </b>1 2 3 4{'\n'}
<b>Output: </b>"366300745"{'\n'}
</pre>
</BrowserWindow>
:::caution MDX is whitespace insensitive
@ -452,6 +482,7 @@ class HelloWorld {
And you will get the following:
````mdx-code-block
<BrowserWindow>
<Tabs>
<TabItem value="js" label="JavaScript">
@ -482,6 +513,7 @@ class HelloWorld {
</TabItem>
</Tabs>
</BrowserWindow>
````
If you have multiple of these multi-language code tabs, and you want to sync the selection across the tab instances, refer to the [Syncing tab choices section](markdown-features-tabs.mdx#syncing-tab-choices).