Docusaurus Problems

Day 1 of using Docusaurus and I'm already pretty disappointed in it. Maybe someone knows how to solve these problems, but online searches and Docusaurus's own documentation has yet to turn up solutions.

Problems

• impossible to disable the dynamic tab title

  Docusaurus produces funky titles (like the title being duplicated) to the point where I've set the title and delimiter to empty strings.

• recommended search behavior requires a backend

  Third party plugins provide offline searching.

• some dark mode CSS var overrides require !important

• impossible to disable or customize many features (like "previous", "next" buttons, archive page title, etc.)

  workaround: hide them with custom styles

• it's strangely slow

  My work's big web app dev server starts in ~300ms. Docusaurus's dev server takes 3.5 seconds to start, even without any blog posts at all.

• customization is hard

  For example, there's no index.html page. I have to insert custom HTML with JavaScript properties in the Docusaurus config file.

• docusaurus start on-change reloads don't actually propagate changes to the website half the time

• it automatically transforms date strings from markdown file names into a URL with slashes between each date part (like 2024-05-27-my-post.md gets turned into /2024/05/27/my-post), but each path part is not a valid page. (Meaning, /2024/05/ does not exist.)

  I worked around this by adding my own post processor that reverts the slashes back into dashes in my Docusaurus config here.

Benefits

• syntax highlighting in code blocks

  export const myVar = 'string value';
• RSS/Atom/JSON feed generated by default

Conclusion

Docusaurus is good enough for now. However, the next time I've got a blank slate (when does that even happen?) I'll roll my own solution.