-
Notifications
You must be signed in to change notification settings - Fork 35
/
Copy pathindex.html
84 lines (84 loc) · 32.8 KB
/
index.html
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
<!doctype html><html lang=en><head><meta content="IE=edge" http-equiv=X-UA-Compatible><meta content="text/html; charset=utf-8" http-equiv=content-type><meta content="width=device-width,initial-scale=1.0,maximum-scale=1" name=viewport><title>Customizing pandoc to generate beautiful pdf and epub from markdown</title><link href=https://learnbyexample.github.io/atom.xml rel=alternate title=RSS type=application/atom+xml><script src=https://cdnjs.cloudflare.com/ajax/libs/slideout/1.0.1/slideout.min.js></script><link href=https://learnbyexample.github.io/site.css rel=stylesheet><meta content="Customizing pandoc to generate beautiful pdf and epub from markdown" property=og:title><meta content=website property=og:type><meta content="This tutorial shows how to customize pandoc to generate PDF and EPUB from GitHub style markdown." property=og:description><meta content=https://learnbyexample.github.io/customizing-pandoc/ property=og:url><meta content=https://learnbyexample.github.io/images/pandoc_pdf/customizing_pandoc.png property=og:image><meta content=1280 property=og:image:width><meta content=640 property=og:image:height><meta content=summary_large_image property=twitter:card><meta content=@learn_byexample property=twitter:site><link href=https://learnbyexample.github.io/favicon.svg rel=icon><link rel="shortcut icon" href=https://learnbyexample.github.io/favicon.png><body><div class=container><div class=mobile-navbar id=mobile-navbar><div class=mobile-header-logo><a class=logo href=/>learnbyexample</a></div><div class="mobile-navbar-icon icon-out"><span></span><span></span><span></span></div></div><nav class="mobile-menu slideout-menu slideout-menu-left" id=mobile-menu><ul class=mobile-menu-list><li class=mobile-menu-item><a href=https://learnbyexample.github.io/books> Books </a><li class=mobile-menu-item><a href=https://learnbyexample.github.io/mini> Mini </a><li class=mobile-menu-item><a href=https://learnbyexample.github.io/tips> Tips </a><li class=mobile-menu-item><a href=https://learnbyexample.github.io/tags> Tags </a><li class=mobile-menu-item><a href=https://learnbyexample.github.io/about> About </a></ul></nav><header id=header><div class=logo><a href=https://learnbyexample.github.io>learnbyexample</a></div><nav class=menu><ul><li><a href=https://learnbyexample.github.io/books> Books </a><li><a href=https://learnbyexample.github.io/mini> Mini </a><li><a href=https://learnbyexample.github.io/tips> Tips </a><li><a href=https://learnbyexample.github.io/tags> Tags </a><li><a href=https://learnbyexample.github.io/about> About </a></ul></nav></header><main><div class=content id=mobile-panel><div class=post-toc id=post-toc><h2 class=post-toc-title>Contents</h2><div class="post-toc-content always-active"><nav id=TableOfContents><ul><li><a class=toc-link href=https://learnbyexample.github.io/customizing-pandoc/#installation>Installation</a><li><a class=toc-link href=https://learnbyexample.github.io/customizing-pandoc/#minimal-example>Minimal example</a><li><a class=toc-link href=https://learnbyexample.github.io/customizing-pandoc/#chapter-breaks>Chapter breaks</a><li><a class=toc-link href=https://learnbyexample.github.io/customizing-pandoc/#changing-settings-via-v-option>Changing settings via -V option</a><li><a class=toc-link href=https://learnbyexample.github.io/customizing-pandoc/#syntax-highlighting>Syntax highlighting</a><li><a class=toc-link href=https://learnbyexample.github.io/customizing-pandoc/#bullet-styling>Bullet styling</a><li><a class=toc-link href=https://learnbyexample.github.io/customizing-pandoc/#pdf-properties>PDF properties</a><li><a class=toc-link href=https://learnbyexample.github.io/customizing-pandoc/#adding-table-of-contents>Adding table of contents</a><li><a class=toc-link href=https://learnbyexample.github.io/customizing-pandoc/#adding-cover-image>Adding cover image</a><li><a class=toc-link href=https://learnbyexample.github.io/customizing-pandoc/#stylish-blockquote>Stylish blockquote</a><li><a class=toc-link href=https://learnbyexample.github.io/customizing-pandoc/#customizing-epub>Customizing epub</a><li><a class=toc-link href=https://learnbyexample.github.io/customizing-pandoc/#resource-links>Resource links</a></ul></nav></div></div><article class=post><header class=post__header><h1 class=post__title><a href=https://learnbyexample.github.io/customizing-pandoc/>Customizing pandoc to generate beautiful pdf and epub from markdown</a></h1><div class=post__meta><span class=post__time>2020-07-21</span></div></header><div class=post-content><p>Either you've already heard of <code>pandoc</code> or if you have searched online for <code>markdown</code> to <code>pdf</code> or similar, you are sure to come across <code>pandoc</code>. This tutorial will help you use <code>pandoc</code> to generate <code>pdf</code> and <code>epub</code> from a <a href=https://github.github.com/gfm/>GitHub style markdown</a> file. The main motivation for this blog post is to highlight what customizations I did to generate <code>pdf</code> and <code>epub</code> versions for <a href=https://learnbyexample.github.io/books/>self-publishing my ebooks</a>. It wasn't easy to arrive at the setup I ended up with, so I hope this will be useful for those looking to use <code>pandoc</code> to generate <code>pdf</code> and <code>epub</code> formats. This guide is specifically aimed at technical books that has code snippets.<p align=center><img alt="Customizing pandoc" loading=lazy src=/images/pandoc_pdf/customizing_pandoc.png><p align=center><i>Poster created using <a href=https://www.canva.com/>Canva</a></i></p><span id=continue-reading></span><br><h2 id=installation>Installation<a aria-label="Anchor link for: installation" class=zola-anchor href=#installation>🔗</a></h2><p>If you use a debian based distro like Ubuntu, the below steps are enough for the demos in this tutorial. If you get an error or warning, search that issue online and you'll likely find what else has to be installed.<p>I first downloaded <code>deb</code> file from <a href=https://github.com/jgm/pandoc/releases>pandoc: releases</a> and installed it. Followed by packages needed for <code>pdf</code> generation.<pre class=language-bash data-lang=bash style=background-color:#f5f5f5;color:#1f1f1f;><code class=language-bash data-lang=bash><span style=color:#5597d6;>$ </span><span style=color:#7f8989;># latest pandoc version as of 27 Aug 2021 is 2.14.2
</span><span style=color:#5597d6;>$</span><span> sudo gdebi </span><span style=color:#5597d6;>~</span><span>/Downloads/pandoc-2.14.2-1-amd64.deb
</span><span>
</span><span style=color:#5597d6;>$ </span><span style=color:#7f8989;># note that download size is hundreds of MB
</span><span style=color:#5597d6;>$</span><span> sudo apt install texlive-xetex
</span><span style=color:#5597d6;>$</span><span> sudo apt install librsvg2-bin
</span><span style=color:#5597d6;>$</span><span> sudo apt install texlive-science
</span></code></pre><p>For more details and guide for other OS, refer to <a href=https://pandoc.org/installing.html>pandoc: installation</a></p><br><h2 id=minimal-example>Minimal example<a aria-label="Anchor link for: minimal-example" class=zola-anchor href=#minimal-example>🔗</a></h2><p>Once <code>pandoc</code> is working on your system, try generating a sample <code>pdf</code> without any customization.<p><img alt=info src=/images/info.svg> See <a href=https://github.com/learnbyexample/learnbyexample.github.io/tree/master/files/pandoc_pdf>learnbyexample.github.io repo</a> for all the input and output files referred in this tutorial.<pre class=language-bash data-lang=bash style=background-color:#f5f5f5;color:#1f1f1f;><code class=language-bash data-lang=bash><span style=color:#5597d6;>$</span><span> pandoc sample_1.md</span><span style=color:#5597d6;> -f</span><span> gfm</span><span style=color:#5597d6;> -o</span><span> sample_1.pdf
</span></code></pre><p>Here <code>sample_1.md</code> is input markdown file and <code>-f</code> is used to specify that the input format is GitHub style markdown. The <code>-o</code> option specifies the output file type based on extension. The default output is probably good enough. But I wished to customize hyperlinks, inline code style, add page breaks between chapters, etc. This blog post will discuss these customizations one by one.<p><img alt=info src=/images/info.svg> <code>pandoc</code> has its own flavor of <code>markdown</code> with many useful extensions — see <a href=https://pandoc.org/MANUAL.html#pandocs-markdown>pandoc: pandocs-markdown</a> for details. GitHub style markdown is recommended if you wish to use the same source (or with minor changes) in multiple places.<p><img alt=info src=/images/info.svg> It is advised to use <code>markdown</code> headers in order without skipping — for example, <code>H1</code> for chapter heading and <code>H2</code> for chapter sub-section, etc is fine. <code>H1</code> for chapter heading and <code>H3</code> for sub-section is not. Using the former can give automatic index navigation on ebook readers.<p>On <a href=https://wiki.gnome.org/Apps/Evince>Evince</a> reader, the index navigation for above sample looks like this:<p align=center><img alt="index navigation" loading=lazy src=/images/pandoc_pdf/chapter_index.png></p><br><h2 id=chapter-breaks>Chapter breaks<a aria-label="Anchor link for: chapter-breaks" class=zola-anchor href=#chapter-breaks>🔗</a></h2><p>As observed from previous demo, by default there are no chapter breaks. Searching for a <a href=https://superuser.com/questions/601469/getting-chapters-to-start-on-a-new-page-in-a-pandoc-generated-pdf>solution online</a>, I got this piece of <code>tex</code> code:<pre class=language-latex data-lang=latex style=background-color:#f5f5f5;color:#1f1f1f;><code class=language-latex data-lang=latex><span style=color:#72ab00;>\usepackage</span><span>{</span><span style=color:#a2a001;>sectsty</span><span>}
</span><span style=color:#b39f04;>\sectionfont</span><span>{</span><span style=color:#b39f04;>\clearpage</span><span>}
</span></code></pre><p>This can be added using <code>-H</code> option. From <code>pandoc</code> manual,<blockquote><p>-H FILE, --include-in-header=FILE<p>Include contents of FILE, verbatim, at the end of the header. This can be used, for example, to include special CSS or JavaScript in HTML documents. This option can be used repeatedly to include multiple files in the header. They will be included in the order specified. Implies --standalone.</blockquote><p>The <code>pandoc</code> invocation now looks like:<pre class=language-bash data-lang=bash style=background-color:#f5f5f5;color:#1f1f1f;><code class=language-bash data-lang=bash><span style=color:#5597d6;>$</span><span> pandoc sample_1.md</span><span style=color:#5597d6;> -f</span><span> gfm</span><span style=color:#5597d6;> -H</span><span> chapter_break.tex</span><span style=color:#5597d6;> -o</span><span> sample_1_chapter_break.pdf
</span></code></pre><p>You can add further customization to headings, for example:<ul><li><code>\sectionfont{\underline\clearpage}</code> to underline chapter names<li><code>\sectionfont{\LARGE\clearpage}</code> to allow chapter names to get even bigger</ul><p>Here are some more links to read about various customizations:<ul><li><a href=https://tex.stackexchange.com/questions/1455/how-to-set-the-font-for-a-section-title-and-chapter-etc>tex.stackexchange: section fonts</a><li><a href=https://tex.stackexchange.com/questions/230730/section-coming-up-as-undefined-when-using-sectsty>tex.stackexchange: section colors</a><li><a href=https://tex.stackexchange.com/questions/10138/change-section-fonts>tex.stackexchange: change section fonts</a></ul><br><h2 id=changing-settings-via-v-option>Changing settings via -V option<a aria-label="Anchor link for: changing-settings-via-v-option" class=zola-anchor href=#changing-settings-via-v-option>🔗</a></h2><blockquote><p>-V KEY[=VAL], --variable=KEY[:VAL]<p>Set the template variable KEY to the value VAL when rendering the document in standalone mode. This is generally only useful when the --template option is used to specify a custom template, since pandoc automatically sets the variables used in the default templates. If no VAL is specified, the key will be given the value true.</blockquote><p>The <code>-V</code> option allows to change variable values to customize settings like page size, font, link color, etc. As more settings are changed, better to use a simple script to call <code>pandoc</code> instead of typing the whole command on terminal.<pre class=language-bash data-lang=bash style=background-color:#f5f5f5;color:#1f1f1f;><code class=language-bash data-lang=bash><span style=color:#7f8989;>#!/bin/bash
</span><span>
</span><span style=color:#5597d6;>pandoc </span><span style=color:#d07711;>"$</span><span style=color:#acb3c2;>1</span><span style=color:#d07711;>" </span><span>\
</span><span style=color:#5597d6;> -f</span><span> gfm \
</span><span style=color:#5597d6;> --include-in-header</span><span> chapter_break.tex \
</span><span style=color:#5597d6;> -V</span><span> linkcolor:blue \
</span><span style=color:#5597d6;> -V</span><span> geometry:a4paper \
</span><span style=color:#5597d6;> -V</span><span> geometry:margin=2cm \
</span><span style=color:#5597d6;> -V</span><span> mainfont=</span><span style=color:#d07711;>"DejaVu Serif" </span><span>\
</span><span style=color:#5597d6;> -V</span><span> monofont=</span><span style=color:#d07711;>"DejaVu Sans Mono" </span><span>\
</span><span style=color:#5597d6;> --pdf-engine</span><span style=color:#72ab00;>=</span><span>xelatex \
</span><span style=color:#5597d6;> -o </span><span style=color:#d07711;>"$</span><span style=color:#acb3c2;>2</span><span style=color:#d07711;>"
</span></code></pre><ul><li><code>mainfont</code> is for normal text<li><code>monofont</code> is for code snippets<li><code>geometry</code> for page size and margins<li><code>linkcolor</code> to set hyperlink color<li>to increase default <strong>font size</strong>, use <code>-V fontsize=12pt</code> <ul><li>See <a href=https://stackoverflow.com/q/23811002/4082052>stackoverflow: change font size</a> if you need even bigger size options</ul></ul><p>Using <code>xelatex</code> as the <code>pdf-engine</code> allows to use any font installed in the system. One reason I chose <code>DejaVu</code> was because it supported <strong>Greek</strong> and other Unicode characters that were causing error with other fonts. See <a href=https://tex.stackexchange.com/questions/21736/using-xelatex-instead-of-pdflatex>tex.stackexchange: Using XeLaTeX instead of pdfLaTeX</a> for some more details.<p>The <code>pandoc</code> invocation is now through a script:<pre class=language-bash data-lang=bash style=background-color:#f5f5f5;color:#1f1f1f;><code class=language-bash data-lang=bash><span style=color:#5597d6;>$</span><span> chmod +x md2pdf.sh
</span><span style=color:#5597d6;>$</span><span> ./md2pdf.sh sample_1.md sample_1_settings.pdf
</span></code></pre><p>Do compare the pdf generated side by side with previous output before proceeding.<p><img alt=warning src=/images/warning.svg> On my system, <code>DejaVu Serif</code> did not have <em>italic</em> variation installed, so I had to use <code>sudo apt install ttf-dejavu-extra</code> to get it.</p><br><h2 id=syntax-highlighting>Syntax highlighting<a aria-label="Anchor link for: syntax-highlighting" class=zola-anchor href=#syntax-highlighting>🔗</a></h2><p>One option to customize syntax highlighting for code snippets is to save one of the <code>pandoc</code> themes and editing it. See <a href=https://stackoverflow.com/a/47876166/4082052>stackoverflow: What are the available syntax highlighters?</a> for available themes and more details (as a good practice on stackoverflow, go through all answers and comments — the linked/related sections on sidebar are useful as well).<pre class=language-bash data-lang=bash style=background-color:#f5f5f5;color:#1f1f1f;><code class=language-bash data-lang=bash><span style=color:#5597d6;>$</span><span> pandoc</span><span style=color:#5597d6;> --print-highlight-style</span><span style=color:#72ab00;>=</span><span>pygments </span><span style=color:#72ab00;>></span><span> pygments.theme
</span></code></pre><p>Edit the above file to customize the theme. Use sites like <a href=https://www.colorhexa.com/>colorhexa</a> to help with color choices, hex values, etc. For this demo, the below settings are changed:<pre style=background-color:#f5f5f5;color:#1f1f1f;><code><span># by default, background is same as normal text
</span><span># change it to a shade of gray to easily distinguish code and text
</span><span>"background-color": "#f8f8f8",
</span><span>
</span><span># change italic to false, messes up comments with slashes
</span><span># change comment text-color to yet another shade of gray
</span><span>"Comment": {
</span><span> "text-color": "#9c9c9c",
</span><span> "background-color": null,
</span><span> "bold": false,
</span><span> "italic": false,
</span><span> "underline": false
</span><span>},
</span></code></pre><p><strong>Inline code</strong><p>Similar to changing background color for code snippets, I found a <a href=https://stackoverflow.com/q/40975004/4082052>solution online</a> to change background color for inline code snippets.<pre class=language-latex data-lang=latex style=background-color:#f5f5f5;color:#1f1f1f;><code class=language-latex data-lang=latex><span style=color:#72ab00;>\usepackage</span><span>{</span><span style=color:#a2a001;>fancyvrb</span><span>,newverbs,xcolor}
</span><span>
</span><span style=color:#b39f04;>\definecolor</span><span>{Light}{HTML}{F4F4F4}
</span><span>
</span><span style=color:#b39f04;>\let\oldtexttt\texttt
</span><span style=color:#668f14;>\renewcommand</span><span>{</span><span style=color:#c23f31;>\texttt</span><span>}[1]{
</span><span> </span><span style=color:#b39f04;>\colorbox</span><span>{Light}{</span><span style=color:#b39f04;>\oldtexttt</span><span>{#1}}
</span><span>}
</span></code></pre><p>Add <code>--highlight-style pygments.theme</code> and <code>--include-in-header inline_code.tex</code> to the script and generate the <code>pdf</code> again.<p>With <code>pandoc sample_2.md -f gfm -o sample_2.pdf</code> the output would be:<p><img alt="Default syntax highlighting" src=/images/pandoc_pdf/default_syn.png><p>With <code>./md2pdf_syn.sh sample_2.md sample_2_syn.pdf</code> the output is:<p><img alt="Customized syntax highlighting" src=/images/pandoc_pdf/customized_syn.png></p><br><p>For my <a href=https://github.com/learnbyexample/py_regular_expressions>Understanding Python re(gex)?</a> book, by chance I found that using <code>ruby</code> instead of <code>python</code> for REPL code snippets syntax highlighting was better. Snapshot from <code>./md2pdf_syn.sh sample_3.md sample_3.pdf</code> result is shown below. For <code>python</code> directive, string output gets treated as a comment and color for boolean values isn't easy to distinguish from string values. The <code>ruby</code> directive treats string value as expected and boolean values are easier to spot.<p><img alt="REPL syntax highlighting" src=/images/pandoc_pdf/python_vs_ruby_syn.png></p><br><h2 id=bullet-styling>Bullet styling<a aria-label="Anchor link for: bullet-styling" class=zola-anchor href=#bullet-styling>🔗</a></h2><p>This <a href=https://stackoverflow.com/q/22156999/4082052>stackoverflow Q&A</a> helped for bullet styling.<pre class=language-latex data-lang=latex style=background-color:#f5f5f5;color:#1f1f1f;><code class=language-latex data-lang=latex><span style=color:#72ab00;>\usepackage</span><span>{</span><span style=color:#a2a001;>enumitem</span><span>}
</span><span style=color:#72ab00;>\usepackage</span><span>{</span><span style=color:#a2a001;>amsfonts</span><span>}
</span><span>
</span><span style=color:#7f8989;>% level one
</span><span style=color:#b39f04;>\setlist</span><span>[itemize,1]{label=</span><span style=color:#d07711;>$</span><span style=color:#b39f04;>\bullet</span><span style=color:#d07711;>$</span><span>}
</span><span style=color:#7f8989;>% level two
</span><span style=color:#b39f04;>\setlist</span><span>[itemize,2]{label=</span><span style=color:#d07711;>$</span><span style=color:#b39f04;>\circ</span><span style=color:#d07711;>$</span><span>}
</span><span style=color:#7f8989;>% level three
</span><span style=color:#b39f04;>\setlist</span><span>[itemize,3]{label=</span><span style=color:#d07711;>$</span><span style=color:#b39f04;>\star</span><span style=color:#d07711;>$</span><span>}
</span></code></pre><p>Comparing <code>pandoc sample_4.md -f gfm -o sample_4.pdf</code> vs <code>./md2pdf_syn_bullet.sh sample_4.md sample_4_bullet.pdf</code> gives:<p><img alt="Bullet styling" src=/images/pandoc_pdf/bullet_styling.png></p><br><h2 id=pdf-properties>PDF properties<a aria-label="Anchor link for: pdf-properties" class=zola-anchor href=#pdf-properties>🔗</a></h2><p>This <a href=https://tex.stackexchange.com/questions/23235/eliminate-edit-pdf-properties-added-by-pdflatex>tex.stackexchange Q&A</a> helped to change metadata. See also <a href=https://pspdfkit.com/blog/2018/whats-hiding-in-your-pdf/>pspdfkit: What’s Hiding in Your PDF?</a> and <a href="https://news.ycombinator.com/item?id=18381515">discussion on HN</a>.<pre class=language-latex data-lang=latex style=background-color:#f5f5f5;color:#1f1f1f;><code class=language-latex data-lang=latex><span style=color:#72ab00;>\usepackage</span><span>{</span><span style=color:#a2a001;>hyperref</span><span>}
</span><span>
</span><span style=color:#b39f04;>\hypersetup</span><span>{
</span><span> pdftitle={My awesome book},
</span><span> pdfauthor={learnbyexample},
</span><span> pdfsubject={pandoc},
</span><span> pdfkeywords={pandoc,pdf,xelatex}
</span><span>}
</span></code></pre><p><code>./md2pdf_syn_bullet_prop.sh sample_4.md sample_4_bullet_prop.pdf</code> gives:<p align=center><img alt="pdf properties" loading=lazy src=/images/pandoc_pdf/pdf_properties.png></p><br><h2 id=adding-table-of-contents>Adding table of contents<a aria-label="Anchor link for: adding-table-of-contents" class=zola-anchor href=#adding-table-of-contents>🔗</a></h2><p>There's a handy option <code>--toc</code> to automatically include table of contents at top of the generated <code>pdf</code>. You can control number of levels using <code>--toc-depth</code> option, the default is 3 levels. You can also change the default string <code>Contents</code> to something else using <code>-V toc-title</code> option.<p><code>./md2pdf_syn_bullet_prop_toc.sh sample_1.md sample_1_toc.pdf</code> gives:<p><img alt="table of contents" src=/images/pandoc_pdf/table_of_contents.png></p><br><h2 id=adding-cover-image>Adding cover image<a aria-label="Anchor link for: adding-cover-image" class=zola-anchor href=#adding-cover-image>🔗</a></h2><p>To add something prior to table of contents, cover image for example, you can use a <code>tex</code> file and include it verbatim. Create a <code>tex</code> file (named as <code>cover.tex</code> here) with content as shown below:<pre class=language-tex data-lang=tex style=background-color:#f5f5f5;color:#1f1f1f;><code class=language-tex data-lang=tex><span style=color:#b39f04;>\includegraphics</span><span>{cover.png}
</span><span style=color:#b39f04;>\thispagestyle</span><span>{empty}
</span></code></pre><p>Then, modify the previous script <code>md2pdf_syn_bullet_prop_toc.sh</code> by adding <code>--include-before-body cover.tex</code> and tada — you get the cover image before table of contents. <code>\thispagestyle{empty}</code> helps to avoid page number on the cover page, see also <a href=https://tex.stackexchange.com/questions/360739/what-is-the-use-of-clearpage-thispagestyleempty-cleardoublepage>tex.stackexchange: clear page</a>.<p>The <code>bash</code> script invocation is now <code>./md2pdf_syn_bullet_prop_toc_cover.sh sample_5.md sample_5.pdf</code>.<p><img alt=warning src=/images/warning.svg> You'll need at least one image in input markdown file, otherwise settings won't apply to the cover image and you may end up with weird output. <code>sample_5.md</code> used in the command above includes an image. And be careful to use escapes if the image path can contain <code>tex</code> metacharacters.</p><br><h2 id=stylish-blockquote>Stylish blockquote<a aria-label="Anchor link for: stylish-blockquote" class=zola-anchor href=#stylish-blockquote>🔗</a></h2><p>By default, blockquotes (lines starting with <code>></code> in markdown) are just indented in the <code>pdf</code> output. To make them standout, <a href=https://tex.stackexchange.com/questions/154528/how-to-change-the-background-color-and-border-of-a-pandoc-generated-blockquote>tex.stackexchange: change the background color and border of blockquote</a> helped.<p>Create <code>quote.tex</code> with the contents as shown below. You can change the colors to suit your own preferred style.<pre class=language-tex data-lang=tex style=background-color:#f5f5f5;color:#1f1f1f;><code class=language-tex data-lang=tex><span style=color:#72ab00;>\usepackage</span><span>{</span><span style=color:#a2a001;>tcolorbox</span><span>}
</span><span style=color:#b39f04;>\newtcolorbox</span><span>{myquote}{colback=red!5!white, colframe=red!75!black}
</span><span style=color:#b39f04;>\renewenvironment</span><span>{quote}{</span><span style=color:#72ab00;>\begin</span><span>{</span><span style=color:#5597d6;>myquote</span><span>}}{</span><span style=color:#72ab00;>\end</span><span>{</span><span style=color:#5597d6;>myquote</span><span>}}
</span></code></pre><p>The <code>bash</code> script invocation is now <code>./md2pdf_syn_bullet_prop_toc_cover_quote.sh sample_5.md sample_5_quote.pdf</code>. The difference between default and styled blockquote is shown below.<p align=center><img alt="styling blockquotes" loading=lazy src=/images/pandoc_pdf/styled_blockquote.png></p><br><h2 id=customizing-epub>Customizing epub<a aria-label="Anchor link for: customizing-epub" class=zola-anchor href=#customizing-epub>🔗</a></h2><p>For a long time, I thought <code>epub</code> didn't make sense for programming books. Turned out, I wasn't using the right ebook readers. <strong>FBReader</strong> is good for novels but not ebooks with code snippets. When I used <a href=https://github.com/mate-desktop/atril>atril</a> and <a href=https://calibre-ebook.com/>calibre ebook-viewer</a>, the results were good.<p>I didn't know how to use <code>css</code> before trying to generate the <code>epub</code> version. Somehow, I managed to take the default <a href=https://github.com/jgm/pandoc/blob/master/data/epub.css>epub.css</a> provided by <code>pandoc</code> and customize it as close as possible to the <code>pdf</code> version. The modified <code>epub.css</code> is available from the <a href=https://github.com/learnbyexample/learnbyexample.github.io/tree/master/files/pandoc_pdf>learnbyexample.github.io repo</a>. The <code>bash</code> script to generate the <code>epub</code> is shown below and invoked as <code>./md2epub.sh sample_5.md sample_5.epub</code>. Note that <code>pygments.theme</code> is same as the <code>pdf</code> customization discussed before.<pre class=language-bash data-lang=bash style=background-color:#f5f5f5;color:#1f1f1f;><code class=language-bash data-lang=bash><span style=color:#7f8989;>#!/bin/bash
</span><span>
</span><span style=color:#5597d6;>pandoc </span><span style=color:#d07711;>"$</span><span style=color:#acb3c2;>1</span><span style=color:#d07711;>" </span><span>\
</span><span style=color:#5597d6;> -f</span><span> gfm \
</span><span style=color:#5597d6;> --toc </span><span>\
</span><span style=color:#5597d6;> --standalone </span><span>\
</span><span style=color:#5597d6;> --top-level-division</span><span style=color:#72ab00;>=</span><span>chapter \
</span><span style=color:#5597d6;> --highlight-style</span><span> pygments.theme \
</span><span style=color:#5597d6;> --css</span><span> epub.css \
</span><span style=color:#5597d6;> --metadata</span><span style=color:#72ab00;>=</span><span>title:</span><span style=color:#d07711;>"My awesome book" </span><span>\
</span><span style=color:#5597d6;> --metadata</span><span style=color:#72ab00;>=</span><span>author:</span><span style=color:#d07711;>"learnbyexample" </span><span>\
</span><span style=color:#5597d6;> --metadata</span><span style=color:#72ab00;>=</span><span>lang:</span><span style=color:#d07711;>"en-US" </span><span>\
</span><span style=color:#5597d6;> --metadata</span><span style=color:#72ab00;>=</span><span>cover-image:</span><span style=color:#d07711;>"cover.png" </span><span>\
</span><span style=color:#5597d6;> -o </span><span style=color:#d07711;>"$</span><span style=color:#acb3c2;>2</span><span style=color:#d07711;>"
</span></code></pre><br><h2 id=resource-links>Resource links<a aria-label="Anchor link for: resource-links" class=zola-anchor href=#resource-links>🔗</a></h2><ul><li><a href=https://pandoc.org/MANUAL.html>pandoc: manual</a><li><a href=https://pandoc.org/demos.html>pandoc: demos</a><li><a href=https://github.com/jgm/pandoc/wiki/Pandoc-Tricks>pandoc: tips and tricks</a></ul><p><strong>More options and workflows for generating ebooks</strong>:<ul><li><a href=https://github.com/Wandmalfarbe/pandoc-latex-template>pandoc-latex-template</a> — a clean pandoc LaTeX template to convert your markdown files to PDF or LaTeX<li><a href=https://keleshev.com/my-book-writing-setup/>Writing a book with pandoc, make, and vim</a><li><a href=https://quarto.org/>Quarto</a> — open source scientific and technical publishing system built on Pandoc<li><a href=https://jupyterbook.org/intro.html>Jupyter Book</a> — open source project for building beautiful, publication-quality books and documents from computational material <ul><li>See also <a href=https://github.com/fastai/fastdoc>fastdoc</a> — the output of fastdoc is an asciidoc file for each input notebook. You can then use asciidoctor to convert that to HTML, DocBook, epub, mobi, and so forth</ul><li><a href=https://www.thedigitalcatbooks.com/maubook-introduction/>Mau</a> — template-based markup language, heavily inspired by AsciiDoc<li><a href=https://asciidoctor.org/docs/what-is-asciidoc/>Asciidoctor</a> <ul><li><a href=https://github.com/daneah/asciidoc-book-template>Asciidoc book template</a><li><a href=https://shape-of-code.coding-guidelines.com/2019/08/11/my-books-pdf-generation-workflow/>pdf generation workflow with Asciidoc</a></ul><li><a href=https://www.sphinx-doc.org/en/stable/index.html>Sphinx</a> <ul><li><a href=https://digitalsuperpowers.com/blog/2019-02-16-publishing-ebook.html>Self-publishing a book with reStructuredText, Sphinx, Calibre, and vim</a></ul><li><a href=https://bookdown.org/home/>Bookdown</a><li><a href=https://orgmode.org/>Emacs orgmode</a><li><a href=https://casual-effects.com/markdeep/>Markdeep</a></ul><p><strong>Miscellaneous</strong><ul><li><a href=https://nickjanetakis.com/blog/vim-is-saving-me-hours-of-work-when-writing-books-and-courses>Vim is saving me hours of work when writing books & courses</a><li><a href=https://joecmarshall.com/posts/book-writing-environment/>Writing a Book with Unix</a><li><a href=https://askubuntu.com/questions/3697/how-do-i-install-fonts>askubuntu: How do I install fonts?</a><li><a href=https://tex.stackexchange.com/questions/9533/what-best-combination-of-fonts-for-serif-sans-and-mono-do-you-recommend>tex.stackexchange: What best combination of fonts for Serif, Sans, and Mono do you recommend?</a><li><a href=https://tug.org/FontCatalogue/>LaTeX font catalogue</a><li><a href=https://github.com/karthik/markdown_science/wiki/Tools-to-support-your-markdown-authoring>Tools to support markdown authoring</a><li><a href=https://picular.co/>picular: search engine for colors</a> and <a href=https://www.colorhexa.com/>colorhexa</a><li><a href="https://ebooks.stackexchange.com/questions?sort=votes">ebooks.stackexchange</a></ul></div><div class=post-footer><div class=post-tags><a href=https://learnbyexample.github.io/tags/tutorial/>#tutorial</a><a href=https://learnbyexample.github.io/tags/ebook-generation/>#ebook-generation</a><a href=https://learnbyexample.github.io/tags/pandoc/>#pandoc</a><a href=https://learnbyexample.github.io/tags/xelatex/>#xelatex</a><a href=https://learnbyexample.github.io/tags/markdown/>#markdown</a><a href=https://learnbyexample.github.io/tags/pdf/>#pdf</a><a href=https://learnbyexample.github.io/tags/epub/>#epub</a></div><hr color=#e6e6e6><div class=post-nav><p><a class=previous href=https://learnbyexample.github.io/python-intermediate/>← I know Python basics, what next?</a><br><p><a class=next href=https://learnbyexample.github.io/javascript-regexp-cheatsheet/>JavaScript regular expressions cheatsheet and examples →</a><br></div><hr color=#e6e6e6><p>📰 Use <a href=https://learnbyexample.github.io/atom.xml>this link</a> for the Atom feed. <br> ✅ Follow me on <a href=https://twitter.com/learn_byexample>Twitter</a>, <a href=https://github.com/learnbyexample>GitHub</a> and <a href=https://www.youtube.com/c/learnbyexample42>Youtube</a> for interesting tech nuggets. <br> 📧 Subscribe to <a href=https://learnbyexample.gumroad.com/l/learnbyexample-weekly>learnbyexample weekly</a> for programming resources, tips, tools, free ebooks and more (free newsletter, delivered every Friday).<hr color=#e6e6e6></div></article></div></main></div><script src=https://learnbyexample.github.io/even.js></script>