feat: Changes to citation and Add Guide to choose PDF engine

Author: nathanlesage

config/en.yml

@@ -76,6 +76,7 @@ nav:
     - Exporting: export/index.md
     - Workflow: export/workflow.md
     - Defaults Files (Profiles): export/defaults-files.md
+    - Selecting the PDF Engine: export/pdf-engine.md
     - Assets Manager: export/assets-manager.md
     - Custom Templates: export/custom-templates.md
     - Custom Commands: export/custom-commands.md

docs/en/editor/citations.md

@@ -31,7 +31,7 @@ From now on, Zettlr will autocomplete any citation that you type. However, to en
 Every citation consists of **four part**, only one of which is mandatory:
 
 * a **prefix** that precedes the citation
-* a **citekey** that specifies the piece of work that shall be cited
+* a **citekey** that specifies the piece of work that shall be cited. This key is mandatory.
 * a **locator** that specifies the exact location within the work cited
 * a **suffix** that includes further information
 
@@ -45,7 +45,7 @@ You can see the prefix in yellow, the actual citation in green, the locator in p
 
 	Only the citekey is required to create a citation. All other parts are optional.
 
-The first thing to recognize is that **Zettlr does not use Zotero’s citation picker**. Instead it utilizes Pandoc’s citation syntax. Pandoc’s citation syntax is equivalent to the citation picker, but instead of using a graphical interface to modify your citation, you write out all the parts of your citation directly. This can be much faster once you are attuned to the syntax.
+The first thing to recognize is that **Zettlr does not use Zotero’s citation picker**. Instead, it utilizes Pandoc’s citation syntax. Pandoc’s citation syntax is equivalent to the citation picker, but instead of using a graphical interface to modify your citation, you write out all the parts of your citation directly. This can be much faster once you are attuned to the syntax.
 
 The syntax for writing a citation using Pandoc syntax is almost the same as what it will look like when rendered:
 
