跳到主要内容

使用 docusaurus 构建开源电子书

创建电子书

npx create-docusaurus@next kubernetes-guide classic --typescript

安装依赖

npm install --save docusaurus-plugin-sass sass @giscus/react raw-loader path-browserify flexanalytics/plugin-image-zoom @docusaurus/plugin-ideal-image@next @docusaurus/plugin-pwa@next

自定义样式

src/css/custom.css 重命名为 src/css/custom.scss,覆盖为以下内容:

src/css/custom.scss
/**
* Any CSS included here will be global. The classic template
* bundles Infima by default. Infima is a CSS framework designed to
* work well for content-centric websites.
*/

/* You can override the default Infima variables here. */
:root {
--ifm-color-primary: #2e8555;
--ifm-color-primary-dark: #29784c;
--ifm-color-primary-darker: #277148;
--ifm-color-primary-darkest: #205d3b;
--ifm-color-primary-light: #33925d;
--ifm-color-primary-lighter: #359962;
--ifm-color-primary-lightest: #3cad6e;
--ifm-code-font-size: 95%;
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
}

/* For readability concerns, you should choose a lighter palette in dark mode. */
[data-theme='dark'] {
--ifm-color-primary: #25c2a0;
--ifm-color-primary-dark: #21af90;
--ifm-color-primary-darker: #1fa588;
--ifm-color-primary-darkest: #1a8870;
--ifm-color-primary-light: #29d5b0;
--ifm-color-primary-lighter: #32d8b4;
--ifm-color-primary-lightest: #4fddbf;
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
}

/* 代码高亮行的样式 */
.code-block-highlighted-line {
background-color: rgb(72, 77, 91);
span[class*='codeLineNumber'] {
background-color: rgb(72, 77, 91);
}
}
.code-block-add-line {
background-color: #213227;
span[class*='codeLineNumber'] {
background-color: #213227;
}
}
.code-block-update-line {
background-color: #362d1e;
span[class*='codeLineNumber'] {
background-color: #362d1e;
}
}
.code-block-error-line {
background-color: #ff000020;
span[class*='codeLineNumber'] {
background-color: #ff000020;
}
}

清理不需要的文件

因为是电子书,不需要默认的首页,也不需要博客页面,直接用电子书作为首页。很多默认生成的文件是不需要的,可以删除:

rm -rf src/components/HomepageFeatures
rm -rf src/pages/*
rm -rf blog
rm -rf docs
rm -rf static/img/*
rm sidebars.js

创建自定义组件

giscus 评论组件

src/components/Comment.tsx
import React from 'react'
import { useThemeConfig, useColorMode } from '@docusaurus/theme-common'
import BrowserOnly from '@docusaurus/BrowserOnly'
import Giscus, { GiscusProps } from '@giscus/react'
import { useLocation } from '@docusaurus/router';

const defaultConfig: Partial<GiscusProps> = {
id: 'comments',
mapping: 'specific',
reactionsEnabled: '1',
emitMetadata: '0',
inputPosition: 'top',
loading: 'lazy',
strict: '0',
lang: 'zh-CN',
}

export default function Comment(): JSX.Element {
const themeConfig = useThemeConfig()

// merge default config
const giscus = { ...defaultConfig, ...themeConfig.giscus }

if (!giscus.repo || !giscus.repoId || !giscus.categoryId) {
throw new Error(
'You must provide `repo`, `repoId`, and `categoryId` to `themeConfig.giscus`.',
)
}

const path = useLocation().pathname.replace(/^\/|\/$/g, '');
const firstSlashIndex = path.indexOf('/');
var subPath: string = ""
if (firstSlashIndex !== -1) {
subPath = path.substring(firstSlashIndex + 1)
} else {
subPath = "index"
}

giscus.term = subPath
giscus.theme =
useColorMode().colorMode === 'dark' ? 'transparent_dark' : 'light'

return (
<BrowserOnly fallback={<div>评论加载中...</div>}>
{() => <Giscus {...giscus} />}
</BrowserOnly>
)
}

增强代码块 FileBlock

src/components/FileBlock.tsx
import React from 'react';
import CodeBlock from '@theme/CodeBlock';
import { useLocation } from '@docusaurus/router';
import * as path from 'path-browserify';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

let extToLang = new Map([
["sh", "bash"],
["yml", "yaml"]
]);

export default function FileBlock({ file, showFileName, ...prop }: { file: string, showFileName?: boolean }) {
// get url path without "/" prefix and suffix
var urlPath = useLocation().pathname.replace(/^\/|\/$/g, '');

// remove locale prefix in urlPath
const { i18n } = useDocusaurusContext()
if (i18n.currentLocale != i18n.defaultLocale) {
urlPath = urlPath.replace(/^[^\/]*\/?/g, '')
}

// find file content according to topPath and file path param
var filepath = ""
if (file.startsWith("@site/")) {
filepath = file.replace(/^@site\//g, '')
} else {
filepath = "codeblock/" + file
}

// load file raw content according to filepath
var content = require('!!raw-loader!@site/' + filepath)?.default
content = content.replace(/\t/g, " "); // replace tab to 2 spaces

// infer language of code block based on filename extension if language is not set
const filename = path.basename(file);
if (!prop.language) {
var language = path.extname(filename).replace(/^\./, '')
const langMappingName = extToLang.get(language)
if (langMappingName) {
language = langMappingName
}
prop.language = language
}

// set title to filename if showFileName is set and title is not set
if (!prop.title && showFileName) {
prop.title = filename
}

return (
<CodeBlock {...prop}>
{content}
</CodeBlock>
);
}

评论加载中...