pandoc-markdown-css-theme/docs/index.html at master · jez/pandoc-markdown-css-theme · GitHub

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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc-markdown-css-theme" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <meta name="author" content="@jez" />
  <meta name="dcterms.date" content="2021-06-20" />
  <title>Pandoc Markdown CSS Theme</title>
  <link rel="stylesheet" href="css/theme.css" />
  <link rel="stylesheet" href="css/skylighting-solarized-theme.css" />
  <script defer="" src="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.js"></script>
  <script>document.addEventListener("DOMContentLoaded", function () {
 var mathElements = document.getElementsByClassName("math");
 var macros = [];
 for (var i = 0; i < mathElements.length; i++) {
  var texText = mathElements[i].firstChild;
  if (mathElements[i].tagName == "SPAN") {
   katex.render(texText.data, mathElements[i], {
    displayMode: mathElements[i].classList.contains('display'),
    throwOnError: false,
    macros: macros,
    fleqn: false
   });
}}});
  </script>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.css" />
</head>
<body>

<header>
<h1 class="title">Pandoc Markdown CSS Theme</h1>
<blockquote class="metadata">
<p class="subtitle">Starter files for generating HTML from Pandoc Markdown</p>
<p class="author">
      <a href="https://github.com/jez"><span class="citation" data-cites="jez">@jez</span></a>
  </p>
<p class="date before-toc"><time datetime="2021-06-20">2021-06-20</time></p>
</blockquote>
</header>

<nav id="TOC" role="doc-toc">
    <strong>Contents</strong><label for="contents">⊕</label>
  <input type="checkbox" id="contents">
  <ul>
  <li><a href="#features" id="toc-features">Features</a></li>
  <li><a href="#usage" id="toc-usage">Usage</a>
  <ul>
  <li><a href="#usage-with-jekyll" id="toc-usage-with-jekyll">Usage with Jekyll</a></li>
  </ul></li>
  <li><a href="#credits" id="toc-credits">Credits</a></li>
  <li><a href="#see-also" id="toc-see-also">See also</a></li>
  </ul>
</nav>

