davidbgk
/
larlet-fr-david-cache

<!doctype html><!-- This is a valid HTML5 document. -->
<!-- Screen readers, SEO, extensions and so on. -->
<html lang="fr">
<!-- Has to be within the first 1024 bytes, hence before the `title` element
  See: https://www.w3.org/TR/2012/CR-html5-20121217/document-metadata.html#charset -->
<meta charset="utf-8">
<!-- Why no `X-UA-Compatible` meta: https://stackoverflow.com/a/6771584 -->
<!-- The viewport meta is quite crowded and we are responsible for that.
  See: https://codepen.io/tigt/post/meta-viewport-for-2015 -->
<meta name="viewport" content="width=device-width,initial-scale=1">
<!-- Required to make a valid HTML5 document. -->
<title>Creating a Nice-Looking PDF with pandoc (archive) — David Larlet</title>
<meta name="description" content="Publication mise en cache pour en conserver une trace.">
<!-- That good ol' feed, subscribe :). -->
<link rel="alternate" type="application/atom+xml" title="Feed" href="/david/log/">
<!-- Generated from https://realfavicongenerator.net/ such a mess. -->
<link rel="apple-touch-icon" sizes="180x180" href="/static/david/icons2/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/static/david/icons2/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/static/david/icons2/favicon-16x16.png">
<link rel="manifest" href="/static/david/icons2/site.webmanifest">
<link rel="mask-icon" href="/static/david/icons2/safari-pinned-tab.svg" color="#07486c">
<link rel="shortcut icon" href="/static/david/icons2/favicon.ico">
<meta name="msapplication-TileColor" content="#f7f7f7">
<meta name="msapplication-config" content="/static/david/icons2/browserconfig.xml">
<meta name="theme-color" content="#f7f7f7" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="#272727" media="(prefers-color-scheme: dark)">
<!-- Documented, feel free to shoot an email. -->
<link rel="stylesheet" href="/static/david/css/style_2021-01-20.css">
<!-- See https://www.zachleat.com/web/comprehensive-webfonts/ for the trade-off. -->
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_regular.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_bold.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_italic.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_regular.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_bold.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_italic.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin>
<script>
    function toggleTheme(themeName) {
        document.documentElement.classList.toggle(
            'forced-dark',
            themeName === 'dark'
        )
        document.documentElement.classList.toggle(
            'forced-light',
            themeName === 'light'
        )
    }
    const selectedTheme = localStorage.getItem('theme')
    if (selectedTheme !== 'undefined') {
        toggleTheme(selectedTheme)
    }
</script>

  <meta name="robots" content="noindex, nofollow">
  <meta content="origin-when-cross-origin" name="referrer">
  <!-- Canonical URL for SEO purposes -->
  <link rel="canonical" href="https://plaintextproject.online/articles/2022/04/06/pdf.html">

<body class="remarkdown h1-underline h2-underline h3-underline em-underscore hr-center ul-star pre-tick" data-instant-intensity="viewport-all">


<article>
  <header>
    <h1>Creating a Nice-Looking PDF with pandoc</h1>
  </header>
  <nav>
    <p class="center">
      <a href="/david/" title="Aller à l’accueil"><svg class="icon icon-home">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-home"></use>
      </svg> Accueil</a> •
      <a href="https://plaintextproject.online/articles/2022/04/06/pdf.html" title="Lien vers le contenu original">Source originale</a>
    </p>
  </nav>
  <hr>
  <p>If you’re familiar with <a href="https://pandoc.org" target="_blank">pandoc</a>, you know how useful and flexible it is. One of the many formats that you can convert to using pandoc is PDF.</p>
