Zettlr/Zettlr

Zettlr/Zettlr

README


  Zettlr [ˈset·lər]

A Markdown Editor for the 21stcentury.

Test Build

Homepage |   Download |   Documentation |   Mastodon |   Discord |   Contributing |   Support Us

screenshot

With Zettlr, writing professional texts is easy and motivating: Whether you are a college student, a researcher, a journalist, or an author — Zettlr has the right tools for you. Watch the video or continue reading to see what they are!

Visit our Website.

Features


Available in over a dozen languages
Tight and ever-growing integration with your favourite reference manager(such as Zotero or JabRef)
Cite with Zettlrusing citeproc and your existing literature database
Five themes and dark mode support
File-agnostic writing: Enjoy full control over your own files
Keep all your notes and texts in one place— searchable and accessible
Code highlightingfor many languages
Simple and beautiful exportswith Pandoc, LaTeX, and Textbundle
Support for state of the art knowledge management techniques (Zettelkasten)
A powerful full text searchthat helps you find anything, anywhere

… and the best is: Zettlr is Free and Open Source Software (FOSS) !

Installation


To install Zettlr, just download the latest release for your operating system. Currently supported are macOS, Windows, and most Linux distributions (via Debian- and Fedora-packages as well as AppImages).

On our website and here on GitHub, we provide a set of installers for the most common use-cases. We provide both 64-bit installers as well as installers for ARM systems (called "Apple Silicon" in the macOS ecosystem). 32-bit is not supported. We offer the following binaries directly:

Windows (x64 and ARM)
macOS (Intel and Apple Silicon)
Debian and Fedora (x64 and ARM)
AppImage (x64 and ARM)

Thanks to our community, we can also offer you a variety of other installation opportunities:

Chocolatey (Windows)
Homebrew (macOS)
AUR (Arch Linux)
FlatPack (Linux)

All other platforms that Electron supports are supported as well, but you will need to build the app yourself for this to work.

Please also consider becoming a patron or making a one-time donation !

Getting Started


After you have installed Zettlr, head over to our documentation to get to know Zettlr. Refer to the Quick Start Guide, if you prefer to use software heads-on.

The central window of Zettlr using the dark theme

Contributing


As an Open Source application, Zettlr always welcomes contributions from the community. You do not need to know how to write code to help!A full overview over all the areas where you can help can be found in our contributing guide. Here, we introduce you to the two biggest areas where we welcome help: translations and contributing code.

Translating


The development team maintains the English and German translations, but lacks adequate knowledge of other languages. All the other available translations have been created by our community.

Zettlr's translations utilize the gettext system. This means that the translations are kept in PO-files within the static/lang directory.

To update a translation, simply download the corresponding language file and edit it. You can edit PO-files with a simple text editor, but if you prefer a more comfortable graphical editor, there are many out there. One good option is the Open Source editor POedit.

As soon as you are happy with your changes, open a Pull Request here that updates the corresponding file. GitHub has created a great guide on how to open Pull Requests.

Contributing Code


Zettlr is an Electron -based app, so to start developing, you'll need to have the following installed on your computer:

A NodeJS -stack. Make sure it's at least Node 14 (lts/fermium ). To test what version you have, run node -v.
Yarn. This is the package manager for the project, as we do not commit package-lock.json -files and many commands require yarn. You can install this globally using npm install -g yarn or Homebrew, if you are on macOS.
On Windows, we recommend to install the Windows Subsystem for Linux (WSL), which will make many of the next steps easier.
A few command-line utilities that the build script requires to download Pandoc to your development setup:
cURL
unzip

An appropriate build toolchain for your operating system, since Zettlr requires a few native C++-modules that must be compiled before running the app:
macOS: On macOS, installing the XCode command-line tools via xcode-select --install suffices
Windows: On Windows, you'll need the free Visual Studio development tools that include the required tools
Linux: On Linux, there are a variety of compatible toolchains available, sometimes they are already preinstalled. Refer to your distribution's manual for more information.

