GitHub - iamgio/quarkdown: 🪐 Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.
Key Points
- 1Quarkdown is a versatile Markdown-based typesetting system that extends CommonMark with a Turing-complete language, allowing for dynamic content generation and complex scripting.
- 2It features an ever-expanding standard library, custom function and variable definitions, and live preview, enabling advanced document control beyond traditional Markdown.
- 3Quarkdown supports diverse output targets including HTML, paged documents (for print), and interactive presentations, making it suitable for academic papers, books, websites, and knowledge bases.
Quarkdown is a modern, versatile Markdown-based typesetting system designed to compile projects into diverse formats, ranging from print-ready books to interactive presentations and static websites. Its core methodology revolves around the "Quarkdown Flavor," a powerful, Turing-complete extension of CommonMark and GitHub Flavored Markdown (GFM).
The system introduces advanced scripting capabilities directly within Markdown documents through a function-based syntax. Functions are invoked using a dot notation followed by the function name, arguments enclosed in curly braces, and an optional body argument. For instance, a function call appears as .functionName {argument1} {argument2} Body content. This mechanism allows for dynamic content generation, conditional logic, loops, and input/output operations, leveraging an ever-expanding standard library that provides layout builders and other utilities. Users can also define their own custom functions and variables within Markdown, facilitating the creation of complex and reusable content. A concrete example of user-defined function definition and invocation is:
.function {greet} to from: **Hello, .to** from .from!
.greet {world} from:{iamgio}This demonstrates how parameters are defined and used within the function body, leading to a dynamic output: "Hello, world from iamgio!". This out-of-the-box scripting support enables complex document structures that are not achievable with vanilla Markdown.
Quarkdown supports multiple output targets, specified via the .doctype function within the source file:
- Plain HTML: Continuous flow, suitable for static websites and knowledge bases.
- Paged HTML: Utilizes paged.js for print-ready documents, articles, and books.
- Slides: Generates interactive presentations via reveal.js.
- PDF: Supports all document types and features by converting HTML outputs to PDF, requiring Node.js, npm, and Puppeteer for rendering.
The system emphasizes conciseness and full document control, distinguishing itself from other document generation tools. For example, a LaTeX section and item list:
\section{Section}
\subsection{Subsection}
\begin{enumerate}
\item \textbf{First} item
\item \textbf{Second} item
\end{enumerate}Is simplified in Quarkdown to:
# Section
## Subsection
1. **First** item
2. **Second** itemFor layout and image inclusion, Quarkdown introduces functions like
.center and .row which abstract complex LaTeX environments:\begin{center} This text is \textit{centered}. \end{center}
\begin{figure}[h!]
\centering
\begin{subfigure}[b]
\includegraphics[width=0.3\linewidth]{img1.png}
\end{subfigure}
% ... more subfigures
\end{figure}Becomes:
.center This text is _centered_ .
.row alignment:{spacebetween}
  Compilation is managed via a command-line interface (CLI) tool. The quarkdown c file.qd command compiles a specified source file. Key CLI options provide granular control over the compilation process:
-por--preview: Enables automatic content reloading and launches a web server for live preview.-wor--watch: Monitors source files for changes and recompiles automatically.--pdf: Instructs the compiler to output a PDF file.-o <dir>or--out <dir>: Sets the output directory for generated files.-r <renderer>or--render <renderer>: Specifies the target renderer, accepting values such ashtml,html-pdf(equivalent tohtmlwith--pdf), andtext.--pipe: Outputs generated content to standard output, useful for integration with other tools.--strict: Forces program exit upon error detection, as opposed to displaying error boxes within the document.--nowrap: Prevents the rendered output from being encapsulated within a full document structure, producing only the inner content for HTML.
Quarkdown requires Java 17 or higher for execution, and Node.js, npm, and Puppeteer for PDF export functionalities. The project's philosophy, symbolized by its logo, reflects the concept of a "down quark"—a fundamental particle that, despite its lightness, forms the building blocks of complex matter, mirroring Quarkdown's goal of building complex documents from simple, foundational Markdown.