跳到主要内容

docusaurus博客常用的文档样式

阅读需 6 分钟

在写文档的时候，我有时会觉得单纯的markdown语法不能将我要表达的内容清楚地表达出来，或者是显示的样式并不美观。这时候，我们可以用docusaurus支持的 .mdx 文件类型来编写我们的文档。在这个类型的文档中，我们可以加入 javascript 语法，引入 JSX 组件，利用组件使得内容更加清晰，更加美观。

这篇文章主要用来记录我用过的文档中的样式，并且给了相应的链接。

JSX 组件​

这个博客的特点就是引入了 mdx v3，这让我们在写 markdown 文档的时候可以使用 JSX 组件。若要使用组件，可以查阅下面资料来了解相关内容：

高亮块​

有两种方式可以采用：导出组件，导入组件

导出组件​

当我们在页面中自定义组件的时候，我们需要导出这个组件，只有使用export的时候不会被解释为markdown语法，才能正常使用自定义组件。

export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '2px',
      color: '#fff',
      padding: '0.2rem',
    }}>
    {children}
  </span>
);
使用这个组件markup
<Highlight color="#25c2a0">Docusaurus green</Highlight> and 
<Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.

绿色高亮 and 蓝色高亮

导入组件​

还有一种更简单的方式，我们可以将这个高亮样式定义为一个组件，需要的时候直接导入组件即可。

我们将组件定义在@site/src/components路径下，组件文件夹下至少要包含一个文件index.json，这个文件描述了组件的内容。若想调整样式，我们可以在组件文件夹下加上一个style.module.css文件来配置组件的样式。

index.jsonjavascript
import React from 'react'

// 这里color使用了默认值，若没有传值，则默认这个颜色
function Highlight({children, color="#fbb656"}) {
    return (
        <span style={{
            backgroundColor: color,
            borderRadius: '2px',
            color: '#fff',
            padding: '0.2rem',
        }}>
        {children}
        </span>
    )
}

export default Highlight
使用高亮组件markup
import HighLight from '@site/src/components/HighLight'

<HighLight>默认颜色</HighLight> 和 <HighLight color="#25c2a0">绿色

默认颜色 和 绿色

选项卡​

官网文档讲述了选项卡如何导入，自定义选项卡。更多选项卡样式查看官方文档

一个选项卡​

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="apple" label="Apple" default>
    This is an apple 🍎
  </TabItem>
  <TabItem value="orange" label="Orange">
    This is an orange 🍊
  </TabItem>
  <TabItem value="banana" label="Banana">
    This is a banana 🍌
  </TabItem>
</Tabs>

This is an apple 🍎

多个选项卡​

当选项卡有多个的时候，我们可以选择这些选项卡是否同步，若选项卡的选择需要同步的时候，我们就给这些选项卡设置相同的groupId属性

<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>
Use Ctrl + C to copy.
Use Ctrl + V to paste.

若选项卡的选择不需要同步，就设置不同的groupId即可

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">Windows in windows.</TabItem>
  <TabItem value="mac" label="macOS">macOS is macOS.</TabItem>
</Tabs>

<Tabs groupId="non-mac-operating-systems">
  <TabItem value="win" label="Windows">Windows is windows.</TabItem>
  <TabItem value="unix" label="Unix">Unix is unix.</TabItem>
</Tabs>
Windows in windows.
Windows is windows.

折叠块​

<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>
Toggle me!
This is the detailed content

Nested toggle! Some surprise inside...

😲😲😲😲😲

链接​

连接到当前文档的其他部分​

[高亮](#高亮块)

高亮

连接到另一个文档​

对博客主题的修改

代码块​

常见的代码块配置有以下几个

  1. 代码块的题目 详情
  2. 代码块的语法高亮 详情
  3. 代码块的行高亮 详情
  4. 代码块的行数 详情
  5. 可交互的代码块 详情
  6. 多语言代码块（例子：多个tab用不同的语言） 详情
代码块实例jsx
import React from 'react';

function MyComponent(props) {
  if (props.isBar) {
    return <div>Bar</div>;
  }

  return <div>Foo</div>;
}

export default MyComponent;

告示​

  1. 告示注意事项 详情
  2. 告示自定义题目 详情
  3. 告示可以嵌套 详情
  4. 告示里面可以用MDX 详情
  5. 告示可以用别的方法，如用JSX来实现 详情
  6. 告示可以自定义样式 详情
:::note[告示]

这是一条告示

:::
告示

这是一条告示

浏览器窗口​

  • 官方浏览器窗口样式
官方浏览器窗口样式javascript
import BrowserWindow from '@site/src/components/BrowserWindow';

<BrowserWindow url={"https://drbear.vercel.app"}>
欢迎来到小熊博士的小窝！
</BrowserWindow>
https://drbear.vercel.app

欢迎来到小熊博士的小窝！

shake博主设计的浏览器窗口样式javascript
import BrowserWindow from '@site/src/components/BrowserWindow';

<BrowserWindow url={"https://drbear.vercel.app"}>
欢迎来到小熊博士的小窝！
</BrowserWindow>
https://drbear.vercel.app

欢迎来到小熊博士的小窝！

标题和目录​

标题就用markdown的标准语法即可，而目录有自动生成的方法。可以查看官方文档。

资源​

图片、文件、内嵌图片

其他​

后续内容用到了再补充

Loading Comments...
0%