<main>
<p>This project provides CSS files and a template for using Pandoc<span class="sidenote-wrapper"><label for="sn-0" class="margin-toggle">&#8853;</label><input type="checkbox" id="sn-0" class="margin-toggle"/><span class="marginnote"><a href="https://pandoc.org/">Pandoc</a> is a “universal document converter.” It is particularly good at generating HTML and <span class="math inline">\LaTeX</span> from Markdown.<br />
<br />
</span></span> to generate standalone HTML files. It supports most features Pandoc Markdown has to offer, and some extras. The default look can be tweaked via CSS variables, and it does not require JavaScript, even for side notes.</p>
<h1 id="features">Features</h1>
<p>A short list of headline features:</p>
<ul>
<li><a href="features/#code-blocks">Code blocks</a>, including:
<ul>
<li>Syntax themes</li>
<li>Line numbers and line highlights</li>
<li>Extra wide and full-width options</li>
<li>Captions</li>
</ul></li>
<li><a href="features/#images-tables-and-captioned-code-blocks">Images and tables</a>, including:
<ul>
<li>Extra wide and full-width options</li>
<li>Captions</li>
</ul></li>
<li><a href="features/#side-notes-and-margin-notes">Side notes and margin notes</a></li>
<li><a href="features/#table-of-contents">Floating table of contents</a></li>
<li><a href="features/#math"><span class="math inline">\LaTeX</span> math</a>, rendered via <a href="https://katex.org/"><span class="math inline">\KaTeX</span></a> in the browser</li>
<li>Dark mode, based on the user’s default color scheme preference</li>
</ul>
<p>For the complete feature set, see the documentation. You might also want to view the “kitchen sink” page that is useful when developing, or the source code:</p>
<p><a href="features/">→ Documentation</a><br />
<a href="kitchen-sink/">→ Kitchen Sink</a><br />
<a href="https://github.com/jez/pandoc-markdown-css-theme">→ Source on GitHub</a></p>
<p>The theme is fully responsive, including phones, tablets, laptops, and wide desktop screens. Side notes and the table of contents display inline on small screen sizes, and in the margins on wide enough screens. Extra wide images, tables, and code blocks shrink when space isn’t available. CSS <code>@media print</code> styles declare first-class print styles.</p>
<div class="wide extra-wide only-light-mode">
<figure>
<img src="img/light-mobile-responsive.png" alt="Only right margin at tablet width, and no margins on mobile" />
<figcaption aria-hidden="true">Only right margin at tablet width, and no margins on mobile</figcaption>
</figure>
</div>
<div class="wide extra-wide only-dark-mode">
<figure>
<img src="img/dark-mobile-responsive.png" alt="Only right margin at tablet width, and no margins on mobile" />
<figcaption aria-hidden="true">Only right margin at tablet width, and no margins on mobile</figcaption>
</figure>
</div>
<p>The source code is extremely tweakable.<span class="sidenote-wrapper"><label for="sn-1" class="margin-toggle">&#8853;</label><input type="checkbox" id="sn-1" class="margin-toggle"/><span class="marginnote">When changing things like the font family or font size, the thing that matters is to pay special attention to alignment. Different fonts have different x-heights and widths. Most layouting can be agnostic of these things, but there are explicit variables for places where it matters.<br />
<br />
</span></span> A small set of CSS variables control a large number of font and color settings: you don’t have to hunt down all the places that need to be changed to tweak the design. As a proof of concept, see <a href="paper/">this page</a>, which tweaks the default theme slightly. These same CSS variables power the light- and dark-mode versions of the theme. Of course, the code is open source and you’re welcome to copy the theme files and completely overhaul them if desired.</p>
<p>And finally, there’s basically only HTML and CSS. The theme doesn’t use custom fonts by default, and only uses JavaScript for three things:</p>
<ul>
<li>Rendering math (via <a href="https://katex.org/"><span class="math inline">\KaTeX</span></a>), only if used.</li>
<li>Slightly tweaking the appearance of checklist items. (Pandoc emits them as disabled, but they look better when enabled in my opinion.) This is entirely presentational.</li>
<li>Progressively enhance the location of certain margin notes on mobile. See <a href="features/#TODO">the docs</a> for more, but know that even without this bit of JavaScript, side notes are still readable and interactive on all platforms.</li>
</ul>
<p>Default placement of side notes, the table of contents, and code block line highlights are all controlled with CSS. See the <a href="#credits">credits</a> below for more background on the techniques used.</p>
<h1 id="usage">Usage</h1>
<p>This project merely provides a CSS files and a standalone HTML template to give to Pandoc. The important files that you might want to copy out to start your own project:</p>
<ul>
<li><a href="https://github.com/jez/pandoc-markdown-css-theme/blob/master/public/css/theme.css"><code>public/css/theme.css</code></a>, the core CSS implementing theme</li>
<li><a href="https://github.com/jez/pandoc-markdown-css-theme/blob/master/template.html5"><code>template.html5</code></a>, the Pandoc template that renders Markdown to HTML</li>
<li><a href="https://github.com/jez/pandoc-markdown-css-theme/blob/master/Makefile"><code>Makefile</code></a>, showcasing the Pandoc flags required to get things to build</li>
<li><a href="https://github.com/jez/pandoc-markdown-css-theme/blob/master/src/index.md"><code>src/index.md</code></a>, the source code for this page</li>
</ul>
<p>To see things in action, try rebuilding this site locally. First, you’ll need a few command line programs:</p>
<ul class="task-list">
<li><label><input type="checkbox" /><a href="https://pandoc.org/">Pandoc</a></label></li>
<li><label><input type="checkbox" /><a href="https://github.com/jez/pandoc-sidenote"><code>pandoc-sidenote</code></a></label></li>
<li><label><input type="checkbox" /><code>realpath</code> from <a href="https://www.gnu.org/software/coreutils/coreutils.html">GNU coreutils</a></label></li>
<li><label><input type="checkbox" />(optional) <a href="https://facebook.github.io/watchman/"><code>watchman</code></a>, for rebuilding when files change</label></li>
</ul>
<p>Follow the installation instructions for your platform. If you’re using macOS, installation is as easy as:</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode numberSource numberLines"><code class="sourceCode"><span id="cb1-1"><a href="#cb1-1"></a>brew install pandoc coreutils</span>
<span id="cb1-2"><a href="#cb1-2"></a></span>
<span id="cb1-3"><a href="#cb1-3"></a>curl --remote-name --no-clobber --create-dirs \</span>
<span id="cb1-4"><a href="#cb1-4"></a>  --output-dir &quot;${XDG_DATA_DIR:-$HOME/.local/share/}/pandoc/filters&quot; \</span>
<span id="cb1-5"><a href="#cb1-5"></a>  -sSL &quot;https://github.com/jez/pandoc-sidenote/raw/refs/heads/master/pandoc-sidenote.lua&quot;</span></code></pre></div>
<p>Then you can clone this project and run <code>make watch</code>:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode numberSource bash numberLines hl-7 hl-10"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1"></a><span class="fu">git</span> clone https://github.com/jez/pandoc-markdown-css-theme</span>
<span id="cb2-2"><a href="#cb2-2"></a><span class="bu">cd</span> pandoc-markdown-css-theme</span>
<span id="cb2-3"><a href="#cb2-3"></a></span>
<span id="cb2-4"><a href="#cb2-4"></a><span class="co"># Test everything by forcing a clean build</span></span>
<span id="cb2-5"><a href="#cb2-5"></a><span class="co"># (the generated comes with the clone)</span></span>
<span id="cb2-6"><a href="#cb2-6"></a><span class="fu">make</span> clean</span>
<span id="cb2-7"><a href="#cb2-7"></a><span class="fu">make</span></span>
<span id="cb2-8"><a href="#cb2-8"></a></span>
<span id="cb2-9"><a href="#cb2-9"></a><span class="co"># If you installed watchman</span></span>
<span id="cb2-10"><a href="#cb2-10"></a><span class="fu">make</span> watch</span></code></pre></div>
<p>Running <code>make</code> will build everything in the site.</p>
<p>Running <code>make watch</code> will start a webserver at <a href="http://127.0.0.1:8000/" class="uri">http://127.0.0.1:8000/</a>, open that URL in a web browser, and watch files for changes in the background.</p>
<h2 id="usage-with-jekyll">Usage with Jekyll</h2>
<p>While the core theme is just a handful of static files that can be copied into any project, using this theme with <a href="https://jekyllrb.com">Jekyll</a> is as easy as installing a theme:</p>
<p>→ <a href="https://github.com/jez/pandoc-markdown-jekyll-theme">Pandoc Markdown Jekyll Theme</a></p>
<p>Check the project above for installation and usage instructions with Jekyll.</p>
<h1 id="credits">Credits</h1>
<p>First, thanks to <a href="https://pandoc.org/">Pandoc</a>, by John MacFarlane, for being an all-around awesome tool, especially for Markdown.</p>
<p>The core technique for laying out side notes<span class="sidenote-wrapper"><label for="sn-2" class="margin-toggle">&#8853;</label><input type="checkbox" id="sn-2" class="margin-toggle"/><span class="marginnote">Gwern has a great survey post that discusses <a href="https://www.gwern.net/Sidenotes">Sidenotes In Web Design</a>, covering the techniques in Tufte CSS as well as the limitations, and many alternatives.<br />
<br />
</span></span> I learned from <a href="https://edwardtufte.github.io/tufte-css/">Tufte CSS</a>, by Dave Liepmann. The technique is <a href="https://edwardtufte.github.io/tufte-css/#sidenotes">described in detail here</a>. Tufte CSS suggests writing the HTML for sidenotes by hand, but I wanted to use Markdown. I wrote <a href="https://github.com/jez/pandoc-sidenote"><code>pandoc-sidenote</code></a>, a <a href="https://pandoc.org/filters.html">Pandoc filter</a> that traverses Pandoc’s internal AST and converts footnote nodes into the HTML side note markup for Tufte CSS-style side notes.</p>
<p>While the idea for side notes comes entirely from Tufte CSS, the implementation at this point is almost completely different. Tufte CSS uses relative widths everywhere, but I wanted a body with a constant width at all but the smallest screen sizes. Tufte CSS renders the main body off center. Rendering centered when possible and off center when not adds complexity in the implementation.</p>
<p>The inspiration for code block line highlights comes from a change I contributed to <a href="https://github.com/owickstrom/pandoc-emphasize-code"><code>pandoc-emphasize-code</code></a>, by Oskar Wickström (another Pandoc filter). I decided against using it for this project because it forces a choice of either line highlights or syntax highlighting per code block (unless you tack on a JavaScript-based syntax highlighter, like Highlight.js). I thought of a <a href="features/#line-highlight-limit">clever technique</a> using CSS clases to avoid this.</p>
<p>Considerable design inspiration comes from <a href="https://www.dropbox.com/paper">Dropbox Paper</a>, a gorgeous and powerful tool. (In fact, the theme is customizable enough to <a href="paper/">recreate the look of Paper</a>. This is provided for educational purposes only, under Fair Use.)</p>
<h1 id="see-also">See also</h1>
<p>If you’d like to use Tufte CSS with Pandoc in your own project, feel free to use my <a href="https://jez.io/tufte-pandoc-css/">Tufte Pandoc CSS</a> project.</p>
<p>If you’d like to use this theme in a Jekyll project, I have already packaged these files as a Jekyll theme: <a href="https://github.com/jez/pandoc-markdown-jekyll-theme"><code>pandoc-markdown-jekyll-theme</code></a>.</p>
<p><a href="https://github.com/jez/pandoc-markdown-css-theme" class="github-corner" aria-label="View source on GitHub"><svg width="80" height="80" viewBox="0 0 250 250" style="fill:#151513; color:#fff; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true"><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a><style>.github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}<span class="citation" data-cites="keyframes">@keyframes</span> octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}<span class="citation" data-cites="media">@media</span> (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}</style></p>
<p class="signoff">
<a href="/">↑ Back to the top</a>
</p>
</main>

