Skip to main content

Update Docusaurus

2.0.0-beta.6​

from 2.0.0-alpha.72 to 2.0.0-beta.6

When I tried to update my docusaurus 2.0.0-alpha.72 version to version 2.0.0-beta.6, I got the errors.

Invalid sidebar file​

First, I got errors about invalid sidebar file, and after a while I realized that my auto-sidebars plugin was conflicting with new docusaurus feature: docusaurus.io: Sidebar Item Autogenerated.

I uninstalled the auto-sidebars plugin and the development server started working again.

Then I suddenly got some broken links. I found out that:

By default, Docusaurus will remove the number prefix from the doc id, title, label and URL paths. docusaurus.io: Using Number Prefixes

Numeric prefixes in Folders​

As I understand it, any numeric prefix in folder names (for example: 5-styling-react-components-and-elements) will be truncated (styling-react-components-and-elements).

I removed the numeric prefix from the folder names.

But that didn't solve the problem of broken links.

The problem of broken links was solved by editing links. If your folder name looks like 5-styling-react-components-and-elements, then the link to that folder should look truncated, without a number: styling-react-components-and-elements.

some page
[broken link](../5-styling-react-components-and-elements/5-10-0-working-with-css-modules)

[working link](../styling-react-components-and-elements/5-10-0-working-with-css-modules)

Numeric Prefixes in Files​

Meanwhile, numeric prefixes in files work.

Initial Errors​

Loading of version failed for version "current"
Error: Invalid sidebar file at "sidebars.auto.js".
These sidebar document ids do not exist:
- courses/react-complete-guide/10-burger-builder-project-accessing-server/10-0-lesson
- courses/react-complete-guide/10-burger-builder-project-accessing-server/10-10-useful-resources-and-links
- courses/react-complete-guide/10-burger-builder-project-accessing-server/10-2-firebase-and-right-database
...

Available document ids are:
- api/love-project/love-project
- api/python3/python
- api/python3/venv-isolate-dependencies
...
    at Object.checkSidebarsDocIds (/mnt/sdc2/Yandex.Disk-parsh/hm/node_modules/@docusaurus/plugin-content-docs/lib/sidebars.js:339:19)
    at doLoadVersion (/mnt/sdc2/Yandex.Disk-parsh/hm/node_modules/@docusaurus/plugin-content-docs/lib/index.js:117:31)
    at async loadVersion (/mnt/sdc2/Yandex.Disk-parsh/hm/node_modules/@docusaurus/plugin-content-docs/lib/index.js:166:28)
    at async Promise.all (index 0)
    at async Object.loadContent (/mnt/sdc2/Yandex.Disk-parsh/hm/node_modules/@docusaurus/plugin-content-docs/lib/index.js:174:33)
    at async /mnt/sdc2/Yandex.Disk-parsh/hm/node_modules/@docusaurus/core/lib/server/plugins/index.js:58:46
    at async Promise.all (index 0)
    at async Object.loadPlugins (/mnt/sdc2/Yandex.Disk-parsh/hm/node_modules/@docusaurus/core/lib/server/plugins/index.js:57:27)
    at async Object.load (/mnt/sdc2/Yandex.Disk-parsh/hm/node_modules/@docusaurus/core/lib/server/index.js:186:82)

These sidebar document ids do not exist:
...
- courses/react-complete-guide/9-reaching-out-web-http-ajax/9-9-posting-data-to-server
Available document ids are:
...
- courses/react-complete-guide/reaching-out-web-http-ajax/9-9-posting-data-to-server

2.0.0-beta.20​

tip

Before deleting node_modules and package-lock.json and run npm i, I copy/pasted the new lines from the default package.json to mine (I had to install the default docusaurus app with command: npx create-docusaurus@latest test-docusaurus-2.0.0-beta.20 classic)

from 2.0.0-beta.15 to 2.0.0-beta.20

Manual structuring of the sidebar​

Replace automatic compilation of sidebarsCourses.js with manual compilation.

It was:

sidebarsCourses.js
module.exports = {
  Docs: [
    {
      type: 'autogenerated',
      dirName: '.', // '.' means the current docs folder
    },
  ],
};

It became:

sidebarsCourses.js
sidebarsCourses.js
module.exports = {
Courses: [
  {
    type: 'category',
    label: 'Courses',
    link: {
      type: 'doc',
      id: 'all-courses',
    },
    collapsible: true,
    collapsed: true,
    items: [
      {
        type: 'category',
        label: 'Cloud Service Engineer',
        link: {
          type: 'doc',
          id: 'cloud-service-engineer/README',
        },
        collapsible: true,
        collapsed: true,
        items: [
          {
            type: 'category',
            label: 'Virtual Machines',
            link: {
              type: 'generated-index',
              slug: '/cloud-service-engineer/virtual-machines',
            },
            items: [
              {
                type: 'category',
                label: 'Intro',
                link: {
                  type: 'generated-index',
                  slug: '/cloud-service-engineer/virtual-machines/intro',
                },
                items: [
                  {
                    type: 'autogenerated',
                    dirName: 'cloud-service-engineer/virtual-machines/intro',
                  },
                ],
              },
            ],
          },
          {
            type: 'category',
            label: 'Data Storage and Analysis',
            link: {
              type: 'generated-index',
              slug: '/cloud-service-engineer/data-storage-and-analysis',
            },
            items: [
              {
                type: 'category',
                label: 'Controlled Databases',
                link: {
                  type: 'generated-index',
                  slug: '/cloud-service-engineer/data-storage-and-analysis/controlled-databases',
                },
                items: [
                  {
                    type: 'autogenerated',
                    dirName:
                      'cloud-service-engineer/data-storage-and-analysis/controlled-databases',
                  },
                ],
              },
            ],
          },
        ],
      },
      {
        type: 'category',
        label: 'React Complete Guide',
        link: {
          type: 'generated-index',
          slug: '/react-complete-guide',
        },
        collapsible: true,
        collapsed: true,
        items: [
          {
            type: 'autogenerated',
            dirName: 'react-complete-guide',
          },
        ],
      },
    ],
  },
],
};

And this is just the beggining!

This file will grow!

Other touched file see in commit

Add React page: Showcase​

  • add new node dependencies:

    package.json
    ...
    "react-dom": "^17.0.2",
    "react-popper": "^2.3.0",
    "@popperjs/core": "^2.11.5"
    },

  • add new components of react page:

    see commit

Add GitHub Deploy env​

const isDeployPreview = !!process.env.GITHUB_ACTIONS;

Add and then Remove trailingSlash​

Everything was fine, but when I pushed, I got a warning:

GitHub Deploy Error

Warning: When deploying to GitHub Pages, it is better to use an explicit "trailingSlash" site config.

And I tried to solve this problem!

I tried two configuration options, but both didn't work:

docusaurus.config.js
// This cause a build error:
trailingSlash: !isDeployPreview,  // = false

// and this cause a build error:
trailingSlash: isDeployPreview,  //  = true

And I remove trailingSlash altogether!!!

Because without the trailingSlash everything works fine!

tip

You can view the values of variables in debug mode (plugin-debug) at http://localhost:3000/hm/__docusaurus/debug:

http://localhost:3000/hm/__docusaurus/debug

Site config


{ 23 items
...
  "baseUrl" : "/hm/"
  "url" : "https://papa31.github.io"
  "onBrokenLinks" : "throw"
  "onBrokenMarkdownLinks" : "warn"
  "favicon" : "img/favicon.ico"
  "customFields" : { 2 items
  "isDeployPreview" : false
  "description" : "papa31 pandora box"
...

2.1.0​

2.0.0-beta.20 → 2.1.0

Docusaurus advice​

I followed Docusaurus suggestion in npm cli:

npm i @docusaurus/core@latest @docusaurus/plugin-ideal-image@latest @docusaurus/plugin-pwa@latest @docusaurus/preset-classic@latest @docusaurus/remark-plugin-npm2yarn@latest @docusaurus/theme-classic@latest @docusaurus/theme-common@latest @docusaurus/theme-live-codeblock@latest @docusaurus/eslint-plugin@latest @docusaurus/module-type-aliases@latest
danger

But I got an error:

npm WARN tar ENOENT: no such file or directory, open '/media/storage418Gb/Yandex.Disk-parsh/hm/node_modules/.staging/core-js-78823b9d/modules/web.url-search-params.js'
npm WARN tar ENOENT: no such file or directory, open '/media/storage418Gb/Yandex.Disk-parsh/hm/node_modules/.staging/core-js-78823b9d/modules/web.url.constructor.js'

perhaps because of very large number of inode. But df -i shows a legitimate amount! 😵

And the workaround in my case is to remove node_modules.

Manual editing​

I manually edited package.json as mentioned in the Docusaurus docs and then:

rm -fr node_modules/ package-lock.json

npm i

Node version error​

But a little error:

$ npx docusaurus --version
[ERROR] Minimum Node.js version not met :(
[INFO] You are using Node.js v14.17.0, Requirement: Node.js >=16.14.

I run:

$ nvm ls

       v10.24.1
      v12.22.12
       v14.16.0
->     v14.17.0
       v14.17.5
       v16.15.0
        v18.2.0
default -> node (-> v18.2.0)
iojs -> N/A (default)
unstable -> N/A (default)
node -> stable (-> v18.2.0) (default)
stable -> 18.2 (-> v18.2.0) (default)
lts/* -> lts/gallium (-> N/A)
lts/argon -> v4.9.1 (-> N/A)
lts/boron -> v6.17.1 (-> N/A)
lts/carbon -> v8.17.0 (-> N/A)
lts/dubnium -> v10.24.1
lts/erbium -> v12.22.12
lts/fermium -> v14.20.0 (-> N/A)
lts/gallium -> v16.17.0 (-> N/A)

and

vim .nvmrc

# and changed the value to 16.15.0
# because this version already
# installed in my system (see nvm ls output above)

Production Node version​

And don't forget about production! Change node-version from 14.x to 16.14.x in config file. In my case:

.github/workflows/documentation.yml
...
      node-version: '16.14.x'
...
      node-version: '16.14.x'
...