https://github.com/mvuorre/quarto-preprint
A Quarto extension for preprints using Typst
https://github.com/mvuorre/quarto-preprint
preprints quarto quarto-extension quarto-template quartopub typst
Last synced: 6 days ago
JSON representation
A Quarto extension for preprints using Typst
- Host: GitHub
- URL: https://github.com/mvuorre/quarto-preprint
- Owner: mvuorre
- License: cc-by-4.0
- Created: 2024-06-12T07:50:34.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-11-28T13:26:09.000Z (11 months ago)
- Last Synced: 2025-01-20T22:57:50.266Z (9 months ago)
- Topics: preprints, quarto, quarto-extension, quarto-template, quartopub, typst
- Language: Lua
- Homepage: https://mvuorre.github.io/quarto-preprint/index.pdf
- Size: 3.6 MB
- Stars: 40
- Watchers: 2
- Forks: 2
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# quarto-preprint
A Quarto extension for creating PDF documents with Typst
# Examples
| Default output | `theme: jou` output | Full-width content | Single-column appendices |
|:--:|:--:|:--:|:--:|
| [](examples/example.pdf) | [](examples/example-jou.pdf) | [](examples/example-jou.pdf#page=2) | [](examples/example-jou.pdf#page=3) |
# Overview
> “An article about computational science in a scientific publication is not the scholarship itself, it is merely advertising of the scholarship. The actual scholarship is the complete software development environment and the complete set of instructions which generated the figures.”
>
> –Buckheit and Donoho (1995, paraphrasing Jon Claerbout)
[Quarto](https://quarto.org/) is "An open-source scientific and technical publishing system" for writing reproducible documents that combine computations and prose written in [markdown](https://quarto.org/docs/authoring/markdown-basics.html) into HTML, PDF, Word, and other outputs. For many R users, Quarto is a successor of [R Markdown](https://rmarkdown.rstudio.com/) but with a broader scope and better support for different output formats and computational content in other languages.
[*quarto-preprint*](https://github.com/mvuorre/quarto-preprint) is a Quarto extension that provides the ***preprint-typst*** output format. When using this format, Quarto renders your document into PDF using [Typst](https://typst.app/), a modern replacement for LaTeX. *preprint-typst* builds on the standard Quarto Typst template and enables separated author-affiliation formatting, additional metadata variables for scholarly writing, opinionated but customizable typesetting, improved two-column layouts (including full-width floats), appendices, and more. In addition, *preprint-typst* aims to
- Be **fast**: Typst creates PDF files very quickly
- **Just Work**: No LaTeX installation required (Typst ships with Quarto)
- Be **100% Quarto compatible**: Switch between output formats without changing content
- Have **rich features**: Separated author-affiliation formatting, two-column layouts, full-width floats, appendices
# Installation
## Add to existing Quarto project
``` bash
quarto add mvuorre/quarto-preprint
```
This creates a `_extensions/preprint/` directory in your project. The *preprint-typst* format is then ready to use.
## Start new Quarto project
``` bash
quarto use template mvuorre/quarto-preprint
```
This creates a new project directory with a starter document, [\_quarto.yml](https://quarto.org/docs/projects/quarto-projects.html#shared-metadata) configuration file, and example bibliography.bib file.
Note that *quarto-preprint* is the name of the Quarto extension, and *preprint-typst* is the name of the Quarto output format.
# Configuration
Quarto document output is configured through YAML front matter [metadata](https://quarto.org/docs/authoring/front-matter.html). To use *preprint-typst* as the [output format](https://quarto.org/docs/output-formats/all-formats.html), include `format: preprint-typst` in the front matter. Here is a minimal example that specifies a title, a table of contents, and two output formats:
``` yaml
---
title: "My Paper"
toc: true
format:
preprint-typst:
wordcount: true
html:
theme: cosmo
---
Your content here...
```
Front matter variables can be shared across output formats (such as `toc` above) or specific to them (like `wordcount` above). See Quarto’s [guide](https://quarto.org/docs/authoring/front-matter.html) to writing scholarly documents and Quarto’s Typst format [documentation](https://quarto.org/docs/output-formats/typst.html).
*preprint-typst* supports all of Quarto’s YAML front matter variables for [scholarly writing](https://quarto.org/docs/authoring/front-matter.html) and [Typst documents](https://quarto.org/docs/output-formats/typst.html). Below, we document the additional variables supported by *preprint-typst*.
## *preprint-typst* extension options
*preprint-typst* enables these custom variables for Typst output:
- `running-head` (string) - Short title text displayed in page headers
- Example: `running-head: "Short Title"`
- `authornote` (string) - Text appearing after corresponding author information
- Example: `authornote: "Author affiliations and contact"`
- `wordcount` (boolean) - Display word count below abstract
- Example: `wordcount: true`
- `theme` (string) - Select a theme ("default", "jou")
- Example: `theme: jou` creates an optimized two-column layout
- `functions` (array) - Enable Typst functions in Quarto divs \[[typst-function](https://github.com/christopherkenny/typst-function)\]
- Example: `functions: ["place"]`
- `corresponding-text` (string) - How to refer to corresponding authors (default: "Send correspondence to:")
- Example: `corresponding-text: "Corresponding authors:"` displays as "Corresponding authors: Name, email."
## Typography
- `monofont` (string) - Font family for code \[[Quarto](https://quarto.org/docs/reference/formats/html.html#fonts)\]
- Example: `monofont: "Monacy"`
- `linkcolor` (string) - Color for hyperlinks \[[Quarto](https://quarto.org/docs/output-formats/html-themes.html#basic-options), [Typst](https://typst.app/docs/reference/visualize/color/)\]
- Example: `linkcolor: "blue"` or `linkcolor: "#0066cc"`
## Layout
- `line-number` (boolean) - Enable line numbers \[[Typst](https://typst.app/docs/reference/model/par/#definitions-line-numbering)\]
- Example: `line-number: true`
- This is simplified to a boolean instead of allowing custom numbering as per Typst.
- `leading` (string) - Line height/spacing between lines \[[Typst](https://typst.app/docs/reference/model/par/#parameters-leading)\]
- Example: `leading: "0.5em"`
- `spacing` (string) - Vertical spacing between paragraphs \[[Typst](https://typst.app/docs/reference/model/par/#parameters-spacing)\]
- Example: `spacing: "0.6em"`
- `first-line-indent` (string) - Indentation for paragraph first lines \[[Typst](https://typst.app/docs/reference/model/par/#parameters-first-line-indent)\]
- Example: `first-line-indent: "1.8em"`
- `all` (boolean) - Whether to indent all paragraphs (including first in section) \[[Typst](https://typst.app/docs/reference/model/par/#parameters-first-line-indent)\]
- Example: `all: false`
- `col-gutter` (string) - Horizontal spacing between columns \[[Typst](https://typst.app/docs/reference/layout/columns/#parameters-gutter)\]
- Example: `col-gutter: "4.2%"` or `col-gutter: "2em"`
## Language
- `lang` (string) - Document language \[[Quarto](https://quarto.org/docs/authoring/language.html), [Typst](https://typst.app/docs/reference/text/text/#parameters-lang)\]
- Example: `lang: "en"` or `lang: "de"`
- `region` (string) - Document region \[[Quarto](https://quarto.org/docs/authoring/language.html), [Typst](https://typst.app/docs/reference/text/text/#parameters-region)\]
- Example: `region: "US"` or `region: "GB"`
## Bibliography & citations
Typst has its [own citation processing system](https://quarto.org/docs/authoring/citations.html#typst), but by default *preprint-typst* turns it off by using `citeproc: true` to allow better bibliography customization and use of Quarto’s [`#refs` div](https://quarto.org/docs/authoring/citations.html#bibliography-generation). In your document, include
``` md
# References
::: {#refs}
:::
```
to display the bibliography section anywhere in the document (for example, before any appendices).
### Citation management
Quarto documents require citations in a separate .bib file. The [vscode-zotero](https://vuorre.com/posts/zotero-positron-vscode/) VS Code plugin helps with inserting in-text citations and managing the .bib file. The plugin works in all VS Code based editors, including [Positron](https://github.com/posit-dev/positron).
# Extra features
## Full-width content
You can include page-wide figures (or any other content) in documents that have more than one column. To do so, wrap the content in a [Quarto div](https://quarto.org/docs/authoring/markdown-basics.html#sec-divs-and-spans) like this:
``` md
::: {.place arguments='top, scope: "parent", float: true'}
Any content here will span the whole page.
:::
```
The above uses the Typst’s [`place()` function](https://typst.app/docs/reference/layout/place/) through the [typst-function](https://github.com/christopherkenny/typst-function) Quarto extension to place the div’s content in `"parent"` scope (the document page is the column’s parent) and must specify that Typst should treat the content as a float. The first argument `top` specifies that the content should be placed on the top of the page; use `bottom` to place it on the bottom.
Since this feature uses a Quarto div, if you want to include further divs inside this div, use more colons. For example:
```md
:::: {.place arguments='top, scope: "parent", float: true'}
::: {#fig-wide fig-cap="Full-width figure"}
{{< placeholder 600 200 format=svg >}}
:::
Other full-width content. Note linebreaks here (between the colons and content) are important.
::::
```
Note: The function only takes effect in Typst documents, other formats (e.g. HTML) will display the content with no extra formatting.
## Appendices
To include an appendix, include the following [raw Typst](https://quarto.org/docs/output-formats/typst.html#raw-typst) block in your Quarto document, followed by your appendix content:
```` md
```{=typst}
#show: appendix.with()
```
# Appendix title
Appendix content.
````
Note: If you want the appendix to appear as an [appendix in HTML output](https://quarto.org/docs/authoring/appendices.html) as well, add the `.appendix` class to the headings. Appendices are an experimental feature. They are provided through a custom Typst function, and their implementation and functionality may change as Quarto’s Typst integration matures.
# Get help & contribute
Send your comments, bug reports, and pull requests to . If you’re reporting a bug, please include a reproducible example / full details of what you’re trying to do, how, and what goes wrong.