前言
docusaurus是一款使用markdown編寫手冊文檔的工具，同類競品有vuepress
目前來看，比后者多了10k個start
docusaurus是基於react，而vuepress是基於vue的
官方文檔點擊此處
使用
創建項目
腳手架創建項目，比如我想創建一個名為linux-book的項目
npx create-docusaurus@latest linux-book classic
設置默認語言
然后集成i18n，不然上一頁下一頁 以及基本的語言默認都是英語。
docusaurus幫我們翻譯了一些基礎的單詞，我們去下載語言即可。
下載完成后復制到項目根目錄中 linux-book/i18n/zh-Hans
修改配置文件
docusaurus.config.js
配置i18n、配置頂部導航、底部、控制生成菜單名字和順序等等基本信息
// @ts-check
const lightCodeTheme = require("prism-react-renderer/themes/github");
const darkCodeTheme = require("prism-react-renderer/themes/dracula");
/** @type {import('@docusaurus/types').Config} */
const config = {
title: "linux手冊",
tagline: "學它，你就可以干掉運維",
url: "https://your-docusaurus-test-site.com",
baseUrl: "/",
onBrokenLinks: "throw",
onBrokenMarkdownLinks: "warn",
favicon: "img/favicon.ico",
organizationName: "facebook", // Usually your GitHub org/user name.
projectName: "linux-book", // Usually your repo name.
i18n: {
// 國際化配置
defaultLocale: "zh",
locales: ["zh"],
},
presets: [
// 預設
[
"classic",
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
sidebarPath: require.resolve("./sidebars.js"),
},
theme: {
customCss: require.resolve("./src/css/custom.css"),
},
}),
],
],
themeConfig: // 頂部導航和底部導航基礎配置
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
navbar: {
title: "linux手冊",
logo: {
alt: "My Site Logo",
src: "img/logo.png",
},
items: [
{
type: "doc",
docId: "第1章_什么是linux",
position: "left",
label: "文檔",
},
{
href: "https://www.cnblogs.com/dingshaohua",
label: "博客",
position: "right",
},
],
},
prism: {
theme: lightCodeTheme,
darkTheme: darkCodeTheme,
defaultLanguage: "javascript",
},
}),
};
module.exports = config;
然后完事。
隱藏md內的標題
其實這個一級標題沒啥用，因為左側菜單不久知道當前講的是啥了嗎
而且如果你不手動設置標題，默認標題去除的是對應md的id，可能不太好看。
所以參考官方文檔隱藏標題掉即可，暫時還沒找到全局配置隱藏。
---
hide_title: true
預覽效果
關於部署
我這邊是部署到gitPage上的，所以需要將docusaurus.config.js中的baseUrl改為如下即可
baseUrl: "/linux-book/build/"
關於側邊欄---折疊
1、側邊欄從2.0開始 支持折疊菜單了。直接建菜單就可以體驗效果。
2、默認情況下，折疊菜單中，文件夾就是一級標題，點擊標題展開的二級標題，實際上就是目錄里的md文件。
3、如果點擊折疊菜單的一級標題，不想展開，而是擁有自己的頁面，則需要在此目錄內新建立一個文件_category_.json，代碼如下即可
{
"label": "第2章_規范",
"link": {
"type": "generated-index",
"description": "這一章講的就是規范"
}
}
還要記得把docusaurus.config.js設置onBrokenLinks: "ignore"，否則編譯不通過
4、顯然，第3條，僅靠description可能滿足不了需求，能不能指定一個markdown文件呢，當然可以
_category_.json修改如下
{
"label": "第2章_規范",
"link": {
"type": "doc",
"id": "第2章_規范/index"
}
}
然后在此目錄下創建一個index.md
---
slug: 第2章_規范
---
## 說明
為了保證開發風格和質量，實現較好的可讀性和可維護性。
關於側邊欄---標題
左邊側邊欄的欄目和頁面內的一級標題，都取的是md文件內定義的title
xxx.md
---
title: 第3章 腳手架
---
如果沒有title屬性 則默認取之當前文件的id（如果不在文件內聲明id，則默認取文件名作為id）
關於側邊欄---排序
多個庫（實例）
修改配置文件里的兩個字段即可
presets.docs里放第一個庫實例，新增plugins字段放第二個庫實例，具體如下
// @ts-check
const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');
/** @type {import('@docusaurus/types').Config} */
const config = {
title: '丁少華的個人網站',
tagline: '這個網站很酷啊，趕緊收藏吧！',
url: 'https://your-docusaurus-test-site.com',
baseUrl: '/',
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
favicon: 'img/favicon.ico',
organizationName: 'facebook', // Usually your GitHub org/user name.
projectName: 'docusaurus', // Usually your repo name.
i18n: {
defaultLocale: 'zh',
locales: ['zh'],
},
presets: [
[
'classic',
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
sidebarPath: require.resolve('./sidebars.js'),
path: 'docs/redux',
routeBasePath: 'redux',
},
theme: {
customCss: require.resolve('./src/css/custom.css'),
},
}),
],
],
plugins: [
[
'@docusaurus/plugin-content-docs',
{
id: 'life',
path: 'docs/life',
routeBasePath: 'life',
sidebarPath: require.resolve('./sidebars.js')
},
],
],
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
navbar: {
title: '丁少華的個人網站',
logo: {
alt: 'My Site Logo',
src: 'img/logo.svg',
},
items: [
{
type: 'doc',
docId: '1、前言',
label: 'redux',
},
{
docsPluginId:'life',
type: 'doc',
docId: '認識我',
label: '碎碎念',
}
],
},
prism: {
theme: lightCodeTheme,
darkTheme: darkCodeTheme,
},
}),
};
module.exports = config;
