Inspired by Dan Prince's Academic Pandoc.
Everything can be easily installed via Homebrew package manager on macOS. Command below should install Command Line Tools from Apple as well (you'll need it later too; if not, run xcode-select —install to invoke a pop-up).
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"Then install Pandoc:
brew install pandoc pandoc-citeprocYou'll also need LaTeX. Pandoc recommends installing BasicTeX, since a full MacTeX installation takes more than a gigabyte of disk space. You can either download the installer or install it by Homebrew-Cask (which you have already installed with Homebrew):
brew cask install basictexIf you need any additional packages later, you can install them by tlmgr tool. For example:
sudo tlmgr update --self
sudo tlmgr install collection-fontsrecommendedNot ready yet 😢
And if you want to enjoy comfortable styling by CSS, you'll need also Prince – a tool which can convert HTML documents to PDF. It's free for non-commercial use. You have to download the archive, unpack it and run this command in the folder:
sudo ./install.shSee official installation guide for more details.
And now, let's try if everything works fine. Run:
./scripts/buildAnd you should see a newly created PDF file in the output folder.
If you get pdflatex not found error, these commands should fix it:
# Append correct path to .bash_profile
echo "export PATH="$PATH:/Library/TeX/texbin"" >> ~/.bash_profile
# Update shell
source ~/.bash_profileCitations with pandoc-citeproc are a piece of cake. Just collect all sources at one place and then reference them during writing.
Sources collections are placed in content/references folder. You can add as many files as you want.
You can use a lot of formats (see list), most notably BibTeX, which can be downloaded at many services like Google Scholar/Books.
If you want to manage the collection manually, the most convenient option is to use CSL YAML format (don't forget to add .yaml extension to your file). CSL means Citation Style Language, see specification, especially useful is list of types and variables. YAML is a human-readable data serialization language, so it's easy to write the collection by hand. Otherwise it is based on CSL JSON format.
The file has to start with:
references:Below, there's a space for your sources. Let's try Thinking, Fast and Slow by Daniel Kahneman book:
- id: thinking-fast-and-slow
type: book
author:
- family: Kahneman
given: Daniel
title: Thinking, Fast and Slow
edition: 1
publisher: Farrar, Straus and Giroux
publisher-place: New York
issued:
- year: 2011
ISBN: 978-0374275631Nothing difficult, right? It's important to keep the indentation precise. As id you can use any string – you'll reference it later in the text. So the whole file may look like this:
references:
- id: thinking-fast-and-slow
type: book
author:
- family: Kahneman
given: Daniel
title: Thinking, Fast and Slow
edition: 1
publisher: Farrar, Straus and Giroux
publisher-place: New York
issued:
- year: 2011
ISBN: 978-0374275631And now the easier part. See Pandoc User's Guide.
Inserting footnotes is totally simple. The first and simplier approach allows you to write footnotes directly in text:
This is a text with footnote.^[…and this the inline footnote itself.]If you prefer to separate the footnotes, you can reference the footnote by an identifier. Identifier can be anything (except it cannot contain spaces) and it has to be unique throughout the document – footnotes will be numbered sequentially automatically.
You can use also footnote identifiers, which separates the footnote content.[^footnote]
[^footnote]: It's a good thing that in that case, you can use multiple paragraphs within the footnote.
Just don't forget to indent other paragraphs by four spaces.Inserting figures – or photos/images/illustrations/schemes/whatever-you-want-to-call-it – works in the same way as inserting images in Markdown. Just be sure the image is in a separate paragraph.
Figure is then automatically annotated and added to List of figures. If you don't want List of figures, simply delete the 0-03-list-of-figures.md file.
But because you'll probably want to reference the figures in the text, the syntax gets a bit more complicated:
{#fig:figure}
See the cat in [\autoref{fig:figure}](#fig:figure).Where figure presents unique identifier of the certain figure.
As you can see, it's possible to link images directly from the internet, which is definitely not recommended. This is how you can insert local file, even PDF. Figures are saved in content/figures folder.
If you want to insert an image not as an figure, simply add backslash at the end:
\Inserting tables is a bit more complicated, especially if you want to use advanced formatting (in that case see Pandoc manual). But not that much:
Table: This is a table caption, you can even use a citation [@thinking-fast-and-slow]
First column | Centered column | Right aligned column
------------- |:---------------:| -------------------:
First row | Second cell | 1234
Second row | Centered cell | 4567
3rd row | …another cell | 89If you want to reference a table, it works in a similar way as with figures:
This is a reference to [\autoref{tab:table}](#tab:table).
Table: [This is a table without header, but with a reference]{#tab:table} \label{tab:table}
----------- ----------------
Another way to insert tables
This time without header
----------- ----------------Tables are again automatically listed in List of tables, if you don't want that, simply delete the 0-04-list-of-tables.md file.
You can add appendices. It's important to name the files beginning with 3. You can add as many appendices as you want, all will be numbered by letter. To change the appendices name (from Appendix to something else), edit 0-00-metadata-and-settings.yaml file.