Skip to main content

I tested Docusaurus V2

· 3 min read
CoffeeCup
CoffeeCup
Senior Technical Writer

Migrating with Confidence: From Hugo to Docusaurus V2​

This summer, I dove back into a client's documentation with a dual mission: explain their new API and migrate the entire site to Docusaurus V2.
From search engines to stylish admonitions and ReDoc integration, this version doesn’t just look good — it works brilliantly. Here’s what we gained, and what to watch out for.

I tested Docusaurus V2

🟢 This summer, I had the pleasure of working for Lineberty again. My mission: document their new API and migrate all the documentation to Docusaurus V2.

Back in 2019, we had opted for a Hugo "Documentation" template, which served its purpose well — Markdown for content, YAML for structure, a three-pane layout, a nice home page, and responsive design. But it had its limitations for evolving Lineberty’s documentation.

So Lineberty chose Docusaurus — specifically, V2 (based on React).

Why not V1, you ask? V1 that I had the opportunity to test during the first half of 2020, when I helped 3DVia migrate its documentation from HTML to Docusaurus?

👉 Quite simply because V2, although still labeled as alpha, is perfectly stable. It’s a very mature release with plenty of attractive new features.

A Great Structure​

  • The search engine is one of Docusaurus’s strengths, along with intuitive navigation and support for i18n (internationalization), announced for V2. Getting started is easy, especially since Docusaurus V2 is so well documented.

  • The sidebar is built from a default file in the package. It relies on page IDs — which play a key role in Docusaurus and help avoid endless paths. So it’s essential to plan the documentation architecture and carefully name those IDs!

  • The home page, menu bar, and CSS are easy to customize — at least if you stay within the default framework. If not, you’ll need to dig into the React files 🙂. Fortunately, the Showcase section proves that nearly anything is possible!

Great Styling Options​

I really appreciated the contribution of Infima to the visual side of V2. Infima variables can be overridden in CSS, giving you access to an infinite color palette. The main CSS can also be extended to override many styles.

The only downside: the default styling of tables — alternating colored bands with no borders — only changes if you dive deep into the code. Best avoided!

I especially liked the support for admonitions via the MDX plugin. Modern color coding, simple syntax — much nicer than the default > note in Markdown.

And of course, the dark mode toggle is a lovely touch.

A ReDoc Plugin​

A great final highlight: V2 supports integration with a ReDoc plugin, allowing direct access to the API documentation from the Docusaurus site.
This creates a single portal for all documentation — user and reference. (Naturally, Lineberty’s documentation is DOCful 😄)

One small note about Markdown in V2: while V1 tolerated HTML tags inside Markdown (like a <br> for a new line), V2 takes a “purist” approach and no longer allows this mix. So yes, you’ll need to think carefully about your content layout — but that’s not on Docusaurus.