Your One-Stop Publication Workbench
Your One-Stop Publication Workbench.
Homepage | Download | Documentation | Community Forum | Discord | Contributing | Support Us | Mastodon
Zettlr brings simplicity back to your texts. Open-minded writing that adapts to your style. Fast information retrieval that finds what matters to you. Versatile exporting that enables you to adapt to whatever publication pipeline your employer or school uses. Focus on what matters to you. **Publish, not perish.** > [Learn more on our website](https://zettlr.com/). *** **Table of Contents** - [Features](#features) - [Getting Started](#getting-started) - [Building from Source](#building-from-source) - [Contributing](#contributing) - [Getting Started](#getting-started-1) - [Tech Stack](#tech-stack) - [Debugging](#debugging) - [Architecture Overview](#architecture-overview) - [Development Commands](#development-commands) - [Build Flags](#build-flags) - [Directory Structure](#directory-structure) - [Command-Line Switches](#command-line-switches) - [VSCode Extension Recommendations](#vscode-extension-recommendations) - [License](#license) ## Features - Your Notes are your notes: Zettlr is **privacy-first** - **Citations** made easy: Tight and ever-growing integration with your favorite reference manager (Zotero, JabRef, and many others) - Available in over a **dozen languages** - Draft your publications in a professional environment, with **LaTeX and Word template support** - Simple and beautiful exports with [Pandoc](https://pandoc.org/), [LaTeX](https://www.latex-project.org/), and [Textbundle](http://textbundle.org/) - **Snippets** allow you to automate insertion of boilerplate code - Themes, dark modes, and full flexibility with **custom CSS** - **Code highlighting** for many languages - Support for state of the art knowledge management techniques (**Zettelkasten**) - A powerful **full text search** that helps you find anything, anywhere … and the best is: **Zettlr is [Free and Open Source Software (FOSS)](https://en.wikipedia.org/wiki/Free_and_open-source_software)!** ## Getting Started [Download the latest release](https://www.zettlr.com/download/) and install it as you would any other app. Currently supported are macOS, Windows, and most Linux distributions. 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: * macOS (Intel and Apple Silicon) * Windows (x64) * Debian/Ubuntu (x64 and ARM) * Fedora/Red Hat (x64 and ARM) * AppImage (x64 and ARM) Thanks to our community, we can also offer you a variety of other setup opportunities via package managers: * [Homebrew (macOS)](https://formulae.brew.sh/cask/zettlr) * [Aptitude (Ubuntu/Debian)](https://apt.zettlr.com) * [Flathub (Linux)](https://flathub.org/apps/details/com.zettlr.Zettlr) * [Chocolatey (Windows)](https://community.chocolatey.org/packages/zettlr/) * [Arch Linux](https://wiki.archlinux.org/title/Zettlr) All other [platforms that Electron supports](https://www.electronjs.org/docs/latest/development/build-instructions-gn#platform-prerequisites) are supported as well, but you will need to build the app yourself. > [!TIP] > Zettlr is fully supported by community donations. You can donate once, or > monthly. [Learn more on our website](https://www.zettlr.com/supporters). > Thank you! After you have installed Zettlr, [head over to our documentation](https://docs.zettlr.com/) to get to know Zettlr. The app ships with a small tutorial which covers the basics. If you are new to Zettlr, refer to our [first time users guide](https://docs.zettlr.com/en/first-time-users/first-steps/). You might also want to consider [installing LaTeX](https://docs.zettlr.com/en/getting-started/installing-latex/) to unlock all export profiles of the app. ## Building from Source You can compile the app for yourself, if you prefer. To do so, refer to our development guide below to ensure you have all required dependencies installed. Then, you can build the app for your computer using the command `yarn package`. ## 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](./CONTRIBUTING.md). In the following, we introduce you to setting up the Zettlr source code locally. ### Getting Started Zettlr is an [Electron](https://www.electronjs.org/)-based app. To start developing, you'll need to have the following installed on your computer: 1. [NodeJS](https://nodejs.org/). Make sure it's at least Node 22 (`lts/jod`). To test what version you have, run `node -v`. 2. [Yarn](https://yarnpkg.com/en/). 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. 3. On Windows, we recommend to [install the Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install), which will make many of the next steps easier. 4. A few command-line utilities that various scripts require for running the development builds: * [`cURL`](https://curl.se/download.html) (required by the Pandoc download script) * `unzip` (required by the Pandoc download script) * [`jq`](https://jqlang.github.io/jq/) (required by the i18n script) 5. 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](https://visualstudio.microsoft.com/free-developer-offers/) 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: ```bash git clone https://github.com/Zettlr/Zettlr.git cd Zettlr yarn install --immutable ``` > [!CAUTION] > Ensure you run `yarn install` with the `--immutable` flag. This ensures that > yarn will stick to the versions as listed in the `yarn.lock` and not attempt > to update them. This can prevent supply-chain attacks that could infect your > computer. 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. ### Tech Stack Zettlr relies on three tech stacks: Electron, Node.js, and Vue for the frontend. In order to provide code, you should have basic familiarity with the following topics and/or manuals (ordered by descending importance): * [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) (especially asynchronous code) and [TypeScript](https://www.typescriptlang.org/docs/) * [Node.js](https://nodejs.org/api/) * [Electron](https://www.electronjs.org/docs) * [Vue.js 3.x](https://vuejs.org/guide/introduction.html) and [Pinia](https://pinia.vuejs.org/) * [CodeMirror 6.x](https://codemirror.net/docs/) * [ESLint](https://eslint.org/) * [Webpack 5.x](https://webpack.js.org/concepts/) * [Electron forge](https://www.electronforge.io/) * [Electron builder](https://www.electron.build/) ### Debugging Zettlr offers full debugging-support within VS Code, powered by configurations in `.vscode/launch.json`. You can start a debugging session directly from the debugging sidebar. You can debug either the main process or attach the debugger to an individual renderer process. > [!TIP] > To learn more about debugging in VS Code, > [read the official guide](https://code.visualstudio.com/docs/debugtest/debugging). ### Architecture Overview As an Electron-app, Zettlr inherits its distinction into one main process and several renderer processes, the latter of which correspond to the individual windows. On top of this, Zettlr implements a relatively classical server/single-page-application pattern. Here, the main process functions as a server that orchestrates the application windows (think of each as its own, individual, SPA) and enables a bridge between them and the operating system. All main process code resides in the `source/app` directory, which includes three parts: 1. The `lifecycle.ts` module that performs pre-boot environment checks and facilitates start and shutdown of the app. 2. The `app-service-container.ts` file which includes the primary application service container. 3. The various service providers in the folder `service-providers`, which are all classes implemented as singletons. During boot, the lifecycle module will perform an environment check and then continue to load the application service container, which in turn loads all the service provider singletons. Those will remain active and running throughout the lifetime of the app. They serve requests from the renderer processes (implemented via Electron's IPC module) and monitor the operating system, e.g., for theme or file changes. The individual renderer processes, or windows, are managed by the `WindowManager`, which is a service provider. Upon request, it will instantiate a new `BrowserWindow` and load the correct entry point for the SPA that serves as the corresponding window. The renderers are fully functional SPAs with three notable differences compared to normal SPAs: 1. Instead of communicating with an API using `fetch`, they communicate with the main process via the IPC module. This works essentially akin to websockets, except we do not have to instantiate a connection first. 2. The IPC communication is injected into every window using the same preload script (`source/common/modules/preload`). 3. They are implemented in a more desktop-oriented way with Vue modules that are ordered according to desktop design principles, rather than website layouts. ### 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` Use this command to carefree test any changes you make to the application. This command will start the application, but will provide a custom configuration and a custom directory. Thus, it will not touch any files that a regular Zettlr installation will use. > [!CAUTION] > **The first time you start this command**, pass the `--clean`-flag to copy a > bunch of test-files to your `./resources`-directory, create a >