<p>Before version 2 of the tool, you needed the TeX typesetting system (and the LaTeX extensions) installed on your computer to go directly to PDF. TeX is great, but it’s also quite big. And if you’re only producing the occasional PDF, then it’s overkill to have even a basic TeX system installed on your computer.</p>
<p>With version 2 of pandoc came a new option: <em>–pdf-engine</em>. That option lets you specify which tool to use when doing a conversion to PDF. While you can still use LaTeX (and a few other tools) to do the deed, you don’t need to bother with all that bulk.</p>
<p>Let’s take a look at how to create a PDF from a <a href="https://gum.co/learnmarkdown" target="_blank">Markdown</a> file using pandoc and a couple of lighter-weight utilities.</p>
<h2 id="getting-started">Getting Started</h2>
<p>You’ll need pandoc installed on your computer, along with one of these tools:</p>

<p>For our purposes, WeasyPrint and wkhtmltopdf are essentially the same, but there are a couple or three little differences. I’ll touch on one of those differences in a moment.</p>
<h2 id="doing-the-conversion">Doing the Conversion</h2>
<p>As I mentioned a few paragraphs ago, I’m going to look at how to create a PDF from a file formatted with Markdown. To do that, open a terminal window on your computer. Navigate to the folder containing the file that you want to convert to PDF and then type either:</p>
<p><code>pandoc [file-name].md --pdf-engine=weasyprint -o [file-name].pdf</code></p>
<p>or</p>
<p><code>pandoc [file-name].md --pdf-engine=wkhtmltopdf -o [file-name].pdf</code></p>
<p>Where <em>[file-name].md</em> is the name of the Markdown file that you want to convert.</p>
<p><strong>Note:</strong> Some people add the <em>-t html</em> option to those commands to create an HTML file that WeasyPrint and wkhtmltopdf then convert to PDF. The command also works without that option.</p>
<p>Here’s the result of a conversion using wkhtmltopdf:</p>
<figure>
<img src="https://plaintextproject.online/images/pdf/wkhtmltopdf-conversion.png" alt="Markdown file converted to PDF with wkhtmltopdf">
</figure>
<p>What you get looks pretty much the same when you use WeasyPrint to do the conversion. The result is functional, but it’s not the nice PDF file that I promised you in the title of this article. So let’s look at how to add a bit of visual flair to a PDF generated with pandoc.</p>
<h2 id="enter-print-css">Enter Print CSS</h2>
<p><a href="https://en.wikipedia.org/wiki/CSS" target="_blank">Cascading Style Sheets</a> (CSS for short) is a way to change the look and feel of a web page or website. Print CSS extends that to formatting a web page or website to be printed. It adds support for changing page sizes, adding page breaks, hiding elements that shouldn’t be printed, adding a cover page, and more.</p>
<p>I’m not going to into print CSS in any detail here, because it’s a big topic that my little brain has trouble wrapping itself around. However, I’m not going to leave you hanging. Here are some sources of information that can help you get started with print CSS:</p>

<h2 id="using-print-css-in-a-conversion">Using Print CSS in a Conversion</h2>
<p>Let’s say you’ve crafted your own print CSS file or begged/borrowed one from somewhere. To use it, you’ll need to add the <em>–css=</em> option to the string of options that you use with pandoc.</p>
<p>So, once again, open a terminal window on your computer. Navigate to the folder containing the file that you want to convert to PDF and then type either:</p>
<p><code>pandoc [file-name].md --pdf-engine=weasyprint --css=pdf-styles.css -o [file-name].pdf</code></p>
<p>or</p>
<p><code>pandoc [file-name].md --pdf-engine=wkhtmltopdf --css=pdf-styles.css -V papersize:a5 -o [file-name].pdf</code></p>
<p>Change <em>pdf-styles.css</em> to the name of your print CSS file. Here’s an example the output, via WeasyPrint, from a print CSS file that I use:</p>
<figure>
<img src="https://plaintextproject.online/images/pdf/weasyprint-conversion.png" alt="Markdown file converted to PDF with WeasyPrint">
</figure>
<p>My stylesheet, while fairly basic:</p>
<ul>
<li>Sets the size of the page to <a href="https://papersizes.io/a/a5" target="_blank">A5</a>.</li>
<li>Adds page breaks before every Heading 1.</li>
<li>Creates margins of 1 inch (2.5 cm) all around.</li>
<li>Uses the Overpass font for all text.</li>
</ul>
<p>The first point in the list above is one area in which WeasyPrint and wkhtmltopdf differ. wkhtmltopdf ignores page sizes that you specify in the CSS file. Instead, you need to specify the page size in the conversion command using the option <em>-V papersize:a5</em>.</p>
<p>The examples I’ve included in this article are fairly basic. But, I hope, they’ll help spark a few ideas for converting your documents formatted with Markdown (or another markup language) to PDF using pandoc.</p>
</article>


