README.md

# Pandoc Template: Slides

This is a template for building presentation slides using Markdown and Pandoc, mainly meant for usage as a git submodule.

You can take a look at my [functional programming slides](https://git.eisfunke.com/lab/fupro) or my[pandoc slides](https://git.eisfunke.com/lab/pandoc) if you want to see it in action.

I also have templates for other document types [here](https://git.eisfunke.com/document/pandoc-template).

## Requirements

You need the following software installed:

- Pandoc
- `pandoc-crossref`
- LuaLaTeX
- `make`
- These fonts:
  - [Zilla Slab](https://github.com/mozilla/zilla-slab)
  - [Raleway](https://github.com/theleagueof/raleway)
  - [Iosevka Funke](https://git.eisfunke.com/config/iosevka)

Alternatively you can use my [PandocPlus Docker image](https://git.eisfunke.com/software/container/pandoc-plus) if you don't want to install the software and fonts directly.

Instructions below!

## Preparing the Project

You need the files in this repo inside a folder named `template` in your project folder to use it. Use one of the following methods to get it.

### Use as download

- Download the repo: [zip file](https://git.eisfunke.com/document/pandoc-template/slides/-/archive/main/slides-main.zip)
- Extract the archive into a folder named `template` inside your project folder.

### Use as repo

- Clone this repo with `git clone https://git.eisfunke.com/document/pandoc-template/slides.git template` into your project folder.

### Use inside a Git repo

- Create a Git repo inside a folder using `git init` or clone an existing one with `git clone`
- Inside the repo folder create a Git submodule with this template repo: `git submodule add --name template https://git.eisfunke.com/document/pandoc-template/slides template`


## Usage

Your project directory should now look like this:

```
your project folder
├── literature.bib (optional, containing your biblatex references)
├── metadata.yaml (required, see below)
├── res (optional)
│   └── ... any images and other resources you need
├── src
│   ├── 10-your-first-source-file.md
│   ├── 20-your-second-source-file.md
│   └── … all your source files, they will be concatenated alphabetically
└── template
    └── … the contents of this repo
```

Compile your project with `make -f template/makefile`, the output will be in the file `out/slides.pdf`.

If you're using the docker image run this:

```sh
sudo docker pull registry.gitlab.fachschaften.org/nicolas.lenz/pandoc-plus  # to pull or update the image
sudo docker run --rm -v $PWD:/mnt registry.eisfunke.com/software/container/pandoc-plus make -C /mnt -f template/makefile
```

The first command will pull the image, the second will run the image by mounting the current working directory into the created container and then running `make` there to build the container.

### `metadata.yaml`

You need a `metadata.yaml` file for settings etc. All data is optional, except for `title`.

This minimal `metadata.yaml` would work to start you off:

```yaml
title: Your Title Here
```

This example shows all available options:

```yaml
title: Your Title Here  # required
subtitle: Your Subtitle Here
color-primary: ed6c00  # hex code for primary color for title slide and slide headings, this is the default
color-progress-bg: f07d8f  #  hex code for progress bar background, this is the default
color-progress-fg: a90d24  #hex code for progress bar foreground, this is the default
logo: logofile.png  # logo image file, will be shown on the title slide
author: Nicolas Lenz  # author for the title slide
date: 2022-04-28  # date for the title slide
institute: |  # will be shown on the right side of the title slide
  Line One

  Line Two
disclaimer: |  # will be shown on a slide after the title slide
  Line One

  Line Two

flake: false  # enables a snowflake in the background on the title slide, default is off

# customization options for the snowflake, these are the default settings
flake-symbols:
  - F
  - G
  - H
flake-rules:
  - "`F -> H[+HG][-HG]G`{=latex}"
  - "`G -> HF`{=latex}"
flake-axiom: FF
flake-order: 4
flake-rotation: 0
flake-step: 0.6cm
flake-width: 0.9cm
flake-scale: 1.0
flake-opacity: 0.1
```

### GitLab CI

This repo contains templates meant for inclusion into a `.gitlab-ci.yml` file if you want to build or deploy your slides using GitLab CI.

`build.gitlab-ci.yml` builds the pdf and tex files and saves them as artifacts. `pages.gitlab-ci.yml` can then be used to deploy the files via GitLab Pages. For example, if you wanted to do both, you could use this as your `.gitlab-ci.yml` in your project structured as described above:

```
include:
  - remote: https://git.eisfunke.com/document/pandoc-template/report/-/raw/main/build.gitlab-ci.yml
  - remote: https://git.eisfunke.com/document/pandoc-template/report/-/raw/main/pages.gitlab-ci.yml
```