-
Notifications
You must be signed in to change notification settings - Fork 907
/
Copy pathhtml-themes.qmd
149 lines (107 loc) · 9.2 KB
/
html-themes.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
148
149
---
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
::: {.callout-tip}
These settings only apply to the `html` output format; more basic options can be set across all formats with a [brand file](/docs/reference/metadata/brand.qmd)
:::
If you are using a Bootstrap theme or the Pandoc theme, there are a set of options you can provide in `_quarto.yml` or 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 in a specific document:
``` yaml
---
title: "My Document"
format:
html:
theme: cosmo
fontsize: 1.1em
linestretch: 1.7
---
```
Alternatively, adding this to `_quarto.yml` will apply that setting to all pages:
``` yaml
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.
The first appearance (light or dark) elements in the theme to determine the default appearance for your html output. For example, since the `light` option appears first in the above example, a reader will see the light appearance by default.
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).
### 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 >}}