Zettlr 4.0 Released
Today is a very special day. Zettlr turns eight years old today. And, at the same time, we are thrilled to announce the release of the next major version of Zettlr! After exactly eight years, today we unveil version 4 of the most comprehensive publication workbench.
This time, the list of changes is truly amazing, and longer than what we have offered in any version thus far. Before upgrading, you should definitely check out the full changelog for this release. In this post, we will guide you through the most important improvements and changes so that you can get a quick glance at everything that has changed!
As always, you can get the new release in our Downloads-section, on GitHub, or via your preferred package manager. Please note that some package managers may fetch the new update with a bit of delay.
At a Glance
Let us get started by quickly introducing the most crucial changes to get you started. The most notable improvement is a fully rewritten table editor. While previously, users were plagued by data loss issues and other weird behavior, this time we have fixed all of these issues and improved upon the table editor.
Second, Zettlr now comes with an image and PDF file viewer. This allows you to preview images and PDF files right within Zettlr. You can turn this on in the settings, and be able to stay in the app for viewing images or PDF files.
Third, we have heavily improved the citation parser. Now it gives you a better visual indication of how the citations will be parsed before you finish the citation. This makes it easier than ever to write the correct syntax and properly cite what you reference. It also now includes support for pandoc-crossref!
Fourth – and this is especially great for new users – Zettlr now ships with a brand-new onboarding screen. When you start the app for the very first time, it now prompts you to adjust some central settings, saving you time to search for these options in the preferences.
Besides these major improvements, we have also reworked the Link insertion and footnote insertion workflows. They now allow you to insert new links and footnotes easier and with fewer clicks or key presses. Also, we have rewritten Zettlr’s FSAL, which means that it will now properly detect changes on your computer, mitigating a lot of issues users had before. Oh, and we have exposed the Lua filter interface to you, which means that you can now customize your exports even further. This allows a much better customization experience and hopefully starts a community movement to share filters among each other.
Last but not least: We have used the occasion as an excuse to completely overhaul the documentation. Many parts of the official user manual were quite outdated, and we took the chance to completely re-do the documentation so that features are better described and easier to find. So regardless of whether you’re a new user or a seasoned community member, you may find something new in the documentation! We really hope that this update makes it easier for everyone to get started with Zettlr. Also, we hope that the community will now begin to move these changes into the community translations!
TableEditor Rewrite
First, the primary reason for which we are excited to release this new update. We have been working for about 18 months to make a new, rewritten table editor a reality.
For some background: Many years ago, we have included a visual editor to edit Markdown tables in the app, since manually editing Markdown table syntax can be quite cumbersome. However, since tables are complex structures, this first table editor was always plagued by bugs. Most crucially, many users had experienced data loss issues where their changes to a table’s contents were not properly saved. While initially we were determined to fix the existing implementation, it quickly became clear that the entire mechanism was brittle and essentially unfixable.
In early 2024, we began to work on a completely new implementation of the table editor — this time tapping into many of the new functions of Zettlr’s code editor, CodeMirror. We rebuilt the entire experience from the ground up to tie into the writing workflow much better so that you will no longer experience any data loss issues.
However, we did not stop there. Since we were already on it, and since we are relying heavily on CodeMirror, we also implemented many of the editing commands as keyboard shortcuts. This means that now you can perform actions such as tabbing between table cells, inserting or moving rows and columns even when you choose not to use the visual table editor. All of this functionality is also available from the context menu.
Furthermore, now even within your tables, you have access to all common keyboard shortcuts from using Cmd/Ctrl+B to make text bold to inserting links or math. This also means that the table editor now supports syntax highlighting, and in general many quality-of-life features that were thus far lacking.
One drawback, however, is that the visual table editor no longer supports grid tables. This type of tables can become very complex, and we wanted to err on the side of caution. Support for grid tables is not off the table, but we have decided to weigh the quick release of the rewritten table editor against support for grid tables, and decided to postpone this support to a later point. Some of the new keyboard shortcuts to navigate between table cells will still work even in grid tables, and even without the visual table editor, so this is a silver lining.
All in all, it took us about two entire years from the first conceptualization of the table editor to our final implementation that we are proud to deliver to you in this update. Many people have been involved at various stages of the process to make this a reality. Special thanks go to Artem Barinov, who has done tremendous work in re-thinking the user interface of the new table editor.
If you want to re-read the entire journey from the opening of the initial PR over the past 18 months, you can read the corresponding Pull Request on the repository.
Image and PDF Viewer
Another great new feature that we are happy to ship with this release is a built-in image and PDF viewer. Now Zettlr can natively open many image formats as well as PDF files side-by-side with your regular Markdown documents. Referencing a plot of your results or a PDF file while you write is easily possible.
The image viewer is a fully-native component that implements all relevant functionality to properly work with images, from zooming, to determining the viewer background, to scrolling around in the image which makes working with large images straight-forward.
For the PDF file viewer, we make use of Zettlr’s framework, Electron. Since it is essentially a Chromium-browser which already includes a PDF viewer, Zettlr leverages this ready-made component to display PDF files for you. If you already use a Chromium-based browser for your day-to-day work, you will immediately feel at home with the new PDF viewer.
It should be noted, however, that both are decisively intended as viewers. Zettlr is still a writing application, and neither a PDF tool nor an image editing program. This means that to edit PDFs or images, you are kindly asked to peruse your existing workflows.
Citation Parser
Another major new feature that we are pleased to provide to you is a rewritten citation parser. Up until now, the citation detection of Zettlr relied on very old code from our Citr library. With this update, we have adjusted the parser in two ways. First, it is now more fine-grained and interacts directly with CodeMirror. And second, it now provides proper syntax highlighting.
This has two implications. First, it means that it is now accessible to Custom CSS, in case you wish to adjust the display of your citations. But second, and more importantly, it will give you direct, visual feedback if your citation syntax is correct. Previously, it was sometimes a bit difficult to spot why Zettlr would not properly render a citation, but now this should be a thing of the past.
In addition, we also improved the parser in many ways to mirror the behavior of Pandoc Citeproc. The citation parser now understands citation keys in curly brackets (@{Some citation key}), and is more flexible to accommodate the entire range of the Citeproc syntax. This means that you’ll now be able to write more complex citations with ease.
While we were at it, we also added support for pandoc-crossref syntax. This means that cross-referencing images, tables, and equations, is now natively understood by Zettlr. However, please note that, to have this syntax work on export, you will need to install pandoc-crossref and add it to your export profiles. You can find the instructions on its GitHub page.
Workflow Improvements
Another area which we have dedicated some time for this update is the general workflow. Writing consists of many different actions that you chain together to end up with a proper text. Since some of these actions require you to press different keys (for example, to insert a link), managing how to move between them is crucial.
Zettlr has, in the past, tried to make your workflows as smooth as possible, but of course there is always room for improvement. In this update, we have taken quite a few things and improved how you can navigate your writing process.
The status bar now includes a quick switch to toggle the display mode between raw syntax (“WYSIWYM”) and fully-rendered preview (“WYSIWYG”). The editor also includes better support for reference-style links, which includes detecting such links, and offering link previews and following such links with a Cmd/Ctrl-click.
In addition, footnote insertion has received a glow-up, with better abilities to insert and remove them. The exporting workflow is now faster, with the “export”-button automatically receiving focus so that you can use Cmd/Ctrl+E, followed by Enter to start an export. In addition, the app now also remembers the export profiles for recently-exported files so that it will automatically pre-select the last profile you’ve used to export that file. This means that you need to spend less time re-selecting the correct profile over and over again.
Furthermore, Zettlr can now detect if it is in full-screen mode and, if it is, turning the distraction-free mode on will properly hide the toolbars if the corresponding setting is enabled. Also, misspellings reported by LanguageTool are now treated equally to misspellings reported by the Hunspell dictionaries. You can now access those from the context menu, too, where you can also add those words to your user dictionary. Next, the Zettelkasten link insertion workflow has received an update. Now, Zettlr utilizes the ability to have a separate link target and link label, and can insert the file title as a label, if you so choose. The label will then be selected for you in case you wish to change it after inserting a link.
Finally, the assets manager has received some improvements, especially in terms of adding new export/import profiles and snippets. Instead of creating one with an arbitrary name that you have to rename first, the manager will ask you for a filename before creating the profile or snippet. This will improve the speed and UX of adding new things.
Onboarding Screen
One thing that was mostly on our wishlist, and less on yours (probably?) is a brand-new onboarding screen. We wanted to add an onboarding screen for a long time now because we feel that, as Zettlr is becoming more complex, adding ways for new users to get accustomed to Zettlr is important.
The onboarding screen will be shown in two instances. If you update the app, the onboarding screen will notify you that the app has been updated. It is a small, comprehensive window that includes many useful links. For example, you can open the entire changelog for the update in your browser with a single click. This makes looking things up after the fact easier, and we hope that you use it to familiarize yourself with the changes before digging in.
For new users, the onboarding screen will instead show a series of panes highlighting some settings that we believe are crucial to adjust at first. Essentially, the new user onboarding experience is a preselection of settings that we deemed relevant. This allows new users to set up a few things without having to scour through the preferences window. To keep the onboarding experience as short as possible, we took some decisions, and we may change the offered settings in the future. For now, we decided to include two types of settings in the dialog: those we believe users want to customize, and those we believe users should be aware of, even if we think that most will likely keep the defaults.
If you personally want a fresh start into Zettlr, you can also trigger the onboarding screen if you remove the configuration file before starting the app. (But of course, remember to back it up first!)
Writing Statistics
One area that we kept suspiciously alone for the past years is the statistics window. While having those statistics is always nice, we were focusing mostly on improving the writing experience. But this time around, we decided that the statistics should also receive a glow-up.
So what did we change? If you click on the statistics toolbar icon and then select “More statistics,” you can view writing statistics in a calendar view and a chart view. Those two views have been heavily improved.
The calendar view has primarily received visual improvements. The days now have rounded corners, there are bigger margins between them. But, more importantly, we abandoned the somewhat arbitrary categorization of how much you have written. Instead, it now includes a heatmap style where blueish colors indicate few written words, and orange indicates a lot of written words. This will make digesting this information much easier. Also, hovering over calendar days will immediately tell you how many words you wrote on that day.
The charts view has also received a face-lift. Instead of plotting arbitrary amounts of data over days, weeks, months, and years in a difficult to parse format, we have now opted for bar charts and simplified the format. The new chart has seven x-axis fields, one for each day of the week. And for each day, it lets you compare your writing from this week to your writing over the yearly average and last year’s average.
We believe that reducing the complexity of these views has improved legibility and thus the usefulness of the statistics window by a lot.
FSAL Rewrite
One of the changes with probably the least amount of visual changes is a large-scale rewrite of the FSAL system that manages the file system view of Zettlr. If you don’t know what this is: good! If you do know, it’s probably because you’ve had some issues with the FSAL in the past.
The FSAL, or File System Abstraction Layer, is essentially a part of Zettlr that reads in some metadata from the files on your computer which you load into Zettlr, and abstracts away all the nitty-gritty of the file system (hence the name).
While we don’t want to go into the technical details of this here, because it is mostly a technical change (you can read up on what we’ve done in the accompanying Pull Request), what we do want to highlight is that the system is now much more performant. Essentially, whatever you change in other apps should now be displayed immediately and appropriately in your file manager. This primarily means that you now no longer need to worry about missing any files that are on your computer but which Zettlr somehow doesn’t show.
LUA Filters
Another feature that we wanted to implement for quite some time but didn’t manage to until now is to expose the LUA filter directory of Zettlr to you. If you’re unfamiliar with filters: Pandoc allows you to fully customize imports and exports using filters. These filters can change the contents of documents before Pandoc writes them to the desired target format.
Zettlr has shipped with two built-in filters for the past years that would automatically run. Those filters took care of adjusting how internal links and keywords were exported, removing them if you so wished. However, there are many other things that you might want to include filters for.
One great example, for instance, is a Mermaid diagram filter that imbues Pandoc with the ability to export files with Mermaid diagrams. You can find the filter on our forum thread and add it to Zettlr now, too.
The filter tab lives in the assets manager. You can also add more filters to customize exports to your liking. If you have found a great use-case, please share your filters on the forum for others who may want to use them, too!
Other Features
Besides these (already many) major new features, Zettlr also includes a host of additional, smaller improvements. Again, we recommend you read the changelog so that you can see exactly what we’ve changed, but some notable improvements are:
- Zettlr now properly “hides” the heading formatting characters. Instead of replacing them with an element that indicates the heading-level, it now hides the characters entirely. This means that headings are now aligned with the rest of your text. Instead, we have moved the indication for the heading-level to the gutter area left of the editor.
- The app now finally allows you to directly load BibLaTeX libraries. While CSL JSON libraries and BibTeX files were already supported, we are proud to be able to finally allow you to include BibLaTeX libraries.
- While Zettlr was already capable of pre-rendering various elements, one that was missing thus far was the ability to pre-render horizontal rules (
***). Some users were falling back to implementing custom CSS fixes to pre-render rules, but with this update, we finally include a proper renderer for this. - We have also finally fixed the print preview. For the past years, printing was not working due to some technical issues of how we have implemented this. But now the print preview uses our own Markdown-to-HTML converter and allows you to properly print your files out if you need them.
- Improved the placement, categorization, and wording of many preferences to be more clear and easier to understand.
- This release also includes many, many user interface and user experience improvements; style fixes, alignment improvements, and other changes that make the app look much better. This also includes an improved popover placement algorithm, so that those are now more flexible and appear in better positions, based on how much space there is.
Changes
Finally, some changes that Zettlr brings compared to previous versions, and which you should know about.
First, we have finally implemented a change to the $FILENAME-variable in the snippets. Many users have argued that, since we also have the $EXTENSION-variable, the $FILENAME-variable should not include the filename extension anymore. This release now does so. If you rely on the exact contents of the $FILENAME-variable, you should now change any occurrence of this variable to read $FILENAME$EXTENSION if you want to have the extension appear. (Note that $EXTENSION already includes the dot in front of the extension, so don’t write $FILENAME.$EXTENSION).
Also, regardless of whether you want to see the word or character count in the toolbar, the status bar below the editor will always show both counts at all times. In addition, the cursor position info element now includes the absolute cursor position in the document.
Third, we have removed the readability button from the toolbar, since the readability mode is active on a per-file basis and the toolbar button was thus decoupled from the UX of the editor-wise readability mode. To toggle the readability mode, please use the status bar.
While improving the Zettelkasten link insertion workflow, we have also adjusted its settings. The previous settings “Link with filename only” and “When linking files, add the document name…” have been removed. Instead, there are two new settings, “Always use the file title as label for internal links” and “Use the file ID as link target if possible.” The first new setting will now always insert the detected file title (which can be a YAML front matter title; first heading level 1; or the filename) as the link label. If disabled, Zettlr will always create links without labels (which is essentially the old behavior). The second setting controls whether Zettlr will always use filenames to link to files, or use IDs where available (which is essentially the “Link with filename only” setting, but reworded). Now, Zettlr no longer adds the file title after the link, and instead makes use of the ability to use link titles.
Final Thoughts
This is the biggest update to Zettlr by far, and we are proud to be able to deliver such a great new update to you. We hope that this makes all your lives easier in writing and managing your notes.
Before we end, we would like to thank our community for the great help they have provided in ensuring the success of this update. We would like to thank everyone who has diligently tested the beta releases and informed us about newly occurring bugs to ensure that this release is as bug-free as possible. We also would like to thank the people who have translated the app, gave us some good ideas, provided suggestions and other feedback on Discord, the forum, and elsewhere.
And last but not least, a special thanks goes out to GitHub user benniekiss, who has started opening new Pull Requests a few months ago, and who has since fixed an incredible amount of things in the app. A large part to why this update is as good as it is, is thanks to his high-quality contributions. Thank you!
And with that, we hope that you enjoy the new update!
Happy holidays, and have a great start into 2026!