@@ -134,7 +134,7 @@ As you cite, Zettlr will automatically generate a preview bibliography in the [S
 
 ## Using a file-specific library
 
-Sometimes you may want to add a few citation keys on a per-file basis. To do so, you must add the bibliography file to your file's [YAML frontmatter](./yaml-frontmatter.md). If Zettlr detects the `bibliography` property in a file's frontmatter, it will automatically load that file and offer you items from that file instead of your main library.
+Sometimes you may want to add a few citation keys on a per-file basis. To do so, you must add the bibliography file to your file's [YAML frontmatter](./yaml-frontmatter.md). If Zettlr detects the `bibliography` property in a file's front matter, it will automatically load that file and offer you items from that file instead of your main library.
 
 Example:
 
@@ -156,32 +156,38 @@ Internally, Zettlr will always use the Chicago style to render citations. Theref
 
 But of course you can use different citation styles, depending on either the journal requirements for which you are writing, or your personal preferences. To change the citation style, you need to download the corresponding CSL file. A very good starting point is the [Zotero style repository](https://www.zotero.org/styles). There you can search for specific citation styles, preview them and download them. Another good option is the [Citation Style Language styles repository](https://github.com/citation-style-language/styles)
 
-You can point Zettlr to a CSL file in two ways. First in the general preferences. In the `Export` tab, beneath the field for your citation database file, you can select your preferred CSL style. This will be used for all single-page exports using the toolbar button.
+You can point Zettlr to a CSL file in three ways. First in the general preferences. In the `Export` tab, beneath the field for your citation database file, you can select your preferred CSL style. This will be used for all exports.
 
 Second, you can set specify a CSL style for a specific project. With your project folder visible in the file manager, right-click on the project folder and select “Properties” → “Project Settings….” In the “Files” tab you can specify the CSL file to use when exporting your project.
 
+Third, you can specify a CSL style only for one particular file, by providing it in the file’s YAML front matter. For example:
+
+```yaml
+csl: ./styles/acta-philosophica.csl
+```
+
 ## Customizing the List of References
 
-By default, Pandoc will simply append a list of references to the end of your documents without any decoration. Therefore, you need to perform a few housekeeping steps to ensure bibliographies are properly rendered.
+By default, Pandoc will simply append a list of references to the end of your documents without any decoration. This is usually not desirable, especially since reference lists should have at least a heading.
 
 ### Adding a Section Header
 
-The simplest task is to provide a section header for the list of references. The easiest way to do so is to append a heading called “References,” “Bibliography,” or similar to the end of your document. While this may look a little off when looking at the document in Zettlr, this will ensure that the bibliography has an appropriate heading on export. Since Pandoc will simply append the rendered bibliography to your document, this “lone” heading will then become the heading for your list of references upon export.
+The easiest way to add a section header to your list of references is to append a heading called “References,” “Bibliography,” or similar to the end of your document. While this may look a little off when viewing the document in Zettlr, this will ensure that the bibliography has an appropriate heading on export. Since Pandoc will simply append the rendered bibliography to your document, this “lone” heading will then become the heading for your list of references upon export.
 
-However, this may become cumbersome quickly, as you create more and more files. It would be great if you could automate this process. Fortunately, you can do so.
+However, this can quickly become cumbersome, as you create more and more files. It would be great if you could automate this process. Fortunately, you can do so.
 
-Instead of specifying the heading section everytime, you can provide a default name for each export profile. To do so, head into the [Assets Manager](../export/assets-manager.md), e.g., by pressing <kbd>Cmd/Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>,</kbd>. In the “Export” tab, select the profile you wish to provide a default reference section for, and add the following code:
+Instead of specifying the heading section every time, you can provide a default name for each export profile. To do so, head into the [Assets Manager](../export/assets-manager.md), e.g., by pressing <kbd>Cmd/Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>,</kbd>. In the “Export” tab, select the profile you wish to provide a default reference section for, and add the following code:
 
 ```yaml
 metadata:
   reference-section-title: "References"
 ```
 
-Customize “References” to your liking (e.g., “Bibliography,” or a translation thereof). If the profile already has the propery `metadata`, place the `reference-section-title` in there instead of duplicating the property. Ensure proper indentation.
+Customize “References” to your liking (e.g., “Bibliography,” or a translation thereof). If the profile already has the property `metadata`, place the `reference-section-title` in there instead of duplicating the property. Ensure proper indentation.
 
 ### Customizing the `reference-section-title` on a per-file basis
 
-Specifying the `reference-section-title` in an export profile has the benefit that you won't have to remember to add a heading anymore, but it will also mean that all your files will receive the default wording. What if you want certain files to have a different section header? Pandoc allows you to also provide this label using the [YAML frontmatter](./yaml-frontmatter.md). To do so, simply place the `reference-section-title` on its own line (not indented) within a file's YAML frontmatter. This will overwrite the default you have provided in the defaults file (hence the name!).
+Specifying the `reference-section-title` in an export profile will apply this title to all files. But what if you want certain files to have a different section header? Pandoc allows you to also provide this label using the [YAML frontmatter](./yaml-frontmatter.md). To do so, simply place the `reference-section-title` on its own line (not indented) within a file's YAML front matter.
 
 !!! warning
 
@@ -191,10 +197,6 @@ Specifying the `reference-section-title` in an export profile has the benefit th
 
 By default, Pandoc will append the rendered reference section to your document, which in almost all cases is sufficient. However, in some rare circumstances, this is not ideal. For example, imagine you are writing a report with a few appendices. Usually, you want the list of references to appear after the main body of the report, but before any of the appendices.
 
-!!! warning
-
-	If you explicitly specify the location of your references by placing a `#refs`-container, Pandoc will ignore your `reference-section-title`. In this case, you must specify the heading manually.
-
 To do so, you can tell Pandoc explicitly where to place the list of references. You do so by creating a container with the ID `#refs`. Pandoc recognizes this, and will place the bibliography into this container, instead of just appending the list. For example:
 
 ```markdown
@@ -214,6 +216,10 @@ Some appendix information...
 
 Pandoc will replace the three-colon-curly-bracket construction with your list of references.
 
+!!! warning
+
+	If you explicitly specify the location of your references by placing a `#refs`-container, Pandoc will ignore your `reference-section-title`. In this case, you must specify the heading manually (as shown in the example).
+
 !!! tip
 
     This also implies that you can provide the list of references multiple times. Pandoc will place the list of references into any container with the ID `#refs`. You can read more on placing the bibliography in the [Pandoc manual](https://pandoc.org/MANUAL.html#placement-of-the-bibliography).

docs/en/export/pdf-engine.md

@@ -0,0 +1,41 @@
+# Selecting the PDF Engine
+
+While Zettlr can export to almost any format using the embedded Pandoc binary, exports to PDF are much more complex, and as such require an additional program to succeed.
+
+Across this entire documentation and the app, we always suggest LaTeX, because it is still the most powerful and easy accessible solution around, albeit competitors like Typst are quickly becoming strong contenders.
+
+Zettlr ships with an export profile by default that uses LaTeX — more specifically, the XeLaTeX binary — to export to PDF. However, depending on your needs, you can change the PDF engine that is used.
+
+## The Default PDF Profile
+
+First, let us walk through the relevant positions in the default PDF export profile, the “XeLaTeX PDF” one. The relevant settings here are the following:
+
+```yaml
+# Other properties omitted for brevity
+reader: markdown
+writer: pdf
+pdf-engine: xelatex
+```
+
+This instructs Pandoc, when you use this profile, to convert a Markdown document into a PDF file using the XeLaTeX compiler as the PDF engine. Depending on the value of `pdf-engine`, Pandoc will use different programs to create the PDF file. Therefore, you can simply change this property to instruct Pandoc to use a different PDF engine.
+
+## Changing the PDF Engine
+
+As of the time of writing (January 2026), Pandoc supports the following PDF engines: `pdflatex`, `lualatex`, `xelatex`, `latexmk`, `tectonic`, `wkhtmltopdf`, `weasyprint`, `pagedjs-cli`, `prince`, `context`, `groff`, `pdfroff`, and `typst`.
+
+!!! warning
+
+	Since all of these engines are external programs, you need to make sure you have the engine of your choice installed on your computer. Refer to their corresponding documentation to see how to install them. If you select an engine that is not installed, Zettlr will show you an error message.
+
+You can change the PDF engine directly in the XeLaTeX PDF profile. However, we recommend against doing so, since this will lead to confusion if the profile called “XeLaTeX PDF” suddenly requires, say, Typst to be installed.
+
+Instead, we recommend you create a copy of this profile. You can do so quickly, by renaming the profile accordingly. For example, if you wish to use Typst instead, perform the following steps:
+
+1. In the [assets manager](./assets-manager.md), navigate to the “Export” tab, and select the “XeLaTeX PDF” profile.
+2. Click into the name text field, and enter a new name for the profile based on the PDF engine you want to use, e.g. “Typst PDF.yaml.”
+3. Click “Rename file.”
+4. Since the XeLaTeX PDF profile is protected, this will not rename the file, and instead create a duplicate.
+5. In this duplicate, change the value of `pdf-engine` to `typst` (or whichever engine you want to use).
+6. Adjust other settings as desired.
+
+From now on, you can export using the selected PDF engine by exporting using this new profile.

docs/en/getting-started/installing-latex.md

@@ -6,7 +6,7 @@ To export more advanced PDF files, you'll need to install [LaTeX](https://en.wik
 
 !!! tip
 
-    Zettlr supports several engines to create PDF files, not just LaTeX. For example, Zettlr also supports Tectonic or Typst. Across this documentation, we focus on LaTeX, as it is the most reliable system for creating PDF files. However, you can select which PDF-engine you want to use by modifying your [export profiles ("Defaults files")](../export/defaults-files/).
+    Zettlr supports several engines to create PDF files, not just LaTeX. For example, Zettlr also supports Tectonic or Typst. Across this documentation, we focus on LaTeX, as it is the most reliable system for creating PDF files. You can select which PDF-engine you want to use by modifying your [export profiles ("Defaults files")](../export/defaults-files/). If you do not wish to use LaTeX for PDF exports, you do not need to install LaTeX. We have written an easy guide to [choosing the right PDF engine](../export/pdf-engine.md) here in the documentation.
 
 LaTeX distributions usually come in two flavors: A “full” installation featuring a host of graphical programs for writing TeX directly, and a “minimal” installation that only contains the actual compilers. Zettlr is happy with only a minimal installation (because it just needs the compiler), but if you want to fiddle around with LaTeX more you are free to install the full package.