Skip to content

Dark mode support for HTML output #11831

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jgm merged 1 commit into from
Sep 1, 2026
+125 −44
Merged

Dark mode support for HTML output #11831

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 48 additions & 6 deletions MANUAL.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2937,17 +2937,24 @@ ODT or pptx.
to e.g. `20px`, but it also accepts `pt`
(12pt = 16px in most browsers).

`fontcolor`
`fontcolor`, `fontcolordark`
: sets the CSS `color` property on the `html` element.

`linkcolor`
`linkcolor`, `linkcolordark`
: sets the CSS `color` property on all links.

`quotebordercolor`, `quotebordercolordark`
: sets the CSS `border-color` property for the left-border of
: `blockquote` elements.

`quotecolor`, `quotecolordark`
: sets the CSS `color` property for `blockquote` elements.

`monofont`
: sets the CSS `font-family` property on `code` elements.
: sets the CSS `font-family` property on `code` and `pre` elements.

`monobackgroundcolor`
: sets the CSS `background-color` property on `code` elements
`monobackgroundcolor`, `monobackgroundcolordark`
: sets the CSS `background-color` property on `code` and `pre` elements
and adds extra padding.

`linestretch`
Expand All @@ -2957,7 +2964,7 @@ ODT or pptx.
`maxwidth`
: sets the CSS `max-width` property (default is 36em).

`backgroundcolor`
`backgroundcolor`, `backgroundcolordark`
: sets the CSS `background-color` property on the `html` element.

`margin-left`, `margin-right`, `margin-top`, `margin-bottom`
Expand Down Expand Up @@ -2985,6 +2992,41 @@ To override or extend some [CSS] for just one document, include for example:

[CSS]: https://developer.mozilla.org/en-US/docs/Learn/CSS

#### Note on `color-scheme`

By default, the browser's chosen `color-scheme` (either `light` or `dark`)
will affect the color of various unstyled elements like input fields, which are
generally only applicable if your document is specifically targeting HTML.

By default, Pandoc emits `color-scheme: light dark` to allow the system to
choose between a default light-mode or dark-mode scheme, but it alters this
if variables specifically override colors, under the assumption that the user
wishes for that scheme to always be used.

Currently, this is only per a basic heuristic that checks whether the following
variables are provided:

* `fontcolor`
* `fontcolordark`
* `backgroundcolor`
* `backgroundcolordark`

And if only one "mode" is provided (light or dark), `color-scheme` is set so
that this chosen mode is used always, regardless of the system's preference for
light or dark mode.

Note that there are a few caveats to this, namely that:

* If the browser does not support `light-dark` (older than ~2024), then it will
always choose light mode, regardless of this override.
* When printing, light mode is always chosen, and color variables are ignored.
* Syntax highlighting is currently unaffected by color scheme.

In general, if you wish to override the theming for a single scheme, you should
choose to override either the normal `*color` variables (light mode) or the
`*colordark` variables (dark mode) to ensure that the styles do not conflict
with other styles added by new versions of Pandoc or the browser itself.

Comment thread
clarfonthey marked this conversation as resolved.
### Variables for HTML math

