-
Notifications
You must be signed in to change notification settings - Fork 1k
Expand file tree
/
Copy pathhtml-themes.qmd
More file actions
143 lines (101 loc) · 9.21 KB
/
html-themes.qmd
File metadata and controls
143 lines (101 loc) · 9.21 KB
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
---
title: "HTML Theming"
tbl-colwidths: [40,60]
---
## Overview
HTML documents rendered with Quarto use Bootstrap 5 by default. This can be disabled or customized via the `theme` option:
``` yaml
theme: default # bootstrap 5 default
theme: cosmo # cosmo bootswatch theme
theme: pandoc # pandoc default html treatment
theme: none # no theme css added to document
```
Quarto includes 25 themes from the [Bootswatch](https://bootswatch.com/) project (for example, this website uses the [cosmo](https://bootswatch.com/cosmo/) theme). Available themes include:
{{< include _theme-list.md >}}
Use of any of these themes via the `theme` option. For example:
``` yaml
format:
html:
theme: united
```
You can also customize these themes or create your own new themes. Learn how to do this below in [Theme Options].
## Basic Options
If you are using a Bootstrap theme or the Pandoc theme, there are a set of options you can provide in document metadata to customize its appearance. These include:
+--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Option | Description |
+==============================================================+================================================================================================================================================================+
| `max-width` | The maximum width occupied by page content. Defaults to 1400px for bootstrap themes and 36em for the pandoc theme. |
+--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `mainfont` | Sets the [`font-family`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-family) property for the document. |
+--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `fontsize` | Sets the base CSS [`font-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-size) for the document. |
+--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `fontcolor` | Sets the default text [`color`](https://developer.mozilla.org/en-US/docs/Web/CSS/color) for the document. |
+--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `linkcolor` | Sets the default text [`color`](https://developer.mozilla.org/en-US/docs/Web/CSS/color) for hyperlinks. |
+--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `monofont` | Sets the [`font-family`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-family) property for `<code>` elements. |
+--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `monobackgroundcolor` | Sets the [`background-color`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-color) property for `<code>` elements. |
+--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `linestretch` | Sets the CSS [`line-height`](https://developer.mozilla.org/en-US/docs/Web/CSS/line-height) property (affects distance between lines of text, defaults to 1.5). |
+--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `backgroundcolor` | Sets the [`background-color`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-color) for the document. |
+--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `margin-left`, `margin-right`, `margin-top`, `margin-bottom` | Sets the CSS [`margin`](https://developer.mozilla.org/en-US/docs/Web/CSS/margin) properties for the document body. |
+--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
For example. here we set the font-size a bit larger and specify that we want a bit more space between lines of text:
``` yaml
title: "My Document"
format:
html:
theme: cosmo
fontsize: 1.1em
linestretch: 1.7
```
{{< include _theme-options.md >}}
{{< include _theme-custom.md >}}
## Dark Mode
In addition to providing a single theme for your html output, you may also provide a light and dark theme. For example:
``` yaml
theme:
light: flatly
dark: darkly
```
Setting the above themes in your `_quarto.yml` results in both a dark and light version of your output being available. For example:
------------------------------------------------------------------------
##### Flatly Themed Output
{fig-alt="A screenshot of the header of the light version of this page showcasing the Flatly theme."}
------------------------------------------------------------------------
##### Darkly Themed Output
{fig-alt="A screenshot of the header of the dark version of this page showcasing the Darkly theme."}
------------------------------------------------------------------------
When providing both a dark and light mode for your html output, Quarto will automatically create a toggle to allow your reader to select the desired dark or light appearance. The toggle will automatically appear in the top right corner of your html output. When possible, the toggle will use browser local storage to maintain the user's preference across sessions.
To honor the user's operating system or browser preference for light or dark mode, specify `respect-user-color-scheme: true`:
``` yaml
format:
html:
respect-user-color-scheme: true
```
Otherwise, the order of light and dark elements in the theme or brand will determine the default appearance for your html output. For example, since the `light` option appears first in the first example, a reader will see the light appearance by default, if `respect-user-color-scheme` is not enabled.
Quarto will automatically select the appropriate light or dark version of the text highlighter that you have specified when possible. For more information, see [Code Highlighting](html-code.qmd#highlighting).
As of Quarto 1.7, `respect-user-color-scheme` requires JavaScript support: users with JavaScript disabled will see the author-preferred (first) brand or theme.
### Customizing Themes
As when providing a single theme, you may provide a custom theme for dark and light mode, or a list of `scss` files to customize the light and dark appearance. This website, for example uses the following to use a light `cosmo` theme and then customizes the `cosmo` theme with additional Sass variables when in dark mode:
``` yaml
theme:
light: cosmo
dark: [cosmo, theme-dark.scss]
```
The contents of `theme-dark.scss` which is customizing the cosmo document appearance is:
``` css
/*-- scss:defaults --*/
// Base document colors
$body-bg: #181818;
$body-color: white;
$link-color: #75AADB;
// Code blocks
$code-block-bg-alpha: -.8;
```
For more information about available Sass variables, see [HTML Customization Using Sass Variables](html-themes-more.qmd).
{{< include _theme-variables.md >}}