Quarkdown — Markdown with Superpowers for Papers, Slides & Websites

Introduction

Quarkdown is a markup language and compiler that extends standard Markdown with functions, variables, conditionals, and loops. It targets authors who need to produce academic papers, slide decks, websites, and books from a single source file. The compiler outputs HTML and PDF with full control over styling and layout.

What Quarkdown Does

• Extends Markdown syntax with callable functions, variables, and control flow for dynamic document generation
• Compiles a single source file into multiple output formats including HTML pages, PDF documents, and slide presentations
• Supports LaTeX math rendering, syntax-highlighted code blocks, and automatic table of contents generation
• Provides a theming system with CSS-like styling that applies consistently across output formats
• Includes a standard library of built-in functions for common document patterns like footnotes, citations, and cross-references

Architecture Overview

Quarkdown is written in Kotlin and runs on the JVM. The compiler parses .qmd files through a pipeline of lexing, parsing, function resolution, and rendering stages. The function system is evaluated at compile time, allowing conditional content inclusion and iterative generation without runtime dependencies. Output rendering delegates to format-specific backends that produce self-contained HTML or PDF via headless browser conversion.

Self-Hosting & Configuration

• Install through Homebrew on macOS/Linux, or download the JAR from GitHub Releases
• Requires a JVM (Java 17+) to run the compiler
• Project configuration is specified in a .quarkdown YAML file at the project root
• Custom themes are defined as CSS files and referenced in the project configuration
• Supports watch mode for live-reloading during document authoring

Key Features

• Turing-complete function system embedded in Markdown for dynamic content generation
• Multi-format output from a single source: HTML, PDF, and presentation slides
• Built-in internationalization with localized document elements
• Automatic slide break detection for presentation mode based on heading levels
• Extensible standard library with user-defined functions and imports across files

Comparison with Similar Tools

• Typst — Purpose-built typesetting language with its own syntax; Quarkdown stays closer to Markdown conventions
• Pandoc — Universal document converter that reads many formats; Quarkdown focuses on a single enhanced Markdown dialect with scripting
• MDX — Extends Markdown with JSX components for React; Quarkdown's functions are format-agnostic and compile-time evaluated
• Marp — Markdown-to-slides tool; Quarkdown handles slides plus papers, books, and websites from one source
• LaTeX — The standard for academic typesetting; Quarkdown offers a simpler syntax while supporting LaTeX math blocks

FAQ

Q: Does Quarkdown replace LaTeX for academic writing? A: Quarkdown can produce papers with citations, math, and figures, but complex layouts or journal-specific templates may still require LaTeX. It supports inline LaTeX math via KaTeX.

Q: Can I use Quarkdown for slide presentations? A: Yes. Quarkdown automatically splits content into slides based on heading levels, with transitions and speaker notes supported.

Q: What output formats are supported? A: HTML (single page or multi-page), PDF (via headless browser rendering), and presentation slides as HTML.

Q: Is Quarkdown compatible with standard Markdown? A: Standard Markdown files render correctly in Quarkdown. The extended features like functions use a .function syntax that degrades gracefully in other renderers.

Sources

• https://github.com/iamgio/quarkdown
• https://github.com/iamgio/quarkdown/wiki