Zettlr 4.8.0 Released
After almost three months of continuous development, today we are pleased to announce the release of Zettlr version 4.8.0. This release comes with a bag of new features and bug fixes. It also includes a set of changes in behavior from previous releases, so make sure to read through these notes carefully. Some features may no longer work exactly the way you remember, so it is important that you know what to look out for, since these changes are not bugs, but intended.
Overall, this release brings three major features and changes. First, we are happy to announce that Zettlr finally supports admonitions. These “callout” style blocks which can be used to highlight information, tips, or warnings, are already supported by Pandoc, GitHub, and many other Markdown-capable tools.
Second, this release changes the way the full-text search function works. Depending on how you have used the search function until now, this may either make your results more relevant to you, or less.
Third, and lastly, this release heavily improves several of the most important translations so that you receive a more localized experience. This includes the addition of a completely new translation into Azerbaijani. We want to give a shoutout to the community members who have put a lot of effort into making these improvements.
In the following, we introduce these major changes and, after that, a set of minor changes in more detail.
Admonitions
The most exciting new feature are the admonitions. You may know them as “callouts” or “alerts.” These are layout elements that wrap some text into a box, which is often colored according to its type. There are several variants of admonitions which you can use to highlight information in your texts. These are especially useful when you are writing documentation, but even for reading notes or to mark to-do-items visibly in your research they can come in handy.
Admonitions use blockquote syntax, with a custom header line that describes the type of admonition. Zettlr initially supports the five types of admonitions that enjoy support from most of the ecosystem:
note: This is intended for side remarks and other information that should be distinct from the surrounding text, but not call special attention to itself.tip: This is intended for useful information that can make something simpler.info: This admonition type is similar to notes, but it adds color (in Zettlr’s default styles purple) to better separate the information from the surrounding text.warning: As you would expect, this admonition type highlights its contents in yellow to draw attention to it. This admonition type is most often used to call attention to things which the user should pay attention to.caution: This type of admonition can be used to warn readers not just of potential issues, but of severe faults that may occur if the cautionary information is not taken into account. Zettlr has adopted the term “caution” (and not “error” or “danger”), since this is the keyword that is already supported by Pandoc, GitHub, and has been adopted by other tools as well. But semantically, “caution” is equal to errors or dangers.
To add an admonition, you simply use the common blockquote syntax, but specify that it should be an admonition by adding one of these keywords into the header of the blockquote:
> [!NOTE]
> This is informational text that will be pre-rendered by Zettlr with a gray background and the title "Note."
Note that, while Zettlr accepts the keywords both in upper- and lowercase, this may not be the case for other tools. For example, we have just recently enabled Pandoc to accept these keywords in a case-insensitive way. The Pandoc version that ships with this Zettlr version does not yet allow lowercase keywords — you must use an UPPERCASE keyword. Other tools (including GitHub) already support these keywords in lowercase. Take care to consult the manual of whichever tool you use documents with admonitions in them, and use the convention the tool supports.
Another feature that Zettlr supports but which is decisively not supported by either Pandoc or GitHub is custom admonition titles. If you merely include the keyword on the first line of the admonition, Zettlr will pre-render the admonitions using the keyword in Capitalized form (e.g., “Note,” “Important,” or “Tip”), but you can override this by providing a custom title like so:
> [!WARNING] A custom warning title
> This is the content of the warning. It will be pre-rendered by Zettlr using a yellow background and the title "A custom warning title."
Another feature of Zettlr’s admonitions (which is also not supported by all tools in the ecosystem) is that you can nest admonitions. If, for whatever reason, you have to nest a warning inside a note, you can do like so:
> [!NOTE]
> This is the content of the outer note admonition. It will be displayed within Zettlr using a gray background.
> > [!WARNING]
> > This is the content of a warning, nested inside the note admonition.
>
> This text is considered to be part of the outer note, not the warning.
Again, this feature is only sparsely supported, and as such take care to consult the documentation of any tool outside Zettlr that will touch your documents to avoid having layout or display issues when admonitions are not rendered the way you expect them to.
Besides this new syntax that Zettlr now understands, we also added pre-rendering capabilities to the app to properly support syntax highlighting. First, you can control the rendering of admonitions just like other syntactic elements in your preferences. By default, the pre-rendering of admonitions is turned on. The setting also respects your global raw/preview rendering setting that you can toggle from the status bar.
When the pre-rendering of admonitions is enabled, Zettlr will display admonitions inside a box with the corresponding color (gray for notes, green for tips, purple for information, yellow for warnings, and red for cautions). It uses contrasting colors for the background, and the border and font color respectively. When your cursor is inside an admonition or pre-rendering is disabled, Zettlr will only color the syntactic elements in the corresponding color to allow easy identification of the admonition type, but without the actual box. The title (either the keyword or your custom title) is rendered in bold atop the admonition box.
You can customize these colors in two ways using Custom CSS. Either you can target the semantic color variables (--zettlr-<keyword>-<type> where keyword is one of the five semantic admonition keywords, and type is either bg for backgrounds or color for foreground and border colors), or you can directly target the pre-rendered admonitions. The former approach has the side effect that this will change all admonitions across the app (including those in the assets manager), while the latter approach only applies to the editor itself.
Lastly, we have enabled Zettlr’s internal Markdown-to-HTML converter, which is used when you copy text as HTML, to correctly parse admonitions into proper HTML elements. However, since admonitions are not recognized as proper HTML elements, it is fully up to the receiving application into which you paste the text whether it will properly style the elements when you paste. You will always receive the best results when writing in Markdown and exporting it directly using Pandoc, or pasting the raw Markdown source into a tool that supports this admonition syntax.
Another note of caution: If you plan to export a document with admonitions from Zettlr, you will need to forcefully enable the extension alerts in the export profile. This is being done by Zettlr automatically. There is a new settings group in the Import and Export tab in your preferences with which you can ensure that specific extensions required to support Zettlr features are always enabled if available. Read more on that below in the miscellaneous section.
A final note of caution: At the time of writing, Pandoc exports correct containers for all admonition types. However, these are by default unstyled, so they will appear like regular text. For the time being, you will need to add corresponding styles manually to your templates and export profiles. We are working on a solution in a future release.
Sidenote: With the addition of admonitions, we are on the one hand merely implementing a long-standing feature request. On the other hand, however, the significance of this must be properly acknowledged. Up until now, we refrained from adding any syntax that was not commonly implemented. The reason is that we wanted to ensure that, no matter where you work with your documents, they will just work, because Zettlr only supported the “smallest common denominator” of Markdown syntax. The one exception from it were citations, which are, to this date, only fully supported by Zettlr and Pandoc.
The implementation of admonitions is a decisive shift from this position. Admonitions are complex syntactic elements that come in various different forms. Even though the
> [!keyword]-syntax is quite common these days, there are exceptions to this rule. Likewise, we have found that many tools do not support nesting of admonitions, some (including Pandoc) do not support custom titles, some require the keywords to be in uppercase, others in lowercase. Lastly, some tools have decided to implement a bunch of additional keywords that no tool except theirs understands.This means that the addition of admonitions brings Zettlr closer to something that we always eschewed: vendor lock-in. The mere addition of a new syntactic element does not constitute vendor lock-in in the strict sense. However, beginning today, the app is entering a new field, in which it supports syntax elements that have spotty support at best, and where various tools disagree on the precise syntax. We do so because there is a balance to be struck between avoiding making Zettlr a requirement for documents to render properly and enabling efficient writing with various custom elements that may not be supported everywhere.
We see vendor lock-in as a three-step process: (a) zero vendor lock-in — syntax is only supported if it works almost everywhere; (b) soft vendor lock-in — syntax may be unsupported in some significant tools, but it still works in the most critical ones; and (c) full vendor lock-in — syntax won’t work anywhere else. We believe that, until now, we mostly stuck to option (a), but admonitions are comfortably in (b) territory (as are citations). We will try to avoid syntax that Pandoc does not support. This way, you can at least expect that your documents look within Zettlr similar to what they will look like when you export them. Wherever possible and applicable, we will mention deviations in syntax support in the documentation.
In the future, we hope that this more relaxed stance will enable much more productive use of the app and a much better writing experience, with hopefully little downsides, especially if you exclusively work with Markdown within the context of Zettlr.
Change to Full-Text Search Behavior
After this introduction of a much-expected new feature to the app, it is time to announce a second crucial change we have made in this release: the full-text search works differently now. When we first implemented the full-text search many years ago, we decided to implement a very traditional boolean search with AND, OR, and NOT operators. In the documentation, we mentioned that simply separating search terms with spaces would be understood as an “AND” operator, meaning that all search terms must occur in a file for it to be considered a result. However, the actual implementation contained a subtle logical bug: Instead of requiring all search terms to occur in a file, the search feature implicitly turned spaces into “OR” operators, making the search less strict.
This release aligns the documented feature with how it actually works: When you now search for “boat ship” a file will only be present in the search results if it contains both terms. It will no longer be considered a match if it only contains one of the two.
Depending on how you used the search until now, this has the potential to significantly impact your search experience. If you predominantly searched for individual terms, this change will not affect you as much as if you searched for multiple terms but subconsciously relied on the feature treating the search as an “OR” search. To restore the old behavior, you will now have to explicitly add pipe-characters (|) in between your search terms to instruct Zettlr to consider any file a match which contains either of these terms, but not both.
Transparency Disclaimer: I personally was fully aware of this bug for the past years, and simply did not bother to change the documentation, as it worked for me, and nobody has complained. For my personal search behavior, having “OR” by default made much more sense, and so it was easy to simply type a series of search terms and get all files that contain any of these terms. This bug only got fixed because a user pointed out the bug. I fully own the implications that this change has on anyone, and wanted to use this space to declare this. But this goes to show how important accountability and openness are in the development of software we rely on every day.
Significant Translation Updates
The third major change in this version is that we have received many contributions that have updated many translations of the app so that they include most, if not all, translatable strings. Specifically, this update improves the Korean, German, Japanese, Catalan, Brazilian Portuguese, and Turkish translations, and adds an entirely new translation into Azerbaijani.
Until now, we never had a release that improved on so many languages at once, and we are happy that we can now offer a better localized support to more people than ever before, thanks to the large community of the app and the efforts these people make.
If you spot issues in the translation of Zettlr, we are always happy to receive improvements, even if it only concerns a single translation string. To learn more, head over to our contributor’s guide.
Miscellaneous Changes
Aside from these three central things that we wanted to highlight specifically, this update of course also includes a bunch of other great improvements.
Autocomplete Suggestions
Autocomplete suggestions can now be either accepted with the Tab key, or the Enter key. This setting is configurable in the preferences and allows you to choose which key should accept selected autocomplete suggestions. Until now, only the Tab key actually accepted autocomplete suggestions. Several users have pointed this out in the past months, so we decided to make this configurable, now that custom shortcuts have arrived in the app.
Streamlined Pandoc Extension Support
We have started to streamline how Zettlr interacts with Pandoc when you export documents and projects. One side effect of the newly added support for admonitions is that they require a special extension to be active to work during export. By default, none of the available Markdown readers has this support enabled.
Enabling extensions typically involves specifying a reader with the corresponding extension (say, reader: markdown+alerts) in the export profiles, and repeat this for every profile you wish to have this syntax available. This is untenable, and would put a burden on every user for having to maintain all of these extensions.
This is why we have devised an automatic mechanism that will ensure that the syntax you can write inside Zettlr is always supported during your exports, without you having to do anything.
Check the app preferences to see a new settings group in the Import and Export tab that manages Pandoc support conveniently for you. Right now, two extensions can be automatically enabled for each and every export: The mark extension (which is typically enabled, but not for all readers), and the alerts extension which adds admonition support (and which is disabled by default in all readers that support it). Zettlr will check your profile before each and every export to ensure it has the corresponding extension enabled. Furthermore, if a reader does not support some extension (for example, the commonmark reader does not support the mark extension), Zettlr will export your document just fine without throwing an error.
In the future, we will use this mechanism to adjust the export profiles in such a way that the difference between features that Zettlr supports and features that Pandoc supports remains absolutely minimal and what you see inside Zettlr corresponds to what you get when you export.
Sidenote: Did you know that Zettlr already adjusted your export profiles using a simpler version of this mechanism? Depending on which flavor of Wikilinks you used (
[[title|filename]]versus[[filename|title]]), Zettlr would silently enable the corresponding Pandoc extension without you having to do anything to ensure that your Wikilinks get exported appropriately.
Improved Menubar Layout on Windows and Linux
A final thing that we thought you may appreciate is that we have started improving the sometimes rather ugly styling of the app on Windows and Linux. On both Windows and Linux Zettlr shows you a fully custom menu bar. The reason is that having both a titlebar and a menubar wastes precious horizontal screen real estate, especially on landscape format screens. However, we haven’t touched that code in quite some time. After having removed the eyesore that was having the entire bar colored in the system accent color, we now also made the window controls much less obnoxious. Furthermore, we have reduced the size of the Zettlr icon to a more manageable size and heavily improved the design and layout of the window menubar items.
This is just a first step in a long process that we embarked on to improve the visual appeal of the app across all three operating systems. We strive to move away from having separate designs for the three different operating systems, and rather offer one unified design that looks good across all platforms, without giving up the specialties of the individual operating systems.
Deprecation Notice: macOS 12 & Ubuntu 17.04
A final note that may be relevant to some of you: This is the final update to Zettlr that supports macOS 12 and Ubuntu 17.04. Both operating systems are no longer supported by their respective developers, and Electron has dropped support for them in the newest version of the framework. We have refrained from updating the framework to the most recent version in this release to ensure that everyone has a chance to figure out ways to update their computers where necessary. But this is a note that these two operating system will no longer be supported in the next Zettlr release.
That’s it — a very lengthy release note, but Zettlr 4.8.0 is full of new features, and we wanted to give you all the full picture. As always, have fun with the new update, and stay tuned for more!