MGEP TFG template for pandoc

A Markdown → PDF template for the Bachelor's Degree Final Project (TFG / GrAL / FDP) of Mondragon Unibertsitatea, Escuela Politécnica Superior. It reproduces the layout of the official Word templates (MGEPTFGPlantillaES.docx, MGEPGBLTxantiloiaEU.docx, MGEPFDPTemplateEN.docx): cover and back cover, declaration and licence page, three abstracts, indices, chapter and section typography, running heads, annexes with A-1 pagination and their own indices.

You write the thesis in Markdown (report.<lang>.md), keep the references in a BibTeX file, and build.sh (or build.ps1 on Windows) produces the PDF with pandoc and XeLaTeX.

Requirements

• pandoc ≥ 3.1.8 (tested with every release from 3.1.8 to 3.11). Older releases fail inside xelatex with "Something's wrong--perhaps a missing \item" or "Undefined control sequence \cslentryspacing": the LaTeX that citeproc emits for the bibliography changed in 3.1.7/3.1.8 and mgep.latex targets the new form. Debian 12 (2.17) and Ubuntu 24.04 (3.1.3) package a pandoc that is too old; install the .deb or the Windows installer from https://github.com/jgm/pandoc/releases.

• TeX Live with XeLaTeX and the following packages: fontspec, polyglossia, geometry, setspace, graphicx, longtable, booktabs, amsmath, xcolor, etoolbox, caption, float, titlesec, titletoc, fancyhdr, emptypage, hyperref, cleveref, eso-pic, textpos, ccicons, tcolorbox, and the fonts Latin Modern and TeX Gyre Heros. On Debian/Ubuntu:

  sudo apt install texlive-xetex texlive-latex-extra texlive-fonts-recommended \
                   texlive-fonts-extra texlive-lang-spanish texlive-lang-european \
                   texlive-lang-french
  

  (texlive-fonts-extra provides ccicons, the Creative Commons badge. Debian and Ubuntu ship the Basque hyphenation patterns in texlive-lang-french, not in texlive-lang-european; without that package the Basque build compiles but polyglossia warns "No hyphenation patterns were loaded for `basque'" and the text is justified without hyphenation.)

Building

./build.sh            # English: report.en.md  → out/report.en.pdf
./build.sh es         # Spanish: report.es.md  → out/report.es.pdf
./build.sh eu         # Basque:  report.eu.md  → out/report.eu.pdf
./build.sh es tesis.md   # any Markdown file, with the Spanish interface strings

The sample reports do not build as they are: the build stops until you have filled in the two fields of the rights page in the front matter (university-authorisation and license), as explained under Metadata below.

build.sh runs on Linux, macOS and Windows under Git Bash. Windows users can also use the PowerShell script, which takes the same arguments:

.\build.ps1
.\build.ps1 es
.\build.ps1 es tesis.md

If Windows refuses to run it ("running scripts is disabled on this system"), start it with powershell -ExecutionPolicy Bypass -File .\build.ps1 es. On Windows, pandoc and a TeX distribution (MiKTeX or TeX Live) must be on the PATH; MiKTeX installs the missing LaTeX packages on the first run.

The first argument selects i18n/<lang>.yaml (the language of the interface: "Capítulo", "Índice de contenidos", the declaration text, …). The second is the Markdown source; it defaults to report.<lang>.md.

Files

File	Purpose
report.{en,es,eu}.md	Sample thesis in each language, with the official placeholder text. Copy one and start writing.
mgep.latex	The pandoc LaTeX template. Language-independent.
i18n/{en,es,eu}.yaml	Interface strings and per-language LaTeX settings.
metadata.lua	pandoc filter that stops the build when a required field of the rights page is missing.
annexes.lua	pandoc filter that marks where the annexes begin.
bibliography.bib, ieee.csl	Sample references and the IEEE citation style used by the university.
assets/	Cover and back-cover images (one pair per language), the sample figure and the annex placeholder images (annex-figure.<lang>.png, regenerated with annex-placeholder.sh and ImageMagick).
build.sh, build.ps1	Build scripts (bash and PowerShell). Output goes to out/.

