Writing in doc/docx editors (Word, LibreOffice etc.) sucks. So does plain Latex. Both distract from actual writing by forcing constant style management (doc / docx) or through gazillion of tags you need to remeber, add and control (Latex). I’m easily distracted - thus not the greatest fan of either.

At the same time formats like markdown (which I like and wrote about previously) lack the direct control of the way the document will be displayed. But luckily with Pandoc and other tools this can be easily remedied - which enables handy workflow for academic writing.

While I’ve started working on a text for my diploma I’ve developed an approach that gives me a lot of control through latex without actually writing in plain latex. In short - I write in markdown, then use pandoc with slightly modified default template to generate nice pdf-s, with bibliography, citations and so on. It’s pretty seamless - but to make it so, I had to get over some hurdles.

Use frontmatter

It quickly turned out the more options I want to add (change margins, set font, bibliography etc) the longer and more unreadable the pandoc command gets. Solution is pretty simple - use frontmatter. Put all the options you can in this optional section of markdown doc and Pandoc will process it.

So for example it may look like this:

---
papersize: a4
geometry:
- top=25mm
- bottom=25mm
- left=30mm
- right=20mm
start-page: 5
author:
- Name Surname
title:  'Loremipsum - pandoc test'
lang: pl
numbersections: True
toc: True
bibliography: "samplebib.bib"
reference-section-title: "Bibliografia"
csl: "harvard-cite-them-right.csl"
---

This in the beggining of markdown document ensures the page size will be set to A4, with margins set to 25mm x 25mm x 30mm x 20mm, with page numbering starting at 5 (for example if you wish to add some pre-prepared title pages later on), the doc will get proper title and author, language set to pl, each section will be numbered, with auto generated table of contents (toc, if you wish to add list of figures as well add lof: True or lot: True for list of tables) and with extra section (titled “Bibliografia”) for bibliography taken from “samplebib.bib” file (generated in Zotero etc.) and styled using harvard-cite-them-right.csl file (which not surprisingly contains basic Harvard citation style definition).

This way I can generate pdf with pretty short command like:

pandoc --citeproc loremipsum.md -o test.pdf --template=./mystyle.latex

Notes in footer

There are several ways to add notes, but IMO the simplest way is to use so called inline notes. You just start with ^ followed by the square brackets [] where you put your note.

So :

Vel facilisis volutpat est velit egestas dui id ornare arcu.^[Inline notes are easier to write, since you don't have to pick an identifier and move down to type the note.]

could result in something like:

Bibliography in footer

The best way is to use a citation style file (csl) that enforces adding bibliography notes this way. But if you need to add it somehow you can use the inline notes method given above, with you bibliography link written between brackets.

Lacus viverra vitae congue eu consequat ac felis donec et ^[@shah_ansible_2015].

Again Pandoc will process it correctly - and will transfrom this link to correct style in both footer and bibliography section.

Spice it up with Latex

There are limits to what markdown can do. It provides excellent writing experience, but there are times when some fancy thing need to be done with page layout.

Luckily there’s an option to simply write some latex tags directly in markdown file.

Mind this has a downside though - it will work great for generating pdf, but will be problematic if you wish to use the same .md file for a static page generator like Hugo. In best case scenario those tags will display as regular text (wont’ be processed at all).

But if a print document / article is your main goal that’s not a problem. Personally I try to use just a couple of those extra tags - and only when really in need.

Pagebreaks

You might want the next section to appear on new page - just add:

\pagebreak

and you’re set.

• bonus hint: add this at the end of your document and the bibliography section will get a new page, instead showing app shortly after the last sentence.

Sections without numeration

Sometimes there’s no need to add numeration to the section - for example in the diploma article I’m working on the spec says you shouldn’t have a numbered intro. Just add {-} after the section title and Pandoc won’t numerate it.

# Some section {-}

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Sit amet luctus venenatis lectus magna fringilla urna.

List of figures / tables in custom spot

If there’s a need to place lof / lot in some custom place, not the default one this can be done by adding:

\hypertarget{lof}{
\listoffigures\label{lof}}
\addcontentsline{toc}{section}{Section name}

Custom tex theme

For the times when a custom template is really needed it will be hard to avoid learning some more Latex. But just tweaking the default one might be enough. You can get it easily by typing:

pandoc -D latex > *path/filename*

This will grab the default latex file and will write it where you want (just change the path_filename to desired location).

Closing notes

That’s it - this minimal setup allows me to enjoy writing while adhering to the document specs enforced by the college. I can use my favourite editors (currently Joplin and Obsidian - oh, how I wish there was an open source or regular, no-subscription based version of the latter) and reap all the benefits of markdown including version control via Git and automatic document generation via Github Actions (which I’ll probably cover in the last article in the markdown series).