跳到主要内容

创建电子书

初始化​

npx create-docusaurus@latest website classic --typescript

添加文档​

在 docs 目录下新建文档：

website # website root directory
├── docs
│   │── intro.md
│   │── hello.md
│   └── tutorial-basics
│       └──create-a-document.md
├── ...

配置侧边栏​

电子书的侧边栏（目录）是通过配置文件 sidebars.js 配置的，默认文件路径是项目根目录下的 ./sidebar.js：

docusaurus.config.js
export default {
  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.js',
        },
      },
    ],
  ],
};

如果希望侧边栏目录根据 docs 目录下的文件自动生成，可以使用类似如下的配置：

sidebars.js
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
};

export default sidebars;

如果希望自定义侧边栏目录，可以使用类似如下的配置：

import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
  tutorialSidebar: [
    'intro', // 第一个是首页
    'hello',
    { // 目录
      type: 'category',
      label: 'Tutorial',
      items: [
        'tutorial-basics/create-a-document'
      ],
    },
  ],
};

export default sidebars;

国际化​

当电子书需要支持多语言时，先配置下 i18n，并加上切换语言的下拉框：

export default {
  i18n: {
    defaultLocale: 'zh',
    locales: ['zh', 'en'],
    localeConfigs: {
      zh: {
        label: '中文',
        htmlLang: 'zh-CN',
      },
      en: {
        label: 'English',
        htmlLang: 'en-US',
      },
    }
  },
  themeConfig: {
    navbar: {
      items: [
        // ...
        {
          type: 'localeDropdown', // 语言选择下拉框
          position: 'right', // 放在右上方
        },
        // ...
      ],
    },
  },
  // ...
};

然后初始化 i18n 目录：

npm run write-translations -- --locale en

将未翻译的 markdown 文件复制到目标语言目录下：

mkdir -p i18n/en/docusaurus-plugin-content-docs/current
cp -r docs/** i18n/en/docusaurus-plugin-content-docs/current

然后将内容原地翻译成目标语言（可利用 AI 进行翻译），翻译完成后最终构建出来的电子书就支持国际化了，可点击语言选择下拉框来切换语言。

预览不支持多语言切换，需显式指定 locale：

npm run start -- --locale en

参考资料​