A template for creating a degree project thesis in markdown + pandoc
If you're at TU Dublin, here's a video of the basics:
Here is the type of PDF thesis document you can easily generate using this repository template:
you now do not need to install ANY software locally - once you've created a FORK of this project, and commit new changes, then a Github Action will run to create a new thesis PDF for you
This repo uses the LaTeX Pandoc Docker image for Github actions from here:
follow these steps:
-
(Github) Create a FORK of this repository project https://github.com/dr-matt-smith/pandoc-thesis-template
-
(Github) in the repository settings, select
Actions
-
(Github | Actions) click the Green button to enable workflows
-
OPTIONAL if you want to work on your local computer clone the repo to your machine
-
Create/Edit some bits
- E.g. title parameters in:
01_front_material/1_title.md
- Change the text in chapter 1:
00_chapters/chapter1_introduction.md
- NOTE: markdown is great โ just write text / #heading1 / ##heading2 / - for bullet list / 1 for numbered list and so on ..
- here are more details about GitHub Markddown
- E.g. title parameters in:
-
(IF LOCAL CLONE EDITING) add/commit/push the changes
-
(IF Gihub website EDITING) each change is automatically a new commit :-)
-
(Github | Actions) click the
Build thesis PDF
action
- (Github | Actions) It will take something like 25-60 seconds (depending on number of pages / complexity of document - but remmeber, this is a free Linux virtual machine from Github :-):
- (Github | Actions) Look at the OUTPUT for the Github ACTIONS โ you should be able to download a newly created PDF of the thesis !
Having done the above once, your PDF to be created automatically in the future every time there is a new COMMIT pushed to the Github repo
- so just CRUD chapters/figures etc. and commit to Github and in a minute or so you can see your updated thesis ...
Add / remove chapters/appendices from the 00_chapters
and 04_appendices
folders. But you must also update file .github/workflows/generate_pdf.yml
to match the sequence of chapters/appendices you want.
NOTE I find it simplest to add a break_______________
after every page
- this ensures there is always at least one blank line after each chapter document, which prevents content from 2 chapters runing together into a single chapter
if you still wish to work on your local machine (why???!!) then here are details in the old README
Add to the collection of references in /05_references/references.bib
Only items that are cited will be added to the list of references in the generated PDF.
For more about CSL and BibTeX see README REFS
To cite a reference item write the 'id' of the reference item in square brackets with an '@-at' sign as follows:
Lots of people have written about how wonderful Pandoc is, for example see [@smith2017].
where in the above smith2017
is the unique 'id' of the reference item. This would output something like this (if citations mode is Harvard-Limerick):
Lots of people have written about how wonderful Pandoc is, for example see (Smith 2017).
In a LaTeX BibText reference collection this 'id' comes immediately after the opening brace {
:
@article{smith2017,
author = {Smith, Matt},
title = {{Some paper about something}},
journal = {Great papers in compting (Dublin, Ireland)},
year = {2017},
volume = {1},
pages = {1--19}
}
To cite a reference item without the authors' names, but just have the year/alpha bit, prefix the citation with a minus sign, e.g.:
Smith [-@smith2017] writes about how wonderful Pandoc is.
would output something like this (if citations mode is Harvard):
Smith (2017) writes about how wonderful Pandoc is.
For BibTeX references then
-
add a "url" and "accessed" field
-
e.g.
@book{smith2018, author = {Smith, Matt}, title = {Unity 2018 Cookbook}, publisher = {Packt}, year = {2018}, url = {https://www.packtpub.com/eu/game-development/unity-2018-cookbook-third-edition}, accessed = {2020} }
-
Copy the figure image into folder 03_figures
. E.g. copy the octocat.png
Github image there.
Use the exclamation mark, followed by caption text (in square brackets), and then path to image file (in parentheses round brackets), e.g.:
![Github's famous 'Octocat'!](03_figures/octocat.png)
You can cite the figure number in the text (to match the automatic figure numbering) by adding a \label{<label>}
in the figure line, and using \ref{<label>}
in your text to get the figure number, e.g.:
See Figure \ref{octocat} to see the famous Github Octocat logo.
![Github's famous 'Octocat'! \label{octocat}](03_figures/octocat.png)
Just remove the appropriate line(s) from the workflow YAML file if you don't want a List of Tables / Figures generated after the Table of Contents.
Find some more Pandoc templates here:
This thesis template is based on the one published by Chia Kaivalya https://chiakaivalya.wordpress.com/2014/04/23/using-markdown-pandoc-to-write-my-biology-phd-thesis/
Thanks Chia!
"First, you catch your fish, then you need to fillet your fish until you serve the finest piece" (Claus Toksvig being quoted by daughter Sandi in Willams 2020)
REFERENCES: Williams, Z. (2020) "Interview with Sandi Toksvig", The Guardian newspaper, UK, 25 May 2020.