{"id":13761096,"url":"https://github.com/cagix/pandoc-lecture","last_synced_at":"2026-02-26T12:40:44.483Z","repository":{"id":13551685,"uuid":"67802199","full_name":"cagix/pandoc-lecture","owner":"cagix","description":"Pandoc Markdown Lecture Template: This project defines a skeleton repo for creating lecture slides and handouts including lecture notes out of Pandoc Markdown (https://pandoc.org/MANUAL.html) using a single source approach.","archived":false,"fork":false,"pushed_at":"2025-11-21T14:46:17.000Z","size":880,"stargazers_count":103,"open_issues_count":41,"forks_count":18,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-13T19:49:26.196Z","etag":null,"topics":["exams","hacktoberfest","handouts","homework-sheets","latex","lecture-notes","lecture-slides","markdown","oer","open-educational-resources","pandoc","pandoc-filter","pandoc-lecture","teaching-materials"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cagix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-09-09T13:42:21.000Z","updated_at":"2026-01-16T04:18:32.000Z","dependencies_parsed_at":"2024-03-16T13:54:31.206Z","dependency_job_id":"af993b8d-a061-4c09-8689-7e10e51b9f3c","html_url":"https://github.com/cagix/pandoc-lecture","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/cagix/pandoc-lecture","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cagix%2Fpandoc-lecture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cagix%2Fpandoc-lecture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cagix%2Fpandoc-lecture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cagix%2Fpandoc-lecture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cagix","download_url":"https://codeload.github.com/cagix/pandoc-lecture/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cagix%2Fpandoc-lecture/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29859231,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T08:51:08.701Z","status":"ssl_error","status_checked_at":"2026-02-26T08:50:19.607Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["exams","hacktoberfest","handouts","homework-sheets","latex","lecture-notes","lecture-slides","markdown","oer","open-educational-resources","pandoc","pandoc-filter","pandoc-lecture","teaching-materials"],"created_at":"2024-08-03T13:01:38.135Z","updated_at":"2026-02-26T12:40:43.687Z","avatar_url":"https://github.com/cagix.png","language":"Lua","funding_links":[],"categories":["Lua"],"sub_categories":[],"readme":"---\ntitle: \"Pandoc Markdown Lecture Template\"\n---\n\nThis project defines a skeleton repo for creating lecture material, i.e. slides and\nhandouts including lecture notes, homework sheets plus the corresponding evaluation\nsheets and exams plus solution sheets out of [Pandoc Markdown](http://pandoc.org/MANUAL.html)\nusing a single source approach.\n\n\n# History\n\n## Slides and Handouts\n\nOriginally [TeX Live](https://www.tug.org/texlive/) and the\n[beamer class](https://www.ctan.org/pkg/beamer) were used to produce\nslides in PDF format for lecture. A nice handout as article (i.e. not\njust 2 or 4 slides on a page) in PDF format with additional comments\ncould easily be generated out of the slide source code by adding the\n`\\usepackage{beamerarticle}` option.\n\nHowever, there are a few drawbacks:\n\n*   The TeX overhead is particularly high in this scenario: estimated 50 to 80\n    percent of the slides source code is just TeX code (defining slides and\n    header, defining bullet point lists, ...).\n*   Comments, that should appear in the handout, are limited. There is a\n    `\\note` command available in `beamer`, but using it for larger texts\n    including code listings and headers is rather inconvenient or even\n    impossible.\n*   Most students would read the handout using a tablet or an e-book reader,\n    so PDF is not really a suitable format for handouts. HTML or even EPUB\n    would be a much more appropriate choice for this task. There are a number\n    of projects addressing this (e.g. [LaTeX2HTML](http://www.latex2html.org/),\n    [Hyperlatex](http://hyperlatex.sourceforge.net/), [TeX4ht](http://www.tug.org/tex4ht/)),\n    but the resulting HTML is not really satisfying, and EPUB generation\n    is not even supported.\n\nUsing [Pandoc Markdown](http://pandoc.org/MANUAL.html) most of the standard\nTeX structures can be written in a much shorter way. Since Pandoc does not\nparse Markdown contained in TeX environments, all `\\begin{XXX}` and `\\end{XXX}`\ncommands need to be replaced using redefinitions like\n`\\newcommand{\\XXXbegin}{\\begin{XXX}}`.\n\nAlso by introducing a notes block/inline (using fenced Divs, new in Pandoc 2.x)\nin combination with a custom Pandoc filter, the lecture notes can be placed\nfreely at any location in the material. Using the filter the lecture notes do\nnot appear in the slides but in the handout. The lecture notes can contain any\nvalid Markdown or TeX code, even further (sub-) sections.\n\nPandoc can convert Markdown also to HTML and EPUB. Thus a single source can\nbe used to create lecture slides (PDF) and handouts (HTML/EPUB). Even slide\ndesks in HTML using e.g. [reveal.js](http://lab.hakim.se/reveal-js/) would\nbe possible.\n\n## Homework Sheets\n\nOriginally [TeX Live](https://www.tug.org/texlive/) and the\n[exam class](https://www.ctan.org/pkg/exam) were used to produce\nhomework sheets in PDF format.\n\nHowever, there are a few drawbacks:\n\n*   The overhead stemming from the `exam` class is quite high in this scenario.\n*   Generating an evaluation sheet from the homework sheet is not supported by\n    the `exam` class.\n\nMuch of the code required by the `exam` class (and also quite some TeX code)\ncan be omitted by using [Pandoc Markdown](http://pandoc.org/MANUAL.html). Thus\nthe homework sheets can be written in a much simpler way, saving quite some time.\n\nDeriving an evaluation sheet from the homework sheet can be done by using\nPandoc in combination with a customised template.\n\nA Pandoc filter adds up all points (like the functionality provided\nby the `exam` class).\n\nSince LaTeX is still used as back end, all TeX macros could be used.\n\n## Exams\n\nOriginally [TeX Live](https://www.tug.org/texlive/) and the\n[exam class](https://www.ctan.org/pkg/exam) were used to produce\nexams and corresponding solution sheets in PDF format.\n\nUsing [Pandoc Markdown](http://pandoc.org/MANUAL.html) the task of\ncreating exams with the `exam` class can be simplified.\nSince LaTeX is still used as back end, all TeX macros could be used.\n\n\n# Installing and using Pandoc-Lecture\n\nThe project [Pandoc-Lecture](https://github.com/cagix/pandoc-lecture) defines a toolchain to generate slides (in PDF format) as well as a website for teaching material from a set of Markdown files. For each unit, the PDF and the HTML page are generated from the same Markdown file:\n\n*   The slide sets (as PDF slide sets) are produced from the Markdown sources with [Pandoc](https://pandoc.org/) plus the [filters](https://github.com/cagix/pandoc-lecture/tree/master/filters), [definitions](https://github.com/cagix/pandoc-lecture/tree/master/resources) and [defaults](https://github.com/cagix/pandoc-lecture/tree/master/defaults) defined in [Pandoc-Lecture](https://github.com/cagix/pandoc-lecture) and with [TexLive](https://tug.org/texlive/).\n\n*   The teaching material (as a website) is produced from the Markdown sources using [Pandoc](https://pandoc.org/) and the [filters](https://github.com/cagix/pandoc-lecture/tree/master/filters), [definitions](https://github.com/cagix/pandoc-lecture/tree/master/resources) and [defaults](https://github.com/cagix/pandoc-lecture/tree/master/defaults) defined in [Pandoc-Lecture](https://github.com/cagix/pandoc-lecture) as well as with [Hugo](https://gohugo.io/) and the [Hugo Relearn-Theme](https://github.com/McShelby/hugo-theme-relearn). The generated website can be deployed e.g. as a _HTML Learning Module_ in the LMS _ILIAS_.\n\nAll required tools are specified in the various installation scripts in the folder [cagix/pandoc-lecture/docker/](https://github.com/cagix/pandoc-lecture/tree/master/docker).\n\nThere are three ways to use the toolchain defined by the [Pandoc-Lecture project](https://github.com/cagix/pandoc-lecture):\n\n*   [Option A](#option-a-online-via-github-action): Online via GitHub action\n*   [Option B](#option-b-locally-via-docker-container): Locally via Docker container\n*   [Option C](#option-c-locally-via-native-installation): Locally via native installation\n\nInstallation and usage in these scenarios is described in the following sections.\n\n## Option A: Online via GitHub action\n\nYou need a suitable build script, e.g. a Makefile, to apply Pandoc and the other tools to your Markdown files. Additionally, you need a GitHub workflow that utilises this Makefile and the [_composite_ GitHub-Action](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) defined in the Pandoc-Lecture project ([action.yaml](https://github.com/cagix/pandoc-lecture/blob/master/action.yaml)).\n\n### Build Script\n\nYou can use your favourite build script technology. In this example we will demonstrate how to use a Makefile. The following code snippet shows two targets `web` and `slides` for calling Hugo and Pandoc, respectively. This example is quite abbreviated, you will find the complete (and working) text in [Programmiermethoden-CampusMinden/Prog2-Lecture/Makefile](https://github.com/Programmiermethoden-CampusMinden/Prog2-Lecture/blob/master/Makefile).\n\nTo produce the teaching material as a website, invoke `make web`; and to produce the PDF slide sets, use `make slides`:\n\n```makefile\n## Create website\nweb: ...\n\thugo $(HUGO_ARGS)\n\n## Create all slides\nslides: ...\n\tpandoc -d beamer $\u003c -o $@\n```\n\n### GitHub Workflow\n\nTo use your build script and the tools in a CI/CD pipeline on the GitHub runner for producing the teaching materials, you need to define a suitable [GitHub workflow](https://docs.github.com/en/actions/using-workflows). This workflow will first install the required tools using the [_composite_ GitHub-Action](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) in [action.yaml](https://github.com/cagix/pandoc-lecture/blob/master/action.yaml), and afterwards you can call your own build script from the workflow steps.\n\nOur [action](https://github.com/cagix/pandoc-lecture/blob/master/action.yaml) will install Pandoc and Pandoc-Lecture in the GitHub runner. If the option `hugo` is set to `'true'` (string!), Hugo and Hugo Relearn theme will also be installed. If the option `texlive` is set to `'true'` (string!), TexLive will be installed along with all the packages needed to produce the Beamer PDF slides. If instead of `'true'` the value `'extra'` is given, additional packages such as additional fonts will be installed (cf. [docker/install-texlive-extra.sh](https://github.com/cagix/pandoc-lecture/blob/master/docker/install-texlive-extra.sh)) - however, this requires _significantly_ more space and time during installation! With the option `graphviz` (value `'true'`, string!) you can also install [GraphViz](https://graphviz.org/) and [Dot](https://graphviz.org/doc/info/lang.html).\n\nHere is an example workflow for your project with one job each for the production of the beamer PDF slides and the website for the teaching materials:\n\n```yaml\nname: WORKFLOWNAME\non:\n  # push on master branch\n  push:\n    branches: [master]\n  # manually triggered\n  workflow_dispatch:\n\njobs:\n  # build slides (pandoc): \"make slides\"\n  slides:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - uses: cagix/pandoc-lecture@master\n        with:\n          texlive: 'true'\n      - run: make slides\n\n      - uses: peaceiris/actions-gh-pages@v3\n        with:\n          github_token: ${{ secrets.GITHUB_TOKEN }}\n          publish_branch: _slides\n          publish_dir: pdf/\n          force_orphan: true\n\n  # build lecture notes (hugo): \"make web\"\n  hugo:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - uses: cagix/pandoc-lecture@master\n        with:\n          hugo: 'true'\n      - run: make web\n\n      - uses: peaceiris/actions-gh-pages@v3\n        with:\n          github_token: ${{ secrets.GITHUB_TOKEN }}\n          publish_branch: _hugo\n          publish_dir: docs/\n          force_orphan: true\n```\n\nUsually, this workflow has to be saved as a YAML file \"`WORKFLOWNAME.yaml`\" in the `.github/workflows/` folder of your project (use an appropriate name for your file). Once pushed to your repository, the workflow will be automatically activated as a CI/CD pipeline on the GitHub server by the defined triggers (in this example, if changes are made to the `master` branch, or if it is manually triggered in the menu `Actions \u003e WORKFLOWNAME \u003e Run Workflow`). The slides created will be available in the `_slides` branch, the teaching materials created in the `_hugo` branch. (_Note_: Both branches will be overwritten the next time you run the workflow).\n\nDepending on your settings, the [\"cagix/pandoc-lecture\"](https://github.com/cagix/pandoc-lecture) GitHub action must be enabled for your repository: `Settings \u003e Actions \u003e General \u003e Action permissions`.\n\n## Option B: Locally via Docker container\n\nFor local use, the [Docker image](https://github.com/cagix/pandoc-lecture/blob/master/docker/Dockerfile) defined in the project can be used. You'll need to build this Docker image, also you'll need a suitable build script, e.g. a Makefile.\n\n### Building the Docker Image\n\nTo create the image with the name `pandoc-lecture`, just clone the project locally, navigate to the sub-folder `docker/` and create the Docker image for your architecture via the provided Makefile. For Intel machines this will be the `amd64` target, for Apple M1 (also M2 and other ARM-based machines) accordingly `arm64`:\n\n```sh\ngit clone https://github.com/cagix/pandoc-lecture.git\ncd pandoc-lecture/\n# Use either of the following steps\nmake amd64  # Intel\nmake arm64  # Apple M1/M2/M3, ARM\n```\n\nOnce the image has been created, the `pandoc-lecture/` folder can be deleted. To renew the image, e.g. after updating the definitions, the above steps have to be repeated.\n\n### Working with the Docker Image\n\nThe entire toolchain is available in the Docker image named `pandoc-lecture`. To work with the toolchain, the Docker image needs to be launched and the local working directory has to be mounted into the container. An interactive shell inside the container can be used to access the mounted files and the toolchain in the container from there.\n\nHere is an example of a Makefile for your local project (excerpt from [Programmiermethoden-CampusMinden/Prog2-Lecture/Makefile](https://github.com/Programmiermethoden-CampusMinden/Prog2-Lecture/blob/master/Makefile), shortened):\n\n```makefile\n## Start Docker container \"pandoc-lecture\" into interactive shell\nrunlocal:\n\tdocker run  --rm -it  -v \"$(shell pwd):/pandoc\" -w \"/pandoc\"  -u \"$(shell id -u):$(shell id -g)\"  --entrypoint \"bash\"  pandoc-lecture\n\n## Create all slides\nslides: ...\n\tpandoc -d beamer $\u003c -o $@\n```\n\nWith `make runlocal`, issued in your local shell, the container will be launched and an interactive shell (Bash) inside the container will be started. Your local working directory will be mounted into the container, so all files in your local working directory are accessible inside the container. With the above Makefile, you can then produce the PDF slide sets in the interactive shell within the container using `make slides`. The generated PDF files are automatically available in the local working directory via the mount.\n\n### Testing of the website in the local file system\n\nThe base URL for the deployment of the produced website has to be defined in the Hugo configuration file (`hugo.yaml`, variable `baseURL`).\n\nHowever, this prevents the generated web pages from being displayed correctly when accessed from the local file system. You would first have to adapt the Hugo configuration to the local URL. However, since this configuration is versioned with Git together with all the other project files, you can easily commit this \"broken\" configuration by accident.\n\nAs an alternative, you can add an additional local file `local.yaml` to the project root, which will _not be versioned_ (create a corresponding entry in the `.gitignore`!). This file contains a single line `baseURL: \"file://\u003cpath_to_project\u003e/docs/\"`, specifying the actual path in the local file system to your project. If this file is present, its definition of the `baseURL` overwrites the original configuration and you can view the generated web pages locally. For the deployment to the LMS, you just need to comment out the single line in the file, so the `baseURL` from the versioned global configuration will be used again.\n\nHere is an excerpt from a suitable Makefile (see again [Programmiermethoden-CampusMinden/Prog2-Lecture/Makefile](https://github.com/Programmiermethoden-CampusMinden/Prog2-Lecture/blob/master/Makefile)):\n\n```makefile\n## Define options to be used by Hugo\n## local.yaml allows to override settings in hugo.yaml\nHUGO_ARGS  = --config hugo.yaml,$(wildcard local.yaml)  --themesDir \"$(XDG_DATA_HOME)/pandoc/hugo\"\n\n## Create website\nweb: ...\n\thugo $(HUGO_ARGS)\n```\n\n## Option C: Locally via native installation\n\nLocal use without Docker is also an option for Unix-like operating systems like Linux or macOS (_but is not recommended_). For this purpose, the specified tools have to be installed manually using the correct versions. The files linked below provide both the download URLs for the respective binaries and the required version numbers:\n\n*   [Pandoc](https://github.com/cagix/pandoc-lecture/blob/master/docker/install-pandoc.sh) and [Pandoc-Lecture](https://github.com/cagix/pandoc-lecture/blob/master/docker/install-pandoc-lecture.sh)\n*   For the web page:\n    *   [Hugo](https://github.com/cagix/pandoc-lecture/blob/master/docker/install-hugo.sh)\n    *   [Hugo Relearn-Theme](https://github.com/cagix/pandoc-lecture/blob/master/docker/install-relearn.sh)\n*   For the PDF slide sets:\n    *   [TeX-Live](https://github.com/cagix/pandoc-lecture/blob/master/docker/install-texlive.sh)\n*   If required, [GraphViz and Dot](https://github.com/cagix/pandoc-lecture/blob/master/docker/install-packages-ubuntu.sh)\n\nThe content of [Pandoc Lecture](https://github.com/cagix/pandoc-lecture) has to be copied into your local user folder `${HOME}/.local/share/pandoc/`. The content of [Hugo Relearn-Theme](https://github.com/McShelby/hugo-theme-relearn) is expected in `${HOME}/.local/share/pandoc/hugo/hugo-theme-relearn/`. Both steps can be achieved using the [Makefile in Pandoc Lecture](https://github.com/cagix/pandoc-lecture/blob/master/Makefile):\n\n```sh\ngit clone https://github.com/cagix/pandoc-lecture.git\ncd pandoc-lecture/\nmake install_scripts_locally\n```\n\nYou can now work with your build script, e.g. a Makefile, in your local project. In the following example, you see a shortened excerpt from [Programmiermethoden-CampusMinden/Prog2-Lecture/Makefile](https://github.com/Programmiermethoden-CampusMinden/Prog2-Lecture/blob/master/Makefile) to produce the teaching material as a website with `make web` or the PDF slide sets with `make slides`:\n\n```makefile\n## Create website\nweb: ...\n\thugo $(HUGO_ARGS)\n\n## Create all slides\nslides: ...\n\tpandoc -d beamer $\u003c -o $@\n```\n\nThe downside of this option would be that you need to manually maintain the installed tools (Pandoc, Hugo, TexLive) as well as the scripts from Pandoc-Lecture and Hugo Relearn-Theme. The versions must always match the specifications in [cagix/pandoc-lecture/docker/](https://github.com/cagix/pandoc-lecture/tree/master/docker)!\n\nIf you want to check the generated artefacts locally, follow the advice given in the \"Testing the Web site in the local file system\" section above.\n\n\n# Contributing\n\nQuestions, bug reports, feature requests and pull requests are very welcome.\n\nPlease first check whether your request has already been dealt with in other (open or closed) issues. Feel free to reopen relevant closed issues to add your request there.\n\nWhen submitting pull requests, please make sure that your **feature branch starts at the tip of the current `master` branch**. Upon acceptance (i.e. merging your pull request), your contribution automatically becomes subject to the licence of this repository (MIT).\n\n\n# Credits\n\nSee the [credits](CREDITS.md) for a detailed list of contributing projects.\n\n\n---\n\n# License\n\nThis [work](https://github.com/cagix/pandoc-lecture) by\n[Carsten Gips](https://github.com/cagix) and\n[contributors](https://github.com/cagix/pandoc-lecture/graphs/contributors)\nis licensed under [MIT](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcagix%2Fpandoc-lecture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcagix%2Fpandoc-lecture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcagix%2Fpandoc-lecture/lists"}