简单记录一下如何安装和使用 Docusaurus 来构建自己的博客和文档站点。
Docusaurus 的官方文档 https://docusaurus.io/zh-CN/docs
生成新站点
使用 classic
模板生成一个新的 Docusaurus 站点 my-website
。
运行命令后,经典模板将自动添加到您的项目中
npm init docusaurus@latest my-website classic
yarn create docusaurus@latest my-website classic
pnpm create docusaurus@latest my-website classic
进入生成的站点目录
cd my-website
启动并运行开发服务器:
npm run start
yarn run start
pnpm run start
打开页面 docs/intro.md
并编辑一些行,可以看到该站点会自动重新加载并显示最新的更改。
配置站点
基础配置
const config = {
title: "Inhere's Site",
tagline: "Inhere's site, blogs and project docs",
url: 'https://inhere.github.io',
baseUrl: '/',
trailingSlash: false,
organizationName: 'inhere', // Usually your GitHub org/user name.
projectName: 'inhere.github.io', // Usually your repo name.
deploymentBranch: 'gh-pages',
// ...
}
文档和博客配置:
presets: [
[
'classic',
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
sidebarPath: require.resolve('./sidebars.js'),
// Please change this to your repo.
// Remove this to remove the "edit this page" links.
editUrl: 'https://github.com/inhere/inhere.github.io/tree/main/',
},
blog: {
showReadingTime: true,
postsPerPage: 6,
// routeBasePath: '/', // 把博客放在站点根部
blogSidebarCount: 6, // 默认 5
// Remove this to remove the "edit this page" links.
editUrl: 'https://github.com/inhere/inhere.github.io/tree/main/',
},
}),
],
],
配置多语言
i18n: {
defaultLocale: 'zh-CN',
locales: [ "zh-CN", 'en'],
localeConfigs: {
en: {
htmlLang: 'en-GB',
},
},
},
这里我是以 zh-CN
为主,生成 en
翻译文档
npm run write-translations -- --locale en
GitHab Pages
参考官方文档添加 GitHab Actions 如下的配置文件,这样在每次推送到仓库时就会触发自动构建,
并且会自动部署构建的静态文件到 gh-pages
分支。
.github/workflows/deploy.yml
.github/workflows/test-deploy.yml
添加常用插件
npm2yarn
可以同时显示 npm 和 Yarn 的 CLI 命令。
然后要使用它,只需在代码块中添加 npm2yarn
键:
npm install @docusaurus/remark-plugin-npm2yarn
yarn add @docusaurus/remark-plugin-npm2yarn
pnpm add @docusaurus/remark-plugin-npm2yarn
配置插件:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
remarkPlugins: [
[require('@docusaurus/remark-plugin-npm2yarn'), {sync: true}],
],
},
pages: {
remarkPlugins: [require('@docusaurus/remark-plugin-npm2yarn')],
},
blog: {
// ...
},
},
],
],
};
docusaurus-search-local
用于 Docusaurus v2 的支持离线本地搜索的插件
安装插件:
npm install --save @easyops-cn/docusaurus-search-local
yarn add @easyops-cn/docusaurus-search-local
pnpm add @easyops-cn/docusaurus-search-local
配置插件:
module.exports = {
// ... Your other configurations.
themes: [
// ... Your other themes.
[
require.resolve("@easyops-cn/docusaurus-search-local"),
{
// ... Your options.
// `hashed` is recommended as long-term-cache of index file is possible.
hashed: true,
// For Docs using Chinese, The is recommended to set to:
language: ["en", "zh"],
},
],
],
};
类似插件:
- https://github.com/praveenn77/docusaurus-lunr-search
- https://github.com/cmfcmf/docusaurus-search-local
openapi-docs
GitHub https://github.com/PaloAltoNetworks/docusaurus-openapi-docs
Installation
Plugin:
yarn add docusaurus-plugin-openapi-docs
Theme:
yarn add docusaurus-theme-openapi-docs
一些使用说明
一些有用的使用说明
强调提示
:::note
一些包含 _Markdown_ `语法` 的 **内容**。
:::
:::tip
一些包含 _Markdown_ `语法` 的 **内容**。
:::
:::info
一些包含 _Markdown_ `语法` 的 **内容**。
:::
:::caution
一些包含 _Markdown_ `语法` 的 **内容**。
:::
:::danger
一些包含 _Markdown_ `语法` 的 **内容**。
:::
效果如下:
一些包含 Markdown 语法
的 内容。
一些包含 Markdown 语法
的 内容。
代码行高亮
你可以用 highlight-next-line
、highlight-start
、highlight-end
等注释来选择要高亮的行。
效果如下:
function HighlightSomeText(highlight) {
if (highlight) {
return '这行被高亮了!';
}
return '这里不会';
}
function HighlightMoreText(highlight) {
if (highlight) {
return '这块被高亮了!';
}
return '这里不会';
}
原文档 https://docusaurus.io/zh-CN/docs/markdown-features/code-blocks#line-highlighting