Then, simply clone the repository and install the dependencies on your local computer:

  1. ``` shell
  2. $ git clone https://github.com/Zettlr/Zettlr.git
  3. $ cd Zettlr
  4. $ yarn install --frozen-lockfile
  5. ```

The --frozen-lockfile flag ensures that yarn will stick to the versions as listed in the yarn.lock and not attempt to update them.

During development, hot module reloading (HMR) is active so that you can edit the renderer's code easily and hit F5 after the changes have been compiled by electron-forge. You can keep the developer tools open to see when HMR has finished loading your changes.

What Should I Know To Contribute Code?


In order to provide code, you should have basic familiarity with the following topics and/or manuals (ordered by descending importance):

JavaScript (especially asynchronous code) and TypeScript
Node.js
Electron
Vue.js 3.x and Vuex
CodeMirror 6.x
ESLint
LESS
Webpack 5.x
Electron forge
Electron builder

Note: See the "Directory Structure" section below to get an idea of how Zettlr specifically works.


Development Commands


This section lists all available commands that you can use during application development. These are defined within the package.json and can be run from the command line by prefixing them with yarn. Run them from within the base directory of the repository.

start


Starts electron-forge, which will build the application and launch it in development mode. This will use the normal settings, so if you use Zettlr on the same computer in production, it will use the same configuration files as the regular application. This means: be careful when breaking things. In that case, it's better to use test-gui.

package


Packages the application, but not bundle it into an installer. Without any suffix, this command will package the application for your current platform and architecture. To create specific packages (may require running on the corresponding platform), the following suffixes are available:

package:mac-x64 (Intel-based Macs)
package:mac-arm (Apple Silicon-based Macs)
package:win-x64 (Intel-based Windows)
package:win-arm (ARM-based Windows)
package:linux-x64 (Intel-based Linux)
package:linux-arm (ARM-based Linux)

The resulting application packages are stored in ./out.

This command will skip typechecking to speed up builds, so be extra cautious.


release:{platform-arch}


Packages the application and then bundles it into an installer for the corresponding platform and architecture. To create such a bundle (may require running on the corresponding platform), one of the following values for {platform-arch} is required:

release:mac-x64 (Intel-based Macs)
release:mac-arm (Apple Silicon-based Macs)
release:win-x64 (Intel-based Windows)
release:win-arm (ARM-based Windows)
release:linux-x64 (Intel-based Linux)
release:linux-arm (ARM-based Linux)

The resulting setup bundles are stored in ./release.

Please note that, while you can package directly for your platform without any suffix, for creating a release specifying the platform is required as electron-builder would otherwise include the development-dependencies in the app.asar, resulting in a bloated application.


csl:refresh


This downloads the Citation Style Language (CSL) files with which the application is shipped, and places them in the static/csl-locales - and static/csl-styles -directories respectively.

Please note, that this command is intended for an automated workflow that runs from time to time on the repository to perform this action. This means: Do notcommit updated files to the repository. Instead, the updated files will be downloaded whenever you git fetch.


lint


This simply runs ESLint. Apps such as Atom or Visual Studio Code will automatically run ESLint in the background, but if you want to be extra-safe, make sure to run this command prior to submitting a Pull Request.

This command will run automatically on each Pull Request to check your code for inconsistencies.


reveal:build


This re-compiles the source-files needed by the exporter for building reveal.js -presentations. Due to the nature of how Pandoc creates such presentations, Zettlr needs to modify the output by Pandoc, which is why these files need to be pre-compiled.

Please note, that this command is intended for an automated workflow that runs from time to time on the repository to perform this action. This means: Do notcommit updated files to the repository. Instead, the updated files will be downloaded whenever you git fetch.


test


This runs the unit tests in the directory ./test. Make sure to run this command prior to submitting a Pull Request, as this will be run every time you commit to the PR, and this way you can make sure that your changes don't break any tests, making the whole PR-process easier.

