Objectives

Teaching materials are often created using classic office applications like Word or PowerPoint. These tools allow for a quick start, but reach their limits with increasing complexity:

• Templates are available, but applying them to existing documents is quite time-consuming.
• Especially in STEM subjects, the integrated formula editor often interrupts the writing flow.
• Exporting as a PDF works reliably, but is only partially readable on mobile devices – especially smartphones.
• Creating worksheets with corresponding answer keys often leads to duplicated effort, as content has to be maintained in separate documents.

This repository takes a different approach: Teaching materials are created in the easy-to-learn markup language Markdown and then exported to various formats such as PDF or HTML.

Here you will find the templates, tools, and workflows I use for this.

A practical introduction is provided by the document "Erstellen von Skripten mit Markdown".

A concrete example of publishing the materials is shown on the page "PHySiCS - Materialien", including in combination with the app "ScriptsApp".

Installation

Tools

The tools are generally operating system independent; they have already been successfully tested on Microsoft Windows, Apple macOS, and Linux. Install the following programs, all of which are open-source and free:

• pandoc
• vscodium or vscode
• nodejs

Directory

• First, create a main directory where you will later organize all your materials for different subjects. We will refer to this directory as "Scripts".
• Navigate to the "Scripts" directory and clone this repository using git clone https://codeberg.org/tk100/ScriptsTemplates.git or download the corresponding ZIP file and extract it. Rename the new folder to "Templates" (it will now be located directly within "Scripts").
• Create appropriate subfolders for each of your subjects in the "Scripts" folder (e.g., "Mathematics").
• Within each subject folder, create further subfolders for topics or learning areas (e.g., "Rational-Functions"). Avoid spaces in the folder names.

Plugin

• Open VS Code or VS Code
• Click on Menu → Extensions → three dots → "Install from VSIX..."
• Select the latest file named "mdtools-extension-x.y.z.vsix"

First Test

• Create a file named "Test.md" in a topic folder (e.g., "Scripts/Mathematics/Rational-Functions").
• Add a YAML header with meta information:

---
title: Example
author: <Your Name>
date: <Current Date>
type: text
---

• Add a few lines below, formatted with Markdown.
• Save the file in the editor; a preview will open showing the HTML.
• If you encounter any problems, read the README for the plugin.

All supported markup options can be found in the document "Erstellen von Skripten mit Markdown"

Structure of this repository

• dist: All resources required to display the scripts using HTML
• extension: Plugin for converting Markdown to HTML
• mdtools: Individual scripts for converting Markdown to HTML and PDF
• pandoc: Specific customizations for Pandoc (header, LaTeX macros, etc.)