使用技巧整理
这里积累 Docusaurus 使用过程中的小技巧点, 可以增加阅读体验
内容展示
1. 显示摘要
博客列表默认显示全部内容, 为了方便阅读, 使用 <!-- truncate --> 后, 列表页可以仅显示摘要内容, 方便预览
....摘要
// highlight-next-line
<!-- truncate -->
....正文
2. 博客设置草稿
未撰写好的博客，在打包的时候不希望显示在博客列表中，可设置该篇博客为草稿状态，默认未设置 draft 为发布状态
---
title: 发布时展示否
...
// highlight-next-line
draft: true
---
3. 文章详情页添加自定义模块
想要在每篇文章下方增加其他组件, 需要修改底层逻辑, (建议有 react 基础, 可以更好理解)
-
/src/components/下新实现全局组件helloWorld -
利用 Swizzle 来完成组件安装, 安装目录为
/src/theme/下pnpm run swizzle @docusaurus/theme-classic helloWorld --wrap -
引入组件
import React from 'react';
import BlogPostItem from '@theme-original/BlogPostItem';
import { useBlogPost } from '@docusaurus/theme-common/internal';
import WeChatFollowCard from '@site/src/components/helloWorld';
import useIsBrowser from '@docusaurus/useIsBrowser';
export default function BlogPostItemWrapper(props) {
const { metadata, isBlogPostPage } = useBlogPost()
const isBrowser = useIsBrowser();
const { frontMatter } = metadata
const { enable_comment: enableComment } = frontMatter
return (
<>
<BlogPostItem {...props} />
{
(enableComment && isBlogPostPage) && <helloWorld />
}
</>
);
}
文档
1. 文档定义为内部引用
我们知道所有 docs 下面的 .md 或 .mdx 后缀的文件都将作为文档里面的页面显示出来，如果某个文档只是被其它的文档所引用，我们只需将该文档的命名前面加上 _ 的前缀， 就好比我们命名私有变量一样
祥见文章MDX 和 React |Docusaurus 文档
2. 侧边栏折叠
themeConfig: {
docs: {
sidebar: {
hideable: true, // 允许隐藏整个侧边栏
autoCollapseCategories: true, // 展开一个类别时自动折叠其他类别
},
},
} satisfies Preset.ThemeConfig,
页面
1. 导入外部组件库
以引入 Material UI 为例，编写更丰富的用户界面。
详见文章 -> 如何将 Material UI 引入到 Docusaurus 中使用 参考文章 -> 代码块导入 | Docusaurus
2. 显示标题等级
默认博客和文档右侧会自动生成带标题的树状目录结构，这个可以通过配置项 hide_table_of_contents: false 来进行设置
显示的标题层级，默认只显示 h2 和 h3，如果要改变显示的标题层级，只需要设置最大和最小的标题层级即可
---
# 显示 h2 到 h5 标题
toc_min_heading_level: 2
toc_max_heading_level: 5
---
3. 默认主题色&切换开关
themeConfig: {
// Replace with your project's social card
image: 'img/docusaurus-social-card.jpg', //! 注意替换
/* 默认主题色 */
colorMode: {
defaultMode: 'dark',
disableSwitch: true,
},
} satisfies Preset.ThemeConfig,
MDX
1. 代码块高亮
将某一行设置为高亮, 将 // highlight-next-line 放置到当前行上方
将某一段代码设为高亮, 使用 // highlight-start 和 // highlight-end 将其包裹
补充一种使用元数据高亮代码方式, 在语言类型后方加入高亮的范围 markdown {1,3-4}
test 第1行
test 第2行
test 第3行
test 第4行
test 第5行
2. 代码块显示行号
若没有效果, 检查一下你的docusaurus版本号是不是V3
默认代码块是不显示行号的，只需要在第一行符号标签上添加 showLineNumbers 即可
test 第1行
test 第2行
3. 插入标题目录
如果想在某个文档中显示内联标题目可以这样干
import TOCInline from '@theme/TOCInline';
<TOCInline toc={toc} minHeadingLevel={2} maxHeadingLevel={4} />
4. 实现交互式代码区
若没有效果, 检查一下你的docusaurus版本号是不是V3
有时我们需要在博客或者文档里展示一些代码的实际运行效果，常见的行为是给个链接跳转到第三方在线代码运行器里，比如“码上掘金”或者“CODEPEN”等， 这样可能觉得不够专注，还可以将实时展示 代码运行结果的功能集成进来。
利用 @docusaurus/theme-live-codeblock 这个官方插件就可以实现，首先安装插件到项目里：
-
组件安装
pnpm add @docusaurus/theme-live-codeblock -
页面配置文件
docusaurus.config.js添加组件docusaurus.config.jsmodule.exports = {
// ...
themes: ['@docusaurus/theme-live-codeblock'],
// ...
}; -
使用的时候，在代码块标签的后面加上
live属性即可，实际效果如下function Clock(props) {
const [startDate, setStartDate] = useState(new Date());
const [date, setDate] = useState(new Date());
useEffect(() => {
const timerID = setInterval(() => tick(), 1000);
return function cleanup() {
clearInterval(timerID);
};
});
function tick() {
setDate(new Date());
}
return (
<div>
<h4>你是在 {startDate.toLocaleTimeString()} 进入本页的</h4>
<h5>你已经在本页待了 {Math.floor((date.getTime() - startDate.getTime()) / 1000)} 秒了</h5>
</div>
);
}
5. 折叠块展示
Details
点击查看更多
我是隐藏内容 
6. 插入代码标题
```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) {
return <h1>你好，{props.name}</h1>;
}
```
function HelloCodeTitle(props) {
return <h1>你好，{props.name}</h1>;
}
7. 支持多语言的代码块(markdown语法)
- 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");
}
}