<hr>

<footer>
  <p>
    <a href="/david/" title="Aller à l’accueil"><svg class="icon icon-home">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-home"></use>
      </svg> Accueil</a> •
    <a href="/david/log/" title="Accès au flux RSS"><svg class="icon icon-rss2">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-rss2"></use>
      </svg> Suivre</a> •
    <a href="http://larlet.com" title="Go to my English profile" data-instant><svg class="icon icon-user-tie">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-user-tie"></use>
      </svg> Pro</a> •
    <a href="mailto:david%40larlet.fr" title="Envoyer un courriel"><svg class="icon icon-mail">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-mail"></use>
      </svg> Email</a> •
    <abbr class="nowrap" title="Hébergeur : Alwaysdata, 62 rue Tiquetonne 75002 Paris, +33184162340"><svg class="icon icon-hammer2">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-hammer2"></use>
      </svg> Légal</abbr>
  </p>
  <template id="theme-selector">
      <form>
          <fieldset>
              <legend><svg class="icon icon-brightness-contrast">
                <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-brightness-contrast"></use>
              </svg> Thème</legend>
              <label>
                  <input type="radio" value="auto" name="chosen-color-scheme" checked> Auto
              </label>
              <label>
                  <input type="radio" value="dark" name="chosen-color-scheme"> Foncé
              </label>
              <label>
                  <input type="radio" value="light" name="chosen-color-scheme"> Clair
              </label>
          </fieldset>
      </form>
  </template>
</footer>
<script src="/static/david/js/instantpage-5.1.0.min.js" type="module"></script>
<script>
    function loadThemeForm(templateName) {
        const themeSelectorTemplate = document.querySelector(templateName)
        const form = themeSelectorTemplate.content.firstElementChild
        themeSelectorTemplate.replaceWith(form)

        form.addEventListener('change', (e) => {
            const chosenColorScheme = e.target.value
            localStorage.setItem('theme', chosenColorScheme)
            toggleTheme(chosenColorScheme)
        })

        const selectedTheme = localStorage.getItem('theme')
        if (selectedTheme && selectedTheme !== 'undefined') {
            form.querySelector(`[value="${selectedTheme}"]`).checked = true
        }
    }

    const prefersColorSchemeDark = '(prefers-color-scheme: dark)'
    window.addEventListener('load', () => {
        let hasDarkRules = false
        for (const styleSheet of Array.from(document.styleSheets)) {
            let mediaRules = []
            for (const cssRule of styleSheet.cssRules) {
                if (cssRule.type !== CSSRule.MEDIA_RULE) {
                    continue
                }
                // WARNING: Safari does not have/supports `conditionText`.
                if (cssRule.conditionText) {
                    if (cssRule.conditionText !== prefersColorSchemeDark) {
                        continue
                    }
                } else {
                    if (cssRule.cssText.startsWith(prefersColorSchemeDark)) {
                        continue
                    }
                }
                mediaRules = mediaRules.concat(Array.from(cssRule.cssRules))
            }

            // WARNING: do not try to insert a Rule to a styleSheet you are
            // currently iterating on, otherwise the browser will be stuck
            // in a infinite loop…
            for (const mediaRule of mediaRules) {
                styleSheet.insertRule(mediaRule.cssText)
                hasDarkRules = true
            }
        }
        if (hasDarkRules) {
            loadThemeForm('#theme-selector')
        }
    })
</script>
</body>
</html>