Writing the thesis

Metadata (YAML header)

The block at the top of report.<lang>.md holds everything that appears on the cover, the declaration page and the front matter.

Required:

Field	Where it appears
title, title-upper	Cover (title) and declaration page (title-upper, in capitals).
author, author-name, author-surname, author-full	PDF metadata; cover and declaration page ("Surname1 Surname2, Name"); declaration ("I, Name Surname1 Surname2").
academic-year, degree	Cover and declaration page.
director, tutor, organization, defense-place, defense-date	Declaration page.
abstract-en, keywords-en, sdg-en, and the same with -es and -eu	The three abstracts, always required in the three languages.
university-authorisation	true prints the paragraph authorising the university to reproduce the work (box 1 of the Word template); false omits it. The build stops if the field is missing.
license	Licence text (Markdown) on the declaration page. The sample reports carry the official CC BY-NC-SA wording and a CC BY-SA example, both commented out: uncomment one or write your own. The build stops if the field is missing.

Optional (delete the line to omit the element):

Field	Effect
cover-image, back-cover-image	Full-page background images (the official artwork in assets/). Without cover-image the cover is set in black on a plain white page.
license-badge	ccicons badge printed next to the licence text (ccby, ccbysa, ccbync, ccbyncsa, ccbynd, ccbyncnd, cczero).
dedication	Dedication page.
acknowledgements	"Acknowledgements" chapter.
symbols	"Symbols and abbreviations" chapter (Markdown).
bibliography, csl	Enable citeproc with the given .bib and .csl files.
mainfont	Body font (default Latin Modern Roman).

Body

• # is a chapter, ## a section, ### a subsection. Numbering, indices and running heads are automatic.
• Cite with [@key]; the bibliography is printed where you put an unnumbered chapter (# Bibliography {-}) followed by ::: {#refs} / :::.
• Figures: ![Caption](file.png){#fig:id height="20%"}; refer to them with \cref{fig:id} ("figura 1.1"). Tables: a pipe table followed by : Caption. \label{tab:id}, referred to with \cref{tab:id}. Figures and tables are placed exactly where they are written, as in Word.
• Annexes: write a single heading # Annexes {.annexes} (any text, the label comes from the i18n file). Every # heading after it is an annex: they are lettered automatically ("Annex A"), paginated A-1, A-2, …, their figures and tables are labelled "Annex Figure A.1", and they get their own indices after the "ANNEXES" separator page plus a "List of Annexes" in the front matter. If the thesis has no annexes, simply leave the heading out.

Adding a language

1. Copy i18n/es.yaml to i18n/<code>.yaml and translate the values under str:. Every key must be present.
2. Set lang (BCP 47, used by citeproc), polyglossia-main / polyglossia-other, cleveref-lang and abstract-order (the official templates put the document's language first).
3. If cleveref or polyglossia lack the language, or the label order differs ("1. kapitulua" instead of "Capítulo 1"), add the LaTeX in latex-extra; i18n/eu.yaml is the worked example.
4. Copy a report.*.md to report.<code>.md and build with ./build.sh <code>.

mgep.latex does not need to be edited.

Differences from the Word templates

Blank verso pages are inserted so that chapters, the table of contents and the body start on a right-hand page, and the back cover lands on a left-hand page; this matches the odd/even section breaks of the Word templates. The stock checklist icon of Figure 1.2 in the Word sample is not reproduced (it is not freely licensed), so the sample has four references instead of five.

Licence

The template (mgep.latex, metadata.lua, annexes.lua, the build scripts, the i18n files and the sample reports) is released under CC BY-SA 4.0 with the attribution requirements waived: you may copy, modify and redistribute it without crediting the author or linking back here. Theses produced with the template are not derivative works of it and are not affected by its licence. The cover artwork belongs to Mondragon Unibertsitatea. See LICENSE.md for the details and for the exact clauses waived.