This repository serves as a template for creating organized, Pandoc-powered course repositories that convert Markdown files into clean PDF handouts. It also allows the user to use Typst to create their document. It is designed for math, computer science, and other technical courses where instructors want full control over formatting and rendering using a lightweight, command-driven setup.
- Modern Typesetting: Typst offers a more modern and flexible typesetting system compared to LaTeX, with a simpler syntax and powerful layout capabilities.
- Built-in Features: Typst has built-in support for features like tables, math, and graphics without needing additional packages.
- Faster Compilation: Typst compiles documents faster than LaTeX, making it more efficient for iterative editing and rendering.
- Better Error Messages: Typst provides clearer and more user-friendly error messages, which can help users troubleshoot issues
This repository includes the following core directories:
/Class_Notes
├── pdf/ # Rendered PDFs from your markdown notes
├── img/ # Images referenced in your markdown files
├── Lecture_01.md # Example markdown files with embedded commands
/Class_Organization
├── pdf/ # PDFs for syllabi, schedules, policies, etc.
/tools
├── render.py # The script that processes markdown to PDF
├── grid-header.tex # Optional LaTeX header to include grid background
- All markdown/typst files (
.md,.typ) placed in folders that contain apdf/subdirectory can be processed. - Files must include a
<!-- command: render -->(markdown) or// command: render(typst) line to be turned into PDFs. - Optional commands allow for landscape formatting and grid overlays (only supported for markdown currently).
| Command | Description |
|---|---|
<!-- command: render --> |
Required for the file to be converted into a PDF |
<!-- command: grid --> |
Adds a grid background using grid-header.tex |
<!-- command: landscape --> |
Renders the PDF in landscape orientation |
You can combine these in a single file.
| Command | Description |
|---|---|
// command: render |
Required for the file to be converted into a PDF |
- Any images referenced using relative paths (e.g.
) will work as long as the image is in the same folder or a subfolder of the.mdfile. - This is supported via Pandoc’s
--resource-path.
- Open a terminal in the top-level directory of your course repo (same level as
tools/). - Run:
python tools/render.pyThe script will:
- Look one level up from
tools/ - Find all subdirectories that contain a
pdf/folder - Process
.mdfiles in those folders that include therendercommand - Save the PDF output to the respective
pdf/folders
- Python 3.6+
- Pandoc
- A working LaTeX installation (
pdflatexrecommended) - A working Typst installation (
typstcommand available in terminal)
To start a new course with this setup:
- Click "Use this template" on GitHub to create a new repo based on this structure.
- Rename folders as needed (e.g.
Class_Notes→Unit_1_Notes) - Add markdown handouts and images.
- Customize the
grid-header.texor replace it with your own.
- Add new directories for homework, projects, or labs — just include a
pdf/subfolder to enable rendering. - Update
render.pyto include new features (e.g., templates, metadata support). - Track versioned syllabi or planning documents inside
Class_Organization.
<!-- command: render -->
<!-- command: grid -->
<!-- command: landscape -->
# Day 1: Introduction to Functions
## Objectives
- Understand domain and range
- Work with multiple representations// command: render
// Typst file example
#set page(margin: 1in)
#set text(font: "Times New Roman", size: 11pt)
#let blank(len) = box(width: len, height: 0.5pt, stroke: 1pt + black)
= Day 1: Introduction to Functions
== Objectives
#enum(
[Understand domain and range],
[Work with multiple representations],
)If you're unsure how to modify the renderer, open an issue or check the inline comments in render.py for guidance.