<script>
;(function() {
  // Non-essential if user has JavaScript off. Just makes checkboxes look nicer.
  var selector = '.task-list > li > input[type="checkbox"]';
  var checkboxes = document.querySelectorAll(selector);
  Array.from(checkboxes).forEach((checkbox) => {
    var wasChecked = checkbox.checked;
    checkbox.disabled = false;
    checkbox.addEventListener('click', (ev) => {ev.target.checked = wasChecked});
  });

  function hoistAbove() {
    const toHoist = document.querySelectorAll('main > .sidenote-wrapper + :not(.sidenote-wrapper)');
    for (let i = toHoist.length - 1; i >= 0; i--) {
      const source = toHoist[i];
      let target = source.previousElementSibling;
      while (target.previousElementSibling?.classList.contains('sidenote-wrapper')) {
        target = target.previousElementSibling;
      }
      source.parentNode.insertBefore(source, target);
    }
  }

  function sinkBelow() {
    const toHoist = document.querySelectorAll('main > :not(.sidenote-wrapper) + .sidenote-wrapper');
    for (let i = 0; i < toHoist.length; i++) {
      const source = toHoist[i].previousElementSibling;
      let target = source.nextElementSibling;
      while (target.classList.contains('sidenote-wrapper')) {
        target = target.nextElementSibling;
      }
      source.parentNode.insertBefore(source, target);
    }
  }

  if (window.matchMedia('screen')) {
    if (window.innerWidth <= 796) {
      hoistAbove();
    }
    let prevSize = window.innerWidth;
    // Needs to mirror breakpoints in :root settings in CSS variables
    // 745px = --main-width-narrow
    // 26px = --line-height
    // 169px = side note min width narrow
    const breakpoint = 26 + 550 + 26 + 169 + 26 - 1;
    window.addEventListener('resize', function() {
      const newSize = window.innerWidth;
      if (prevSize >= breakpoint && newSize < breakpoint) {
        hoistAbove();
      } else if (prevSize < breakpoint && newSize >= breakpoint) {
        sinkBelow();
      }
      prevSize = newSize;
    });
  }
})();
</script>
</body>
</html>