Awesome MDX
搭建博客的过程中遇到了一个新格式:.mdx
,它太 awesome 了,结合了 markdown 和 jsx 语法,这样页面内容就可以变得更加丰富多彩了!话虽如此,不过目前就单独的 markdown 基本够应付日常的博客笔记了...
不过仍值得学习,有备无患~
2021.4.9 记
虽然 mdx 很香,不过支持 Docusaurus 的 mdx 语法的工具不太好找 😢,原本写博客使用 typora + PicGo 非常方便,但是 typora 貌似并不支持 mdx 语法,在 typora 中写的话排版会很难受 ,而且还有部分语法解析规则不相同,总之就是丧失了一大利器
所以看来今后写博客只能在 VSCODE 上写了??更难受的是在 VSCODE 上下载了一个 MDX 文件的预览插件,但是这个插件并不能解析 Docusaurus 的路径解析 :
@site
语法,因此无法同步预览了,要查看效果只能在浏览器里查看,难受 😫这就是鱼和熊掌不可兼得吗,获得了更加丰富的表现能力就要在文章编辑效率上做出一定的舍弃 😩
支持的部分 Markdown 特性如下:
#
头部字段定义Front Matter,为文档提供一些基本信息
---slug: docid: my-doctitle: My document titledescription: My document descriptionsidebar_label: My doc---
Markdown content
#
超链接支持页面内的相对路径跳转和其他页面的绝对路径跳转:
相对路径的文件名称也可以是文章的头部字段中定义的 slug 值
Let's see how to [Link](./前言).
Let's see how to [Link](https://yleave.top/docs/).
Let's see how to Link.
新页面跳转:Let's see how to Link.
图片链接:可以使用相对路径来使用 static
路径下的图片: static/img/docusaurus.png
,当然也能使用绝对路径使用网络上的图片。

#
标注提供了很棒的标注语法,共有五种:
:::note
The content and title *can* include markdown.
:::
:::tip You can specify an optional title
Heads up! Here's a pro-tip.
:::
:::info
Useful information.
:::
:::caution
Warning! You better pay attention!
:::
:::danger
Danger danger, mayday!
:::
note
The content and title can include markdown.
You can specify an optional title
Heads up! Here's a pro-tip.
info
Useful information.
caution
Warning! You better pay attention!
danger
Danger danger, mayday!
#
React 组件Docusaurus 中支持 mdx 语法,即可以在 markdown 中使用 jsx 语法添加自定义组 React 组件,当这样使用的时候最好把文件后缀改成 .mdx
以便于更准确的解析和更好的编辑器支持:
export const Highlight = ({children, color}) => ( <span style={{ backgroundColor: color, borderRadius: '2px', color: 'red', padding: '0.2rem', }}> {children} </span>);
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
#
标签组Docusaurus 提供了 <Tabs>
组件,开箱即用(舒服:
import Tabs from '@theme/Tabs';import TabItem from '@theme/TabItem';
<Tabs defaultValue="apple" values={[ {label: 'Apple', value: 'apple'}, {label: 'Orange', value: 'orange'}, {label: 'Banana', value: 'banana'}, ]}> <TabItem value="apple">This is an apple 🍎</TabItem> <TabItem value="orange">This is an orange 🍊</TabItem> <TabItem value="banana">This is a banana 🍌</TabItem></Tabs>;
- Apple
- Orange
- Banana
可通过 groupId
来同步或创建多个标签组,也可以通过 className
自定义标签组的外观
info
默认情况下,标签组在加载之后就会立即渲染,但是你可以通过向 Tabs
组件传递 lazy
属性让该组件延迟加载。
#
代码块#
基本设置使用 ```
来创建代码块, 使用 title 字段定义代码标题:
```jsx title="src/components/HelloDocusaurus.js"function HelloDocusaurus() { return ( <h1>Hello, Docusaurus!</h1> )}```
function HelloDocusaurus() { return <h1>Hello, Docusaurus!</h1>;}
. 代码中的变化标记 diff:
```diff title="sidebars.js"module.exports = { docs: [ { type: 'category', label: 'Docusaurus Tutorial',- items: ['getting-started', 'create-a-doc', ...],+ items: ['getting-started', 'create-a-doc', 'hello', ...], }, ],};```
module.exports = { docs: [ { type: 'category', label: 'Docusaurus Tutorial',- items: ['getting-started', 'create-a-doc', ...],+ items: ['getting-started', 'create-a-doc', 'hello', ...], }, ],};
如设置第一行、设置第 4 ~ 6 行和第 11 行代码高亮,更多行号设置:
```jsx {1,4-6,11}import React from 'react';
function MyComponent(props) { if (props.isBar) { return <div>Bar</div>; }
return <div>Foo</div>;}
export default MyComponent;```
import React from 'react';
function MyComponent(props) { if (props.isBar) { return <div>Bar</div>; }
return <div>Foo</div>;}
export default MyComponent;
#
多语言代码块假如你精通各个语言的 hello world,那这个功能就非常好用了:
import Tabs from '@theme/Tabs';import TabItem from '@theme/TabItem';
<Tabs defaultValue="js" values={[ { label: 'JavaScript', value: 'js', }, { label: 'Python', value: 'py', }, { label: 'Java', value: 'java', }, ]}><TabItem value="js">
```jsfunction helloWorld() { console.log('Hello, world!');}```
</TabItem><TabItem value="py">
```pydef hello_world(): print 'Hello, world!'```
</TabItem><TabItem value="java">
```javaclass HelloWorld { public static void main(String args[]) { System.out.println("Hello, World"); }}```
</TabItem></Tabs>
- JavaScript
- Python
- Java
function helloWorld() { console.log('Hello, world!');}
def hello_world(): print 'Hello, world!'
class HelloWorld { public static void main(String args[]) { System.out.println("Hello, World"); }}
#
实时代码编辑器要使用这个功能需要安装 @docusaurus/theme-live-codeblock
插件:
- Npm
- Yarn
cnpm install --save @docusaurus/theme-live-codeblock
yarn add @docusaurus/theme-live-codeblock
然后再将其添加到 docusaurus.config.js
中:
module.exports = { // ... themes: ['@docusaurus/theme-live-codeblock'], // ...};
然后在代码块前加上 live
即可:```live
,RESULT 中的就是这段代码的运行结果:
#
内联目录也就是在文章开头显示文章的目录,已经有侧边目录功能了,这个就 pass。
import TOCInline from '@theme/TOCInline';
<TOCInline toc={toc} />;