How We Replaced Gitbook with Docusaurus for Scalable Documentation

Background

Help documentation is a key means of delivering product value. High‑quality, efficiently published docs greatly improve the efficiency of value transmission and reduce delivery costs.

GrowingIO originally used Gitbook for SaaS help docs, but client access restrictions forced us to scrape Gitbook pages and serve them from our own web server. Maintaining private‑deployment docs with Gitbook proved costly and hard to automate, so we decided to rebuild using Docusaurus.

Problems to Solve

Multi‑version support : SaaS docs need only the latest version, but private deployments require docs for each product version. Gitbook’s variant feature was discontinued, making native multi‑version support a critical selection criterion.

Change review : Gitbook’s changelog UI was cumbersome; Docusaurus relies on Git for review, requiring editors to learn markdown and Git.

Offline export : Some customers need offline docs. Gitbook lacked export, so we previously converted markdown to PDF manually.

Practice Content

Installation

npm init docusaurus@latest op-help-docs classic

This command creates a Docusaurus project named op-help-docs using the classic template.

Basic Configuration

Most settings are placed in docusaurus.config.js.

Page Style

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        theme: {
          customCss: [require.resolve('./src/css/custom.css')],
        },
      },
    ],
  ],
};

:root {
  --ifm-color-primary: #FC5F3A;
  --ifm-color-primary-dark: #fc461b;
  --ifm-color-primary-darker: #fb3a0c;
  --ifm-color-primary-darkest: #d62b03;
  --ifm-color-primary-light: #fc7859;
  --ifm-color-primary-lighter: #fd8468;
  --ifm-color-primary-lightest: #fda996;
  --ifm-code-font-size: 90%;
}

Home Page

The home page consists of a header with a button and a feature list. The header code resides in src/pages/index.js:

function HomepageHeader() {
  const {siteConfig} = useDocusaurusContext();
  return (
    <header className={clsx('hero hero--primary', styles.heroBanner)}>
      <div className="container">
        <h1 className="hero__title">{siteConfig.title}</h1>
        <p className="hero__subtitle">{siteConfig.tagline}</p>
        <div className={styles.buttons}>
          <Link className="button button--secondary button--lg" to="/docs/2.3/product-intro">
            开启增长平台产品探索之旅
          </Link>
        </div>
      </div>
    </header>
  );
}

Site title and tagline are defined in docusaurus.config.js:

const config = {
  title: "一站式数据增长引擎",
  tagline: "数据+智能+营销，赋能商业决策，实现业绩增长",
  // ...
};

Navigation

Navigation bar configuration is also in docusaurus.config.js:

themeConfig: {
  navbar: {
    title: "",
    logo: { alt: "GrowingIO Logo", src: "img/logo.svg" },
    items: [
      { href: "https://growingio.github.io/growingio-sdk-docs/docs", label: "采集 SDK 帮助文档", position: "left" },
      { type: "docsVersionDropdown", position: "right" },
      { href: "https://www.growingio.com/", label: "官网", position: "right" },
      { href: "https://github.com/growingio/growingio-cdp-docs", label: "GitHub", position: "right" },
    ],
  },
  // ...
}

Sidebar

We use Docusaurus’ autogenerated sidebar based on the docs folder structure:

const sidebars = {
  tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }],
};
module.exports = sidebars;

Search

Docusaurus supports Algolia search natively; we also use the local search plugin @cmfcmf/docusaurus-search-local:

plugins: [
  [require.resolve("@cmfcmf/docusaurus-search-local"), {
    indexDocs: true,
    indexDocSidebarParentCategories: 1,
    indexBlog: false,
    indexPages: true,
    language: ["zh", "en"],
    lunr: { tokenizerSeparator: /[\s\-]+/, b: 0.75, k1: 1.2, titleBoost: 0, contentBoost: 1, parentCategoriesBoost: 2 },
  }],
];

Image Zoom

Large images are zoomable via the plugin-image-zoom plugin:

plugins: ["plugin-image-zoom"];

Jira Feedback Integration

We embed Jira Issue Collectors using docusaurus-plugin-includes to collect user feedback directly from the docs:

plugins: [
  ["docusaurus-plugin-includes", {
    injectedHtmlTags: {
      preBodyTags: [{
        tagName: "script",
        attributes: {
          type: "text/javascript",
          src: "https://growingio.atlassian.net/.../issuecollector.js?collectorId=xxxxxxxx",
        },
      }],
    },
  }],
  "plugin-image-zoom",
];

Multi‑Version Support

Docusaurus can generate versioned docs with a single command: npm run docusaurus docs:version 2.1-beta Version information is stored in versions.json and the actual files are managed via Git submodules.

Build and Deploy

npm run build   // generate static site in the build folder
npm run serve   // preview locally

The built site can be uploaded to any web server for production use.

PDF Export

We use the mr-pdf plugin to export a whole version of the docs as a PDF:

npx mr-pdf --initialDocURLs="https://docs.growingio.com/op-help/docs/2.0/product-intro" \
  --contentSelector="article" \
  --paginationSelector=".pagination-nav__item--next > a" \
  --excludeSelectors=".margin-vert--xl a" \
  --excludeSelectors=".tocMobile_3Hoh > button" \
  --coverTitle="增长平台产品帮助文档" \
  --disableTOC \
  --pdfMargin="50,50,50,50" \
  --outputPDFFilename="op-help-docs_v2.0.pdf"

Summary

Our Docusaurus practice has largely solved the pain points encountered with Gitbook. Although it lacks a native visual editor and changelog review UI—raising the entry barrier for documentation maintainers—the platform’s openness standardizes, controls, and streamlines the publishing, management, and maintenance of help docs, thereby improving overall efficiency.