This summer, I had the pleasure of working for 🔗 Lineberty again: my mission was to document their new API but also to migrate all the documentation to Docusaurus V2.

In 2019, we opted for a Hugo “Documentation” template which fulfilled its role very well (Markdown files for the content, YAML files for the framework, three-pane structure, nice Home Page, responsive) but which had its limits for future evolution of the Lineberty documentation.

Lineberty therefore chose Docusaurus (based on React) and the V2 in particular.

Why not the V1 you will tell me? V1 that I had the opportunity to test in the 1st semester of 2020 by helping 3DVia to migrate its documentation from HTML to Docusaurus.

➡️ Quite simply because V2, although still in alpha version, is now perfectly stable. This version is very successful and offers a number of very attractive innovations.

🔸 A Great Structure

The search engine is one of the strong points of Docusaurus, as well as the navigation and the management of the i18N languages which is announced for this V2. Getting started is easy, especially since 🔗 Docusaurus V2 is very well documented.

The sidebar is easily built from the default file provided in the package. It uses the IDs of the pages which play a key role in Docusausus and which make it possible to avoid entering endless paths. We must therefore think carefully about the documentation architecture and the names used as IDs!

The Home page, the menu bar and the CSS are easily modifiable, especially if we remain within the default framework. Otherwise, we will have to look deeper in the React files :-) but many examples presented in the Showcase section show us that almost anything is possible!

🔸 Great Styling Options

For my part, I appreciated the Infima contribution for all the visual improvements in this V2. Infima variables can be overwritten in CSS, which offers an infinite color chart. The main CSS can also be supplemented to override a number of styles. The only downside is the visual aspect of the tables (an alternation of colored bands, without borders) which only changes if you risk diving very deep into the files. Better to avoid!

I appreciated even more the support for “admonitions” via the MDX plugin with their very modern color codes and very easy writing. It’s nicer than Markdown’s default > note.

Last but not least, the toggle button to enable the dark mode!

⭐A ReDoc Plugin

An excellent point to finish, the integration of a ReDoc plugin in V2 which allows direct access, in the case of Lineberty, to the API documentation from the Docusaurus site. We then obtain a single portal to the whole documentation, user and reference (of course, the Lineberty documentation is 🔗 DOCful 😃)

Small remark concerning the use of Markdown in V2: where V1 very well tolerated the use of HTML tags in Markdown (a simple ‘break’ for example to force a new line), V2 went to “purist” mode and this mix is no longer possible. It is therefore also necessary to think very well about the content, but this is not the responsibility of Docusaurus!

Please have a look to the result by browsing my 🔗 Portfolio