文档编辑指南
这里总结了一些我觉得自己比较常用的 Docusaurus 写作样式，参考自官方文档以及源码。
MDX 与 React
Docusaurus 原生支持 MDX v1，可以直接在 Markdown 文档中编写 JSX，并渲染为 React 组件，不过我比较喜欢以导入组件的方式进行引用。关于 MDX 的更多内容可以去阅读官方文档
高亮块
👉这是 HighLight 的效果
导出组件
可以选择直接在 md/mdx 文件里自定义组件，只需导出它即可，以 export 开头的段落即可被解析为组件，而不是文本。
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
<Highlight color="#25c2a0">Docusaurus 绿</Highlight> 和 <Highlight color="#1877F2">Facebook 蓝</Highlight>
效果如下：
Docusaurus 绿 和 Facebook 蓝
导入组件
我喜欢简便一点的方式，并且不需要灵活切换高亮颜色，所以将它封装为组件，用导入的方式进行使用
import HighLight from "@site/src/components/HighLight"
<HighLight>这是 HighLight 的效果</HighLight>
效果如下：
👉这是 HighLight 的效果
选项卡
- Apple
- Orange
- Banana
This is an apple 🍎
This is an orange 🍊
This is a banana 🍌
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 🍊<br/></TabItem>
<TabItem value="banana">This is a banana 🍌<br/></TabItem>
</Tabs>
还可以设置同步选项，减少重复性操作
- Windows
- macOS
Use Ctrl + C to copy.
Use Command + C to copy.
- Windows
- macOS
Use Ctrl + V to paste.
Use Command + V to paste.
<Tabs groupId="operating-systems">
<TabItem value="win" label="Windows">Use Ctrl + C to copy.</TabItem>
<TabItem value="mac" label="macOS">Use Command + C to copy.</TabItem>
</Tabs>
<Tabs groupId="operating-systems">
<TabItem value="win" label="Windows">Use Ctrl + V to paste.</TabItem>
<TabItem value="mac" label="macOS">Use Command + V to paste.</TabItem>
</Tabs>
根据 groupId 来进行关联，不同的 groupId 会有不同的效果
- Windows
- macOS
- Linux
I am Windows.
I am macOS.
I am Linux.
- Windows
- macOS
- Unix
I am Windows.
I am macOS.
Unix is unix.
<Tabs groupId="operating-systems">
<TabItem value="win" label="Windows">I am Windows.</TabItem>
<TabItem value="mac" label="macOS">I am macOS.</TabItem>
<TabItem value="linux" label="Linux">I am Linux.</TabItem>
</Tabs>
<Tabs groupId="test">
<TabItem value="win" label="Windows">I am Windows.</TabItem>
<TabItem value="mac" label="macOS">I am macOS.</TabItem>
<TabItem value="unix" label="Unix">Unix is unix.</TabItem>
</Tabs>
折叠块
Toggle me!
This is the detailed content
Nested toggle! Some surprise inside...
😲😲😲😲😲
Testing...
🤨
<details>
<summary>Toggle me!</summary>
<div>
<div>This is the detailed content</div>
<br/>
<details>
<summary>Nested toggle! Some surprise inside...</summary>
<div>😲😲😲😲😲</div>
<br/>
<details>
<summary>Testing...</summary>
<div>🤨</div>
</details>
</details>
</div>
</details>
选项块里也可以嵌入折叠块（其他组件也可以类似地进行嵌套）
- One
- Two
One!
Toggle me!
This is the detailed content
Nested toggle! Some surprise inside...
😲😲😲😲😲
Two!
告示块
备注
note
👋
note 自定义标题
提示
tip
信息
info
警告
caution
危险
danger
:::note
**note**
:::
:::note 👋
**note** 自定义标题
:::
:::tip
**tip**
:::
:::info
**info**
:::
:::caution
**caution**
:::
:::danger
**danger**
:::
代码块
比如下面一段代码
ts 表示用 ts 语言渲染代码块
{1,4,6-8} 表示第 1 行、第 4 行、第 6-8 行代码高亮，分开的用 , 隔开，连续的用 - 连接
title 表示代码块的标题
```ts {1,4,6-8} title="src/clientModules/routeModules.ts"
your code...
```
src/clientModules/routeModules.ts
import mitt from 'mitt';
import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
const emitter = mitt();
if (ExecutionEnvironment.canUseDOM) {
window.emitter = emitter;
}
export function onRouteDidUpdate() {
if (ExecutionEnvironment.canUseDOM) {
setTimeout(() => {
window.emitter.emit('onRouteDidUpdate');
});
}
// https://github.com/facebook/docusaurus/issues/8278
}
下面的代码块用于表示代码的修改
````diff
+ code_1
- code_2
````
module.exports = {
+ themeConfig: {
- algolia: {
appId: 'YOUR_APP_ID', // Application ID
apiKey: 'YOUR_SEARCH_API_KEY', // Search-Only API Key
indexName: 'YOUR_INDEX_NAME' // Index name
}
}
};
外链标识
import HyperLink from "@site/src/components/HyperLink";
- <HyperLink type="external" link="https://www.cordcloud.biz/">
CordCloud
</HyperLink>
- <HyperLink type="external" link="https://cyoooo.co/">
KuLi
</HyperLink>
（Testing）
不过我觉得有点麻烦，还不如用普通的外链语法，这个标识要不要无所谓
内嵌 bilibili 视频
import BVideo from "@site/src/components/BVideo";
<BVideo src="//player.bilibili.com/player.html?aid=379284479&bvid=BV17f4y1M7mq&cid=445379085&page=1" width="100%" height="360" frameborder="no" scrolling="no" allowfullscreen="allowfullscreen" bsrc="https://www.bilibili.com/video/BV17f4y1M7mq/"/>
但是引用的视频清晰度只有 360P
设置博客内部的跳转链接
跳转到当前文档
跳转到高亮块
跳转到[高亮块](#高亮块)
跳转到另一个文档
跳转到部署
跳转到[部署](/docs/Site/Docusaurus/部署.md)
跳转到部署-进阶部署
跳转到[部署-进阶部署](/docs/Site/Docusaurus/部署.md/#进阶部署)
跳转到目标文件
可以通过在 Markdown 文件中直接链接静态资源（比如 docx 文件、图片等）来获取目标文件，例如：
[在 Markdown 里下载这个 docx](@site/static/doc/example.docx)
快捷键样式
ctrl + Cimport Shortcut from "@site/src/components/Shortcut/index";
<Shortcut>ctrl</Shortcut> + <Shortcut>C</Shortcut>
图片 flex 布局
import DisplayFlex from '@site/src/components/DisplayFlex'
<DisplayFlex>
</DisplayFlex>
浏览窗口
浏览器窗口
这是官方样式的浏览器窗口
import BrowserWindow2 from '@site/src/components/BrowserWindow2';
// <BrowserWindow2 url="www.example.com">
<BrowserWindow2>
**这是官方样式的浏览器窗口**
</BrowserWindow2>
这是我根据开源样式修改的浏览器窗口
import BrowserWindow from '@site/src/components/BrowserWindow';
<BrowserWindow url="http://www.shaking.site">
**这是我根据开源样式修改的浏览器窗口**
</BrowserWindow>
阅读卡片窗口
这是根据开源样式设计的阅读卡片窗口
（用来写摘抄啥的）
摘自 —— xxxx
2023-xx-xx
import ReadingCard from '@site/src/components/ReadingCard'
<ReadingCard book="xxxx" date="2023-xx-xx">
这是根据开源样式设计的阅读卡片窗口<br/>
</ReadingCard>