test-gui


Use this command to carefree test any changes you make to the application. This command will start the application as if you ran yarn start, but will provide a custom configuration and a custom directory.

This command will skip typechecking to speed up builds, so be extra cautious.


The first time you start this command, pass the --clean -flag to copy a bunch of test-files to your ./resources -directory, create a test-config.yml in your project root, and start the application with this clean configuration. Then, you can adapt the test-config.yml to your liking (so that certain settings which you would otherwise alwaysset will be pre-set without you having to open the preferences).

Whenever you want to reset the test directory to its initial state (or you removed the directory, or cloned the whole project anew), pass the flag --clean to the command in order to create or reset the directory. This is also necessary if you changed something in test-config.yml.

If you want to prevent a config-file from being created (e.g., to simulate the first start experience), you can pass the flag --no-config to this command.

You can pass additional command-line switches such as --clear-cache to this command as well. They will be passed to the child process.

Attention: Before first running the command, you mustrun it with the --clean -flag to create the directory in the first place!


Additionally, have a look at our full development documentation.

Directory Structure


Zettlr is a mature app that has amassed hundreds of directories over the course of its development. Since it is hard to contribute to an application without any guidance, we have compiled a short description of the directories with how they interrelate.

  1. ``` sh
  2. .
  3. ├── resources                      # Contains resource files
  4. │   ├── NSIS                       # Images for the Windows installer
  5. │   ├── icons                      # Icons used to build the application
  6. │   ├── screenshots                # The screenshots used in this README file
  7. ├── scripts                        # Scripts that are run by the CI and some YARN commands
  8. │   ├── assets                     # Asset files used by some scripts
  9. │   └── test-gui                   # Test files used by `yarn test-gui`
  10. ├── source                         # Contains the actual source code for the app
  11. │   ├── app                        # Contains service providers and the boot/shutdown routines
  12. │   ├── common                     # Common files used by several or all renderer processes
  13. │   │   ├── fonts                  # Contains the font files (note: location will likely change)
  14. │   │   ├── img                    # Currently unused image files
  15. │   │   ├── less                   # Contains the themes (note: location will likely change)
  16. │   │   ├── modules                # Contains renderer modules
  17. │   │   │   ├── markdown-editor    # The central CodeMirror markdown editor
  18. │   │   │   ├── preload            # Electron preload files
  19. │   │   │   └── window-register    # Run by every renderer during setup
  20. │   │   ├── util                   # A collection of utility functions
  21. │   │   └── vue                    # Contains Vue components used by the graphical interface
  22. │   ├── main                       # Contains code for the main process
  23. │   │   ├── assets                 # Static files (note: location will likely change)
  24. │   │   ├── commands               # Commands that perform user-actions, run from within zettlr.ts
  25. │   │   └── modules                # Main process modules
  26. │   │       ├── document-manager   # The document manager handles all open files
  27. │   │       ├── export             # The exporter converts Markdown files into other formats
  28. │   │       ├── fsal               # The File System Abstraction Layer provides the file tree
  29. │   │       ├── import             # The importer converts other formats into Markdown files
  30. │   │       └── window-manager     # The window manager manages all application windows
  31. │   ├── win-about                  # Code for the About window
  32. │   ├── win-custom-css             # Code for the Custom CSS window
  33. │   ├── win-defaults               # Code for the defaults file editor
  34. │   ├── win-error                  # The error modal window
  35. │   ├── win-log-viewer             # Displays the running logs from the app
  36. │   ├── win-main                   # The main window
  37. │   ├── win-paste-image            # The modal displayed when pasting an image
  38. │   ├── win-preferences            # The preferences window
  39. │   ├── win-print                  # Code for the print and preview window
  40. │   ├── win-stats                  # Code for the general statistics window
  41. │   ├── win-tag-manager            # Code for the tag m