`classoption`
Expand Down
49 changes: 36 additions & 13 deletions data/templates/styles.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,10 @@
line-height: $linestretch$;
$endif$
color: $if(fontcolor)$$fontcolor$$else$#1a1a1a$endif$;
color: light-dark($if(fontcolor)$$fontcolor$$else$#1a1a1a$endif$, $if(fontcolordark)$$fontcolordark$$else$#fdfdfd$endif$);
background-color: $if(backgroundcolor)$$backgroundcolor$$else$#fdfdfd$endif$;
background-color: light-dark($if(backgroundcolor)$$backgroundcolor$$else$#fdfdfd$endif$, $if(backgroundcolordark)$$backgroundcolordark$$else$#1a1a1a$endif$);
color-scheme:$if(fontcolor)$ light$elseif(backgroundcolor)$ light$elseif(fontcolordark)$$elseif(backgroundcolordark)$$else$ light$endif$$if(fontcolordark)$ dark$elseif(backgroundcolordark)$ dark$elseif(fontcolor)$$elseif(backgroundcolor)$$else$ dark$endif$;

@clarfonthey clarfonthey Aug 28, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The way the logic works out, this should always output at least one of the two.

}
body {
margin: 0 auto;
Expand All @@ -38,12 +41,17 @@
}
@media print {
html {
background-color: $if(backgroundcolor)$$backgroundcolor$$else$white$endif$;
color-scheme: light only;
}
body {
html, body, pre, code {
background-color: transparent;
}
body, a, a:visited, blockquote {
color: black;
}
pre, code {
padding: 0;
}
p, h2, h3 {
orphans: 3;
widows: 3;
Expand All @@ -55,11 +63,13 @@
p {
margin: 1em 0;
}
a {
color: $if(linkcolor)$$linkcolor$$else$#1a1a1a$endif$;
}
a:visited {
color: $if(linkcolor)$$linkcolor$$else$#1a1a1a$endif$;
a, a:visited {
color: $if(linkcolor)$$linkcolor$$else$inherit$endif$;
$if(linkcolor)$
color: light-dark($linkcolor$, $if(linkcolordark)$$linkcolordark$$else$inherit$endif$);
$elseif(linkcolordark)$
color: light-dark(inherit, $linkcolordark$);
$endif$
Comment on lines +68 to +72

@clarfonthey clarfonthey Aug 28, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These avoid outputting a redundant light-dark(inherit, inherit).

}
img {
max-width: 100%;
Expand Down Expand Up @@ -88,8 +98,11 @@
blockquote {
margin: 1em 0 1em 1.7em;
padding-left: 1em;
border-left: 2px solid #e6e6e6;
color: #606060;
border-left: 2px solid;
border-color: $if(quotebordercolor)$$quotebordercolor$$else$#e6e6e6$endif$;
border-color: light-dark($if(quotebordercolor)$$quotebordercolor$$else$#e6e6e6$endif$, $if(quotebordercolordark)$$quotebordercolordark$$else$#4c4c4c$endif$);
color: $if(quotecolor)$$quotecolor$$else$#606060$endif$;
color: light-dark($if(quotecolor)$$quotecolor$$else$#606060$endif$, $if(quotecolordark)$$quotecolordark$$else$#b6b6b6$endif$);
}
$if(abstract)$
div.abstract {
Expand All @@ -109,6 +122,11 @@
font-family: $if(monofont)$$monofont$$else$Menlo, Monaco, Consolas, 'Lucida Console', monospace$endif$;
$if(monobackgroundcolor)$
background-color: $monobackgroundcolor$;
background-color: light-dark($monobackgroundcolor$, $if(monobackgroundcolordark)$$monobackgroundcolordark$$else$inherit$endif$);
padding: .2em .4em;
$elseif(monobackgroundcolordark)$
background-color: inherit;
background-color: light-dark(inherit, $monobackgroundcolordark$);
padding: .2em .4em;
$endif$
font-size: 85%;
Expand All @@ -119,6 +137,11 @@
margin: 1em 0;
$if(monobackgroundcolor)$
background-color: $monobackgroundcolor$;
background-color: light-dark($monobackgroundcolor$, $if(monobackgroundcolordark)$$monobackgroundcolordark$$else$inherit$endif$);
padding: 1em;
$elseif(monobackgroundcolordark)$
background-color: inherit;
background-color: light-dark(inherit, $monobackgroundcolordark$);
padding: 1em;
$endif$
overflow: auto;
Expand All @@ -134,7 +157,7 @@
}
hr {
border: none;
border-top: 1px solid #1a1a1a;
border-top: 1px solid currentColor;
height: 1px;
margin: 1em 0;
}
Expand All @@ -156,11 +179,11 @@
}
tbody {
margin-top: 0.5em;
border-top: 1px solid $if(fontcolor)$$fontcolor$$else$#1a1a1a$endif$;
border-bottom: 1px solid $if(fontcolor)$$fontcolor$$else$#1a1a1a$endif$;
border-top: 1px solid currentColor;
border-bottom: 1px solid currentColor;
}
th {
border-top: 1px solid $if(fontcolor)$$fontcolor$$else$#1a1a1a$endif$;
border-top: 1px solid currentColor;
padding: 0.25em 0.5em 0.25em 0.5em;
}
td {
Expand Down
32 changes: 20 additions & 12 deletions test/writer.html4
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,10 @@
*/
html {
color: #1a1a1a;
color: light-dark(#1a1a1a, #fdfdfd);
background-color: #fdfdfd;
background-color: light-dark(#fdfdfd, #1a1a1a);
color-scheme: light dark;
}
body {
margin: 0 auto;
Expand All @@ -39,12 +42,17 @@
}
@media print {
html {
background-color: white;
color-scheme: light only;
}
body {
html, body, pre, code {
background-color: transparent;
}
body, a, a:visited, blockquote {
color: black;
}
pre, code {
padding: 0;
}
p, h2, h3 {
orphans: 3;
widows: 3;
Expand All @@ -56,11 +64,8 @@
p {
margin: 1em 0;
}
a {
color: #1a1a1a;
}
a:visited {
color: #1a1a1a;
a, a:visited {
color: inherit;
}
img {
max-width: 100%;
Expand Down Expand Up @@ -89,8 +94,11 @@
blockquote {
margin: 1em 0 1em 1.7em;
padding-left: 1em;
border-left: 2px solid #e6e6e6;
border-left: 2px solid;
border-color: #e6e6e6;
border-color: light-dark(#e6e6e6, #4c4c4c);
color: #606060;
color: light-dark(#606060, #b6b6b6);
}
code {
white-space: pre-wrap;
Expand All @@ -114,7 +122,7 @@
}
hr {
border: none;
border-top: 1px solid #1a1a1a;
border-top: 1px solid currentColor;
height: 1px;
margin: 1em 0;
}
Expand All @@ -131,11 +139,11 @@
}
tbody {
margin-top: 0.5em;
border-top: 1px solid #1a1a1a;
border-bottom: 1px solid #1a1a1a;
border-top: 1px solid currentColor;
border-bottom: 1px solid currentColor;
}
th {
border-top: 1px solid #1a1a1a;
border-top: 1px solid currentColor;
padding: 0.25em 0.5em 0.25em 0.5em;
}
td {
Expand Down
32 changes: 20 additions & 12 deletions test/writer.html5
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,10 @@
*/
html {
color: #1a1a1a;
color: light-dark(#1a1a1a, #fdfdfd);
background-color: #fdfdfd;
background-color: light-dark(#fdfdfd, #1a1a1a);
color-scheme: light dark;
}
body {
margin: 0 auto;
Expand All @@ -39,12 +42,17 @@
}
@media print {
html {
background-color: white;
color-scheme: light only;
}
body {
html, body, pre, code {
background-color: transparent;
}
body, a, a:visited, blockquote {
color: black;
}
pre, code {
padding: 0;
}
p, h2, h3 {
orphans: 3;
widows: 3;
Expand All @@ -56,11 +64,8 @@
p {
margin: 1em 0;
}
a {
color: #1a1a1a;
}
a:visited {
color: #1a1a1a;
a, a:visited {
color: inherit;
}
img {
max-width: 100%;
Expand Down Expand Up @@ -89,8 +94,11 @@
blockquote {
margin: 1em 0 1em 1.7em;
padding-left: 1em;
border-left: 2px solid #e6e6e6;
border-left: 2px solid;
border-color: #e6e6e6;
border-color: light-dark(#e6e6e6, #4c4c4c);
color: #606060;
color: light-dark(#606060, #b6b6b6);
}
code {
white-space: pre-wrap;
Expand All @@ -114,7 +122,7 @@
}
hr {
border: none;
border-top: 1px solid #1a1a1a;
border-top: 1px solid currentColor;
height: 1px;
margin: 1em 0;
}
Expand All @@ -131,11 +139,11 @@
}
tbody {
margin-top: 0.5em;
border-top: 1px solid #1a1a1a;
border-bottom: 1px solid #1a1a1a;
border-top: 1px solid currentColor;
border-bottom: 1px solid currentColor;
}
th {
border-top: 1px solid #1a1a1a;
border-top: 1px solid currentColor;
padding: 0.25em 0.5em 0.25em 0.5em;
}
td {
Expand Down
2 changes: 1 addition & 1 deletion wasm/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -318,7 +318,7 @@ window.pandocApp = function() {
// Template variables by category
templateVariablesByCategory: {
all: ['title', 'author', 'date', 'subtitle', 'abstract', 'abstract-title', 'keywords', 'subject', 'description', 'category', 'lang', 'dir', 'header-includes', 'include-before', 'include-after', 'toc-title'],
html: ['document-css', 'mainfont', 'fontsize', 'fontcolor', 'linkcolor', 'monofont', 'monobackgroundcolor', 'linestretch', 'maxwidth', 'backgroundcolor', 'margin-left', 'margin-right', 'margin-top', 'margin-bottom'],
html: ['document-css', 'mainfont', 'fontsize', 'fontcolor', 'fontcolordark', 'linkcolor', 'linkcolordark', 'quotebordercolor', 'quotebordercolordark', 'quotecolor', 'quotecolordark', 'monofont', 'monobackgroundcolor', 'monobackgroundcolordark', 'linestretch', 'maxwidth', 'backgroundcolor', 'backgroundcolordark', 'margin-left', 'margin-right', 'margin-top', 'margin-bottom'],
htmlSlides: ['institute', 'revealjs-url', 's5-url', 'slidy-url', 'slideous-url', 'title-slide-attributes'],
beamer: ['aspectratio', 'beameroption', 'institute', 'logo', 'navigation', 'section-titles', 'theme', 'colortheme', 'fonttheme', 'innertheme', 'outertheme', 'themeoptions', 'titlegraphic'],
latex: ['block-headings', 'classoption', 'documentclass', 'geometry', 'hyperrefoptions', 'indent', 'linestretch', 'margin-left', 'margin-right', 'margin-top', 'margin-bottom', 'pagestyle', 'papersize', 'secnumdepth', 'fontenc', 'fontfamily', 'fontfamilyoptions', 'fontsize', 'mainfont', 'sansfont', 'monofont', 'mathfont', 'CJKmainfont', 'mainfontoptions', 'sansfontoptions', 'monofontoptions', 'colorlinks', 'linkcolor', 'filecolor', 'citecolor', 'urlcolor', 'toccolor', 'links-as-notes', 'lof', 'lot', 'thanks', 'toc-depth', 'biblatexoptions', 'biblio-style', 'biblio-title', 'natbiboptions'],
Expand Down