A New Documentation for Zettlr
One of the most central components of every piece of software is its documentation. Without documentation, new and old users alike would be lost in trying to utilize the software efficiently. Without documentation, users could not trust that the features they wish to use work the way they need them to. And without documentation, a piece of software is almost unusable. At the same time, we rarely realize when a program is properly written. Some software is so simple that it doesn’t require a real documentation. And other software has a documentation written so well that it is almost imperceptible.
Naturally, there are also counter-examples. Documentation written so badly that software becomes famous for it. Or documentation that is clumsy to navigate; that contains all necessary information, but in such a way that it is extremely difficult to navigate. In short, good documentation remains invisible, because it is well-written, easy to navigate, and provides the right information in the right place at the right time to anyone who seeks to make the most of software.
That’s why we’re pleased to announce that today we have given Zettlr’s documentation a new look. For the past decade, its documentation was powered by MkDocs, a Markdown-based, powerful documentation framework. But MkDocs is slowly showing its age. While ten years ago, the Material design language was considered state of the art, in today’s world, its design looks outdated. At the same time, it was very bare-bones. We had to provide many patches and fixes to add functionality that we deemed necessary for our documentation.
After months of research, deliberation, and planning, we have therefore now replaced MkDocs as the driver of Zettlr’s documentation page. Instead, we now use a new and actively maintained framework called VuePress. VuePress essentially uses the same information as MkDocs, but provides a more modern, more legible, and more efficient scaffolding around it. The framework makes use of state-of-the-art web technologies to provide faster page loading speeds, quicker navigation, and a better layout of the documentation so that it is easier to digest. Because the primary goal of every documentation is to stay out of the users’ way and provide just the required information.
Technically, not much has changed. The documentation is still served with static files, and it is still maintained in its original repository. Also, every URL has remained the same, so any bookmarks and links you still have will still work. The repository also still has the same layout, so if you ever contributed to the documentation, you will find everything still at its place.
We do not want this blog post to become too technical, so we invite you to check out the new documentation, which you can from now on find at the known location, https://docs.zettlr.com. In the remainder of this post, we introduce you to some of the improvements that were made possible due to the new documentation framework.
Multilingual by Default
One of the biggest improvements for the new documentation is that internationalization (i18n) is built-in. MkDocs never supported multilingual documentation pages, so we had to “fake” this feature by essentially building a dozen separate MkDocs pages and serve them under one roof. VuePress has allowed us to keep everything in one place.
For you, this means that you can now at any point switch languages simply by perusing the language selector in the main navigation. If a community translation contains a translation of the page you are currently viewing, switching the language will take you to that same page. If a translation does not yet contain a translation of that page, you will be directed to the language’s home page.
In the past, to switch languages, you would have to go to the landing page of the documentation to choose another language. This is now no longer necessary. This has allowed us to make another change: We have now removed all untranslated duplicates of old documentation pages that have over time become heavily outdated. Since it is now much easier to always go back to the official English translation, there is no need anymore to keep these crutches from the past with us. This means that it is now also easier to judge the state of a translation by the size of its sidebar: Only actually translated pages are shown there, giving you a glimpse as to how much has actually been translated.
We hope that this also leads to a push in motivation from our users to improve the existing translations, go through the pages and translate additional content. This way users who are not that fluent in English can read the instructions for how to use Zettlr in the same language they use the app itself in.
Improved Mobile & Accessibility Support
An additional improvement that comes simply by using the new framework is a much better mobile support. The old documentation used a fixed-width layout that was not made for an age in which many of us wish to read some information on our phones, rather than our computers. Even the sidebar which, on the old documentation, slid in from the side, was one of the patches we mentioned earlier that we have made to make this happen. By itself, MkDocs did not show a proper sidebar on mobile devices.
VuePress has made the documentation mobile ready. The page now fluently adjusts to whichever screen you are looking at — large desktop monitors, laptops, tablets, or phones — and rearranges content in the most ideal way to ensure you are able to navigate the documentation efficiently regardless of the device you are using.
This also brought with it additional accessibility and device features that MkDocs was lacking. The new framework now natively supports a dark mode, which means that you can read the documentation both in bright daylight and at night without straining your eyes overly much. The navigability of the documentation for screen readers has also been improved, making it more accessible to every user.
Improved Full-Text Search
One perk of switching to the new framework is a much improved search that is better both in precision and in usability than the old search. While the old search was fully capable, it was always a bit clumsy to navigate — you would have to find and focus the search field, type in your query, and then wait until the search results page has been loaded. Now, the search lives in the menu bar and is more readily accessible on mobile.
On larger devices, the search now also follows the general design principles that have been established in the past years of how you can expect a documentation to work. It now comes with keyboard shortcuts all around, easier overview, and faster navigation to all pages.
New Ways to Visualize Content
Since VuePress comes with more recent Markdown support, we can now visualize and demonstrate content in new ways that weren’t possible with the old framework. For example, VuePress allows us more variation in how we wish to mark admonitions (those little boxes containing additional information, tips, notes, or warnings). Also, it is finally possible to copy code blocks to your clipboard with a button click instead of manually having to select it first. The list of additions to the Markdown dialect we can use also includes math support baked right into the documentation, more syntax examples, and better image rendering.
But the framework goes further. It also defines a few wholly new visualizations for content. For example, in various parts of the documentation, we can now directly demonstrate how Markdown will render using a preview element, which also shows you its source code with the click of a button. In the section where we guide you in conceptualizing your workspaces, we have made use of a folder visualization plugin that shows you an actual folder structure instead of having to rely on nested lists. This makes following the examples and understanding what we mean much simpler.
There are other great features, not all of which we have yet implemented in the documentation. What is important is that the new framework gives us large freedom in shaping the documentation in any way we need.
Extensibility
Lastly, the new framework makes extending it with new components, additional features, and custom designs much more pleasant. Since VuePress is built on Vue, and we in the team have strong experience with this framework because it is the same framework that drives Zettlr’s UI, it is straight-forward for us to fully customize the entire layout, functionality, features, and much more, simply by extending the same Vue components we all know from our work with Zettlr.
This extensibility that is not just present, but slots right into what we already know, is what gives us the confidence that VuePress will be a great choice to use for our documentation in the years to come.
A Call to Action
We want to conclude this blog post with a call to action. Besides migrating the documentation to the new framework, we have also read the entire documentation start to finish in order to improve it, remove outdated information, and clarify complex explanations. At the same time, it became apparent that many community translations were outdated (where we could understand the language partially) or extremely sparse (judging from the amount of pages that were translated).
Therefore, we would like to invite our community to improve the community translations and bring them up to speed. Some of the translations haven’t been touched in years, and they all will benefit from some collective effort to make the documentation not just technically, but also linguistically accessible to a broader range of users.
We hope that you will have a much easier time reading and using the documentation now, and appreciate the work we put into it. And, as always, if you spot errors or problems, we are incredibly grateful for your notice!
Stay sharp!