Init article template

.gitignore

+article.pdf
+article.tex
+out/

LICENSE

+MIT License
+
+Copyright (c) 2022 Nicolas Lenz (https://git.eisfunke.com/document/pandoc-template/article)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

-# article
+# Pandoc Template: Report
 
+This is a template for building articles using Markdown and Pandoc, mainly meant for usage as a git submodule. It is also suitable for things like university assignments or general documents.
+
+Note that this is not as well tested as [my other templates](https://git.eisfunke.com/document/pandoc-template) and still evolving.
+
+## Requirements
+
+You need the following software installed:
+
+- Pandoc
+- `pandoc-crossref`
+- LuaLaTeX
+- `make`
+- These fonts:
+  - [Libertinus](https://github.com/alerque/libertinus)
+  - [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/report/-/archive/main/article-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/article.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/article 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
+└── template
+    └── … the contents of this repo
+```
+
+You can either:
+
+- create a single document from all your source files concatenated with `make -f template/makefile article.pdf`, it will be written to the file `article.pdf`;
+- create one document for each source file with `make -f template/makefile multipdf`, the output files will be in the folder `out`.
+
+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-title: ed6c00  # hex code for background color of the title page, this is the default
+color-example: ed6c00  # hex code for example boxes, this is the default
+color-definition: 483d8b  # hex code for definition boxes, this is the default
+color-listing: 2e8b57  # hex code for listing boxes, this is the default
+logo: logofile.png  # logo image file, will be shown on the title page
+author: Nicolas Lenz  # author for the title page
+date: 2022-04-28  # date for the title page
+draft: false  # inserts a draft watermarks and show a note on the title page with the compilation time.
+updated: false  # inserts a note on the title page that this is an updated version with the compilation time.
+institute: |  # institute for the title page
+  Line One
+
+  Line Two
+disclaimer: |  # will be shown after the table of contents
+  Line One
+
+  Line Two
+
+flake: false  # enables a snowflake in the background on the title page, 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 report 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/article/-/raw/main/build.gitlab-ci.yml
+  - remote: https://git.eisfunke.com/document/pandoc-template/article/-/raw/main/pages.gitlab-ci.yml
+```

build.gitlab-ci.yml

+variables:
+  TEMPLATE_MODE: single
+
+build-single:
+  rules:
+    - if: $TEMPLATE_MODE == "single"
+  stage: build
+  image: registry.eisfunke.com/software/container/pandoc-plus:latest
+  variables:
+    GIT_SUBMODULE_STRATEGY: recursive
+  script:
+    - make -f template/makefile article.pdf article.tex
+  artifacts:
+    paths:
+      - article.pdf
+      - article.tex
+
+build-multi:
+  rules:
+    - if: $TEMPLATE_MODE == "muilti"
+  stage: build
+  image: registry.eisfunke.com/software/container/pandoc-plus:latest
+  variables:
+    GIT_SUBMODULE_STRATEGY: recursive
+  script:
+    - make -f template/makefile multipdf multitex
+  artifacts:
+    paths:
+      - out/

div-to-env.lua

+--[[
+take a table of key-value-pairs/attributes and create a string with
+`{foo}={bar}, ` for each of them to be used as arguments in the \begin command
+--]]
+local function attributes_to_string(attributes)
+    local result = ""
+    for k,v in pairs(attributes) do
+        result = result .. string.format("{%s}={%s}, ", k, v)
+    end
+    if result ~= "" then
+        result = string.format("{%s}", result)
+    end
+    return result
+end
+
+-- if the identifier is not empty, wrap it in square brackets
+local function identifier_to_string(identifier)
+    if identifier ~= "" then
+        return string.format("[%s]", identifier)
+    else
+        return ""
+    end
+end
+
+-- convert divs to LaTeX environments
+function Div(div)
+    -- ignore info divs, so they can be used somewhat like comments
+    if div.classes[1] == "info" then
+        return pandoc.Null()
+    end
+
+    local result = {}
+
+    -- for each class insert a \begin{foo} command
+    for i = 1, #(div.classes) do
+        table.insert(result,
+            pandoc.RawBlock("latex", string.format
+                ( "\\begin{%s}%s%s"
+                , div.classes[i]
+                , identifier_to_string(div.identifier)
+                , attributes_to_string(div.attributes)
+                )
+            )
+        )
+    end
+
+    -- insert the original content of the div
+    for _,block in ipairs(div.content) do
+        table.insert(result, block)
+    end
+
+    -- for each class insert a \end{foo} command, in reverse order
+    for i = #(div.classes), 1, -1 do
+        table.insert(result,
+            pandoc.RawBlock("latex", string.format("\\end{%s}", div.classes[i]))
+        )
+    end
+
+    return result
+end

macros.tex

+\DeclareMathOperator{\bnfdef}{\hspace{1mm}\vcentcolon\vcentcolon=\hspace{1mm}}
+\DeclareMathOperator{\bnfalt}{\hspace{1mm}\makebox[\widthof{$\vcentcolon\vcentcolon=$}]{$\mid$}\hspace{1mm}}
+\newcommand{\eval}{\Downarrow}
+\newcommand{\typecheck}{:_\shortleftarrow}
+\newcommand{\typeinfer}{:_\shortrightarrow}
+\newcommand{\cmark}{✔}
+\newcommand{\xmark}{✘}
+\newcommand{\trr}{\triangleright}
+\newcommand{\blank}{\sqcup}
+\newcommand{\atom}{\mathbb{A}}
+\newcommand{\universe}{\mathbb{U}}
+\newcommand{\type}{\mathbb{T}}
+\newcommand{\nat}{\mathbb{N}}
+\newcommand{\defeq}{\mathrel{\overset{\makebox[0pt]{\mbox{\normalfont\tiny\sffamily def}}}{=}}}
+\newcommand{\lp}{λ\textsubscript{Π}\xspace}
+\newcommand{\ls}{λ\textsubscript{$\shortrightarrow$}\xspace}

makefile

+inputs = $(shell ls src/*.md)  # $(wildcard src/*.md) outputs in the wrong order
+resources_file = $(wildcard res/*)
+template_files = template/template.tex template/macros.tex template/style.csl template/div-to-env.lua
+metadata_file = $(wildcard metadata.yaml)  # if there's a metadata.yaml, use it as metadata file
+bibliography = $(wildcard literature.bib)  # if there's a literature.bib, use it as bibliography
+
+pandoc = pandoc -f markdown --pdf-engine=lualatex \
+--template template/template.tex --lua-filter template/div-to-env.lua \
+--filter pandoc-crossref --citeproc --csl template/style.csl -M link-citations:true
+
+ifneq ($(strip $(metadata_file)),)  # if metadata is non-empty, add it to the pandoc command
+pandoc += --metadata-file metadata.yaml
+endif
+
+ifneq ($(strip $(bibliography_file)),)  # if bibliography is non-empty, add it to the pandoc command
+pandoc += --bibliography literature.bib
+endif
+
+
+# the FORBIDDEN parser retrieves the value of the value multi in the metadata.yaml file
+multi = $(shell grep -m1 -E "^multi" metadata.yaml | sed 's/^multi: //')
+
+ifeq ($(multi), true)
+all: multipdf
+else
+all: article.pdf
+endif
+
+
+# Rules for building a single documents from all source files concatenated
+
+article.pdf: $(inputs) $(metadata_file) $(bibliography_file) $(template_files) $(resources)
+	$(pandoc) -t pdf   -o $@ $(inputs)
+
+article.tex: $(inputs) $(metadata_file) $(bibliography_file) $(template_files)
+	$(pandoc) -t latex -o $@ $(inputs)
+
+
+# Rules for building multiple documents, one for each source file
+
+multipdf: $(patsubst src/%.md, out/%.pdf, $(inputs))
+multitex: $(patsubst src/%.md, out/%.tex, $(inputs))
+
+out/%.pdf: src/%.md $(metadata_file) $(bibliography_file) $(template_files) $(resources) | out
+	$(pandoc) -t pdf   -o $@ $<
+
+out/%.tex: src/%.md $(metadata_file) $(bibliography_file) $(template_files) | out
+	$(pandoc) -t latex -o $@ $<
+
+out:
+	mkdir -p out
+
+
+clean:
+	rm -rf article.pdf article.tex out
+
+.PHONY: all multipdf multitex clean test

pages.gitlab-ci.yml

+variables:
+  TEMPLATE_MODE: single
+  OUTPUT_NAME: article
+
+pages-single:
+  rules:
+    - if: $TEMPLATE_MODE == "single"
+  stage: deploy
+  image: docker.io/alpine:latest
+  script:
+    - mkdir public
+    - mv report.pdf public/$OUTPUT_NAME.pdf
+    - mv report.tex public/$OUTPUT_NAME.tex
+  artifacts:
+    paths:
+      - public
+  only:
+    - main
+
+pages-multi:
+  rules:
+    - if: $TEMPLATE_MODE == "multi"
+  stage: deploy
+  image: docker.io/alpine:latest
+  script:
+    - mv out public
+  artifacts:
+    paths:
+      - public
+  only:
+    - main

style.csl

+<?xml version="1.0" encoding="utf-8"?>
+<style xmlns="http://purl.org/net/xbiblio/csl" class="in-text" version="1.0" demote-non-dropping-particle="sort-only">
+  <info>
+    <title>IEEE (with URL)</title>
+    <id>http://www.zotero.org/styles/ieee-with-url</id>
+    <link href="http://www.zotero.org/styles/ieee-with-url" rel="self"/>
+    <link href="https://ieeeauthorcenter.ieee.org/wp-content/uploads/IEEE-Reference-Guide.pdf" rel="documentation"/>
+    <link href="https://journals.ieeeauthorcenter.ieee.org/your-role-in-article-production/ieee-editorial-style-manual/" rel="documentation"/>
+    <author>
+      <name>Michael Berkowitz</name>
+      <email>mberkowi@gmu.edu</email>
+    </author>
+    <contributor>
+      <name>Julian Onions</name>
+      <email>julian.onions@gmail.com</email>
+    </contributor>
+    <contributor>
+      <name>Rintze Zelle</name>
+      <uri>http://twitter.com/rintzezelle</uri>
+    </contributor>
+    <contributor>
+      <name>Stephen Frank</name>
+      <uri>http://www.zotero.org/sfrank</uri>
+    </contributor>
+    <contributor>
+      <name>Sebastian Karcher</name>
+    </contributor>
+    <category citation-format="numeric"/>
+    <category field="engineering"/>
+    <category field="generic-base"/>
+    <summary>IEEE style with URLs as per the 2018 guidelines, V 11.12.2018.</summary>
+    <updated>2019-12-21T00:36:11+00:00</updated>
+    <rights license="http://creativecommons.org/licenses/by-sa/3.0/">This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License</rights>
+  </info>
+  <locale xml:lang="en">
+    <terms>
+      <term name="chapter" form="short">ch.</term>
+      <term name="presented at">presented at the</term>
+      <term name="available at">available</term>
+    </terms>
+  </locale>
+  <!-- Macros -->
+  <macro name="edition">
+    <choose>
+      <if type="bill book chapter graphic legal_case legislation motion_picture paper-conference report song" match="any">
+        <choose>
+          <if is-numeric="edition">
+            <group delimiter=" ">
+              <number variable="edition" form="ordinal"/>
+              <text term="edition" form="short"/>
+            </group>
+          </if>
+          <else>
+            <text variable="edition" text-case="capitalize-first" suffix="."/>
+          </else>
+        </choose>
+      </if>
+    </choose>
+  </macro>
+  <macro name="issued">
+    <choose>
+      <if type="article-journal report" match="any">
+        <date variable="issued">
+          <date-part name="month" form="short" suffix=" "/>
+          <date-part name="year" form="long"/>
+        </date>
+      </if>
+      <else-if type="bill book chapter graphic legal_case legislation motion_picture paper-conference song thesis" match="any">
+        <date variable="issued">
+          <date-part name="year" form="long"/>
+        </date>
+      </else-if>
+      <else>
+        <date variable="issued">
+          <date-part name="day" form="numeric-leading-zeros" suffix="-"/>
+          <date-part name="month" form="short" suffix="-" strip-periods="true"/>
+          <date-part name="year" form="long"/>
+        </date>
+      </else>
+    </choose>
+  </macro>
+  <macro name="author">
+    <names variable="author">
+      <name and="text" et-al-min="7" et-al-use-first="1" initialize-with=". "/>
+      <label form="short" prefix=", " text-case="capitalize-first"/>
+      <et-al font-style="italic"/>
+      <substitute>
+        <names variable="editor"/>
+        <names variable="translator"/>
+      </substitute>
+    </names>
+  </macro>
+  <macro name="editor">
+    <names variable="editor">
+      <name initialize-with=". " delimiter=", " and="text"/>
+      <label form="short" prefix=", " text-case="capitalize-first"/>
+    </names>
+  </macro>
+  <macro name="locators">
+    <group delimiter=", ">
+      <text macro="edition"/>
+      <group delimiter=" ">
+        <text term="volume" form="short"/>
+        <number variable="volume" form="numeric"/>
+      </group>
+      <group delimiter=" ">
+        <number variable="number-of-volumes" form="numeric"/>
+        <text term="volume" form="short" plural="true"/>
+      </group>
+      <group delimiter=" ">
+        <text term="issue" form="short"/>
+        <number variable="issue" form="numeric"/>
+      </group>
+    </group>
+  </macro>
+  <macro name="title">
+    <choose>
+      <if type="bill book graphic legal_case legislation motion_picture song" match="any">
+        <text variable="title" font-style="italic"/>
+      </if>
+      <else>
+        <text variable="title" quotes="true"/>
+      </else>
+    </choose>
+  </macro>
+  <macro name="publisher">
+    <choose>
+      <if type="bill book chapter graphic legal_case legislation motion_picture paper-conference song" match="any">
+        <group delimiter=": ">
+          <text variable="publisher-place"/>
+          <text variable="publisher"/>
+        </group>
+      </if>
+      <else>
+        <group delimiter=", ">
+          <text variable="publisher"/>
+          <text variable="publisher-place"/>
+        </group>
+      </else>
+    </choose>
+  </macro>
+  <macro name="event">
+    <choose>
+      <if type="paper-conference speech" match="any">
+        <choose>
+          <!-- Published Conference Paper -->
+          <if variable="container-title">
+            <group delimiter=", ">
+              <group delimiter=" ">
+                <text term="in"/>
+                <text variable="container-title" font-style="italic"/>
+              </group>
+              <text variable="event-place"/>
+            </group>
+          </if>
+          <!-- Unpublished Conference Paper -->
+          <else>
+            <group delimiter=", ">
+              <group delimiter=" ">
+                <text term="presented at"/>
+                <text variable="event"/>
+              </group>
+              <text variable="event-place"/>
+            </group>
+          </else>
+        </choose>
+      </if>
+    </choose>
+  </macro>
+  <macro name="access">
+    <choose>
+      <if variable="URL">
+        <group delimiter=". ">
+          <group delimiter=": ">
+            <text term="available at" text-case="capitalize-first"/>
+            <text variable="URL"/>
+          </group>
+          <group prefix="[" suffix="]" delimiter=": ">
+            <text term="accessed" text-case="capitalize-first"/>
+            <date variable="accessed">
+              <date-part name="day" form="numeric-leading-zeros" suffix="-"/>
+              <date-part name="month" form="short" suffix="-" strip-periods="true"/>
+              <date-part name="year" form="long"/>
+            </date>
+          </group>
+        </group>
+      </if>
+    </choose>
+  </macro>
+  <macro name="page">
+    <group>
+      <label variable="page" form="short" suffix=" "/>
+      <text variable="page"/>
+    </group>
+  </macro>
+  <macro name="citation-locator">
+    <group delimiter=" ">
+      <choose>
+        <if locator="page">
+          <label variable="locator" form="short"/>
+        </if>
+        <else>
+          <label variable="locator" form="short" text-case="capitalize-first"/>
+        </else>
+      </choose>
+      <text variable="locator"/>
+    </group>
+  </macro>
+  <macro name="doi">
+    <text variable="DOI" prefix="doi: "/>
+  </macro>
+  <!-- Citation -->
+  <citation collapse="citation-number">
+    <sort>
+      <key variable="citation-number"/>
+    </sort>
+    <layout delimiter=", ">
+      <group prefix="[" suffix="]" delimiter=", ">
+        <text variable="citation-number"/>
+        <text macro="citation-locator"/>
+      </group>
+    </layout>
+  </citation>
+  <!-- Bibliography -->
+  <bibliography entry-spacing="0" second-field-align="flush">
+    <layout>
+      <!-- Citation Number -->
+      <text variable="citation-number" prefix="[" suffix="]"/>
+      <!-- Author(s) -->
+      <text macro="author" suffix=", "/>
+      <!-- Rest of Citation -->
+      <group suffix=". ">
+        <choose>
+          <!-- Specific Formats -->
+          <if type="article-journal">
+            <group delimiter=", ">
+              <text macro="title"/>
+              <text variable="container-title" font-style="italic" form="short"/>
+              <text macro="locators"/>
+              <text macro="page"/>
+              <text macro="issued"/>
+              <text macro="doi" suffix="."/>
+            </group>
+          </if>
+          <else-if type="paper-conference">
+            <group delimiter=", ">
+              <text macro="title"/>
+              <text macro="event"/>
+              <text macro="issued"/>
+              <text macro="locators"/>
+              <text macro="page"/>
+              <text macro="doi"/>
+            </group>
+          </else-if>
+          <else-if type="report">
+            <group delimiter=", ">
+              <text macro="title"/>
+              <text macro="publisher"/>
+              <group delimiter=" ">
+                <text variable="genre"/>
+                <text variable="number"/>
+              </group>
+              <text macro="issued"/>
+            </group>
+          </else-if>
+          <else-if type="thesis">
+            <group delimiter=", ">
+              <text macro="title"/>
+              <text variable="genre"/>
+              <text macro="publisher"/>
+              <text macro="issued"/>
+            </group>
+          </else-if>
+          <else-if type="webpage post post-weblog" match="any">
+            <group delimiter=", " suffix=". ">