Skip to main content

Docusaurus

Styling​

Algolia​

Install the Algolia npm package:

npm install --save @docusaurus/theme-search-algolia

Do not change the preset theme:

docusaurus.config.js
// ...
  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */

      // ...
    ],
  ],
// ...

Add an algolia field in the themeConfig:

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      // The application ID provided by Algolia
      appId: 'YOUR_APP_ID',

      // Public API key: it is safe to commit it
      apiKey: 'YOUR_SEARCH_API_KEY',

      indexName: 'YOUR_INDEX_NAME',
    },
  },
};

Run npm run build to check if everything is working.

  • replace all spaces in the file path with dashes %20, eg. if the filename is Some Filename with Spaces.mdx you can link to it via
[title](./path/to/Some%20Filename%20with%20Spaces.mdx#section)

see section Jumping to Sections when Clicking on Links Takes Long

Troubleshooting​

Error: EMFILE: too many open files, watch '/absolute/path/to/docusaurus.config.js'​

Problem: Error when running npm start:

[ERROR] Error: EMFILE: too many open files, watch '/home/bra-ket/git/homepage/pharath.cpp/docusaurus.config.js'
    at FSWatcher.<computed> (node:internal/fs/watchers:247:19)
    at Object.watch (node:fs:2469:36)
    at createFsWatchInstance (/home/bra-ket/git/homepage/pharath.cpp/node_modules/chokidar/lib/nodefs-handler.js:119:15)
    at setFsWatchListener (/home/bra-ket/git/homepage/pharath.cpp/node_modules/chokidar/lib/nodefs-handler.js:166:15)
    at NodeFsHandler._watchWithNodeFs (/home/bra-ket/git/homepage/pharath.cpp/node_modules/chokidar/lib/nodefs-handler.js:331:14)
    at NodeFsHandler._handleFile (/home/bra-ket/git/homepage/pharath.cpp/node_modules/chokidar/lib/nodefs-handler.js:395:23)
    at NodeFsHandler._addToNodeFs (/home/bra-ket/git/homepage/pharath.cpp/node_modules/chokidar/lib/nodefs-handler.js:637:21)
    at async /home/bra-ket/git/homepage/pharath.cpp/node_modules/chokidar/index.js:451:21
    at async Promise.all (index 0) {
  errno: -24,
  syscall: 'watch',
  code: 'EMFILE',
  path: '/home/bra-ket/git/homepage/pharath.cpp/docusaurus.config.js',
  filename: '/home/bra-ket/git/homepage/pharath.cpp/docusaurus.config.js'
}

Solution: Run npm run clear and killall node. Then, try npm start again.

  • clear the swap using sudo swapoff -a (wait until the swap is cleared), followed by sudo swapon -a
  • run npm start again, free up some memory

CSS Pecularities​

& Nesting Selector​

Related Error:

The following error is shown when running npm run build:

[WARNING] {"file":"assets/css/styles.90f5ac16.css","message":"assets/css/styles.90f5ac16.css from Css Minimizer plugin\nInvalid property name '&.primary{background-color' at assets/css/styles.90f5ac16.css:25:27365. Ignoring.","compilerPath":"client"}

This error is thrown by the css-minimizer-webpack-plugin.

Reason:

The & Nesting selector might not work in older browser versions

Baseline 2023 Newly available Since December 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

source: mdn

Solution:

Use the equivalent non-nested syntax without the & nesting selector, ie.

.parent-rule {
  /* parent rule properties */
  &.child-rule {
    /* child rule properties */
  }
}

/* the browser parses the above nested rules as shown below */
.parent-rule {
  /* parent rule properties */
}

.parent-rule.child-rule {
  /* child rule properties */
}