-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathtemplate.qmd
147 lines (94 loc) · 8.02 KB
/
template.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
---
title: Tufte inspired Typst template (in Quarto)
shorttitle: Tufte-Memo Usage Guide
subtitle: The Tufte-Memo Usage guide and background
author:
- name: Author One
affiliations:
- name: An Organization
email: email@email.com
- name: Noah Gula
email: "github.com/nogula"
- name: Christopher T. Kenny
email: "github.com/christopherkenny"
abstract: This Quarto template adopts many aspects of the design and typography of Edward Tufte's books and extends [nogula](https://github.com/nogula)'s Typst template. The document itself demonstrates the functionality and usage of the template, including setup, sidenotes, figure display, citations, and more.
date: today
bibliography: bibliography.bib
format:
tufte-typst: default
functions:
- note
- wideblock
---
# Introduction
Edward Tufte is an American statistician, professor, and pioneer in the field of data visualization, known for his work on the visual presentation of data and information. He is the author of influential books such as "The Visual Display of Quantitative Information" @Tufte2001 and is renowned for his principles on clarity, precision, and efficiency in data graphics. His books have inspired a unique design and typography, created by Howard Gralla.
This template adopts many of the conventions used by Gralla and Tufte and allows the interested author to obtain a similar appearance to style of Tufte's publications. However, the design adapts the book-format to work as an article (i.e., not having multiple parts and chapters and so forth, but instead something more akin to a memo or academic journal article).
This document is a skeuomorph[This document is not only a skeuomorph, but also tests the template itself.]{.note} of the template; it intends to demonstrate the template's functionality across various frontmatter styles, citations, figures, and importantly, sidenotes.
# Using this template
This template will function primarily as a normal Quarto template and requires no special configuration to use the basic features.
However, to get full use of all Tufte-style features, you may find some additional features useful.
To support this, the [(christopherkenny/typst-function)](https://github.com/christopherkenny/typst-function) filter is embedded.
The next three subsections demonstrate how to use wideblocks, side notes, and place figures in the margin.
Quarto does not currently support margin *figures* so a slightly modified syntax is needed to use this feature.^[[At the time of writing this](https://github.com/quarto-dev/quarto-cli/blob/fe989e5468f2a5e0545a0db441a771a74f9e3098/src/resources/filters/customnodes/floatreftarget.lua#L1002-L1006), any "margin" positions in Typst were converted to "bottom", hence the need for this approach.]
You should keep the following in the document metadata:
```
functions:
- note
- wideblock
```
You are welcome to add to this, but removing these will limit your ability to use wideblocks (full width elements) and note (margin-only elements).
## Wideblocks
::: {.wideblock}
You may have noticed that this text spans the entire width of the page whereas the preceeding two pages were compressed to a four-inch-wide column in the typical manner of Tufte books. The template makes permissible the ability to break the narrow column format when desired by using a Typst-based `#wideblock()` function, which takes a single required argument representing the content to be displayed. The simplest way to use the wideblock is by using a div:
```md
::: {.wideblock}
your content
:::
```
:::
The wideblock simply is a Typst `block` but with the width parameter adjusted to make the block 6.5 inches wide. This can be useful when a full page does not contain any sidenotes and otherwise the text would look somewhat awkward being unnecessarily compressed into a narrow column.
## Sidenotes
In Tufte books, sidenotes[This is a sidenote; perhaps you have already noticed them in this document.]{.note} are a distinctive feature: sidenotes are used for a variety of purposes, but mainly to provide non-critical but related information. In a basic sense, they are simply footnotes but put on the side. Sidenotes appear closer to the text being referenced.
This template implements sidenotes with a Typst `#note()` function. The simplest sidenote is created with `[enter your content here]{.note}` which yields:[enter your content here]{.note}. Notice how the sidenote is automatically numbered like a footnote. This can be disabled with the `numbered: false` argument.[This sidenote is not numbered.]{.note arguments="numbered: false"}
Sidenotes are most typically set with a span, `[text]{.note}` which is converted to Typst code for `#note()` with the `typst-function` filter.
On the backend, the `note()` function uses the `drafting` package @Jessurun2023, pre-configured with some defaults. Importantly, though, the `dy` argument can still be passed to `note()` in order to adjust the vertical offset as it appears. This is helpful when many notes are included in close vicinity. Though, `drafting` package will attempt to adjust vertical positions in such cases, sometimes a manual touch is necessary.
Strictly speaking, the `note()` function can be used with content of any kind, including figures. More will be discussed on the side figure topic, so it will be left for now.
There is one other type of sidenote: the citation-sidenote. Citations here follow the standard [Quarto syntax](https://quarto.org/docs/authoring/citations.html).
However, they are processed to be placed in the right margin.
## Figures
Figures can be displayed in three different ways.
A standard figure, which sits within the body text can be placed as normal, without any special configuration.
This is demonstrated with @fig-plain-figure, below.
These figures only occupy the four-inch-wide space making up the width of the document.
::: {#fig-plain-figure}
{{< placeholder 400 200 format=svg >}}
This is just a plain figure.
:::
Second, a `wideblock()` can be used to display a larger (or, at least wider) figure in the text, which spans 6.5 inches rather than four. This is demonstrated with @fig-wide.
::: {.wideblock}
::: {#fig-wide}
```{=typst}
#rect(width:100%, height:3in)
```
The widest figure you've ever seen!
:::
:::
Note that this figure also demonstrates the ability to place raw Typst blocks within figures. You can mix and match as you see fit, but I strongly recommend using the basic figure formatting from Quarto, otherwise you may need to manually control figure kinds and their respective counters. In general, if you use Quarto syntax where possible and only resort to raw Typst at the last moment (like above using `#rect` only after setting up the figure), things should work.
Third, you can also display figures in the margin.
@fig-side-figure demonstrates this.
You can adjust their location using the `dy` argument to `note()`. You can use any [Typst length](https://typst.app/docs/reference/layout/length/), inlcuding inches ("in") or centimeters ("cm"). This note is moved 1.2 inches down on the page.
::: {.note arguments="dy:-1.2in, numbered:false"}
::: {#fig-side-figure}
{{< placeholder 200 200 format=svg >}}
This is a little figure in the sidenotes.
:::
:::
## Other Formatting
This template supports headings up to and including the third level. Levels below this are supported, but will use standard Quarto styling.
Text is displayed with a modest lightness (`luma(30)`) to reduce the harshness of the contrast between the type and the paper; links are displayed underline like <www.example.com>.
To start a bibliography on a new page, it is recommended to use the [`{{{< pagebreak >}}}` shortcode](https://quarto.org/docs/authoring/markdown-basics.html#page-breaks) which is included in Quarto automatically.
# Epilogue
#### [nogula](https://github.com/nogula)'s original thanks
Thank you to Edward Tufte for inspiring this template, and to other Typst contributes, particularly Nathan Jessurun for `drafting`.
#### [christopherkenny](https://github.com/christopherkenny)'s thanks
Thank you to nogula for building the Typst template from which this Quarto template is built.