Pandoc Thesis Template

A template for thesis documents written in Markdown.

About

This template makes it easy to write your thesis in Markdown. It uses an integrated toolchain to translate your work into LaTeX, creating a properly formatted PDF document. So you don't have to worry about the somewhat arcane TeX commands and you can still enjoy the centuries-old art of letterpress printing, with its rules integrated into LaTeX.

You can choose between two different styles:

• 'simple'

  The 'Simple' theme uses the scrbook LaTeX class and adds a custom title page.

• 'Eisvogel'

  The 'Eisvogel' style is based on the Eisvogel LaTeX template and adds a back page for the cover sheet with all the information you need for a thesis.

Both styles let you add an acknowledgement, an abstract (in German and/or English) and a restriction note.

Prerequisites

There are two different ways you can start with this template:

1. Working locally on your own machine:

   You will need Docker and the pandoc/extra docker image, as well as the contents of this template repository plus GNU Make.

-   Fork this repository into your own namespace

    Here's a tip: If you don't need the history or future update, just click the '*Use
    this template*' button above!

-   *Git clone* your repository locally to your machine

-   Install [Docker]

-   Fetch the [`pandoc/extra`] docker image containing all dependencies, e.g. pandoc and
    TeX Live: `make docker` or `docker pull pandoc/extra:latest-ubuntu`

    **Note**: You will need about 1.5GB of free disk space:

        $ docker image ls
        REPOSITORY       TAG             IMAGE ID       CREATED       SIZE
        pandoc/extra     latest-ubuntu   4be5559759ed   6 weeks ago   1.27GB

-   Work on the [`thesis.md`] and [`references.bib`] files to create your thesis and build
    the PDF using `make simple` or `make eisvogel` (see below)

</details>

1. Working remote using GitHub workflows:

   Maintain a repository with the two relevant files thesis.md and references.bib, and use a GitHub workflow to build the PDF.

-   Either fork this repository into your own namespace or create your own repository
    containing copies of both the [`thesis.md`] and [`references.bib`] files provided here

-   Create a GitHub workflow in your repository using the GitHub action
    `cagix/pandoc-thesis` that is included in this template, e.g.:

    ``` yaml
    on:
      pull_request:

    jobs:
      compile:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v5
          - uses: cagix/pandoc-thesis@master
            with:
              srcfile: thesis.md
              targetfile: thesis.pdf
              bibfile: references.bib
              template: eisvogel
          - uses: actions/upload-artifact@v4
            with:
              path: thesis.pdf
              overwrite: true
    ```

    Please adjust the file names as needed.

-   Work on the [`thesis.md`] and [`references.bib`] files to create your thesis and build
    the PDF by pushing to your repository (see below)

</details>

Working with this template

1. Maintain your references in references.bib

   There are many reference management programs offering BibTeX export. A nice example is JabRef, which allows you to create and maintain your BibTeX file locally.

2. Put the title of your thesis, your name and other meta information into the YAML header of thesis.md

3. Adjust optional definitions in the YAML header of thesis.md to your needs:

-   Disable extras like `abstract-*` or `acknowledgements` or `restrictionnote`: Remove or
    comment this optional definitions
-   Modify content (text) of optional definitions like `abstract-*` or `acknowledgements`
    or `restrictionnote`

1. Put your content into the markdown file thesis.md

   The default chapters correspond to a typical structure of a scientific thesis (see also @Balzert2022: Balzert et al. "Wissenschaftliches Arbeiten", 2022). You can just use this as starting point for your work ...

   Hint: You will find some help regarding the use of Markdown in the first chapter of thesis.md as well as typical number of pages for each chapter in the beginning of each chapter.

2. Pandoc uses per default the Chicago Manual of Style for citations (cf. pandoc.org/MANUAL.html#citations).

   You can search zotero.org/styles or editor.citationstyles.org/searchByName for alternative style definitions, download the corresponding .csl file to your project folder and activate the style in the corresponding default file, i.e. eisvogel.yaml or simple.yaml.

3. Build the thesis:

-   Locally:
    -   Simple layout: `make simple`
    -   Eisvogel theme: `make eisvogel`
-   Remote:
    -   `git push` (and let your GitHub workflow do the heavy lifting)

1. Clean up (when working locally):

-   To remove temporary (generated) filed: `make clean`
-   To also remove the generated thesis (PDF): `make distclean`

[!WARNING] When switching between templates, please make sure to make clean first! Failing to do so may lead to strange behaviour or even to weird errors.

[!IMPORTANT] Do not use Windows + Docker directly, but via WSL:

• Install WSL (see https://learn.microsoft.com/en-us/windows/wsl/install), any distribution will work
• Start the subsystem to get access to its shell
• git clone https://github.com/cagix/pandoc-thesis.git to pull the project
• make docker to pull the pandoc/extra image
• make simple or make eisvogel to build the thesis
• Success!

Submitting your thesis

HSBI students submit their work as a PDF using the upload form at https://www.hsbi.de/hochschule/schriftliche-arbeiten.

A declaration of originality must also be submitted. The form can be found at "Eigenständigkeitserklärung" and must be completed, signed and uploaded together with the thesis PDF.

Preview

Example using Simple Layout

| Simple Titlepage | Simple Chapter | |--------------------------|------------------------| | | |

Example using Eisvogel Template

| Eisvogel Titlepage | Eisvogel Chapter | |----------------------------|--------------------------| | | |

License

This work by Carsten Gips and contributors is licensed under MIT.