LuisFX/quarkdown

🪐 Markdown with superpowers.

Download the latest build here 

---

Quarkdown is a Markdown parser and renderer that extends the capabilities of Markdown, bringing support for functions and many other syntax extensions.

This is a function call:

.somefunction {arg1} {arg2}
    Body argument

Possibilities are unlimited thanks to an ever-expanding standard library, which offers layout builders, I/O, math, conditional statements and loops.

Not enough? You can still define your own functions and variables — all within Markdown.

.function {greet}
    to from:
    **Hello, .to** from .from!

.greet {world} from:{iamgio}

Result: Hello, world from iamgio!

This out-of-the-box scripting support opens doors to complex and dynamic content that would be otherwise impossible to achieve with vanilla Markdown.

 

---

Check out the demo presentation here

Built with Quarkdown itself — source code

(Desktop view is suggested)

---

 

Comparison

	Markdown	LaTeX	Quarkdown
Concise and readable	✅	❌	✅
Full document control	❌	✅	✅
Scripting	❌	❌	✅

LaTeX

Quarkdown

\tableofcontents \section{Section} \subsection{Subsection} \begin{enumerate} \item \textbf{First} item \item \textbf{Second} item \end{itemize} \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} \begin{subfigure}[b] \includegraphics[width=0.3\linewidth]{img2.png} \end{subfigure} \begin{subfigure}[b] \includegraphics[width=0.3\linewidth]{img3.png} \end{subfigure} \end{figure}

.tableofcontents # Section ## Subsection 1. **First** item 2. **Second** item .center This text is _centered_. .row alignment:{spacebetween}   

Installation

Download quarkdown.zip from the releases page or build it yourself with gradlew distZip, and unzip it.
If you'd rather keep it minimal, gradlew build produces only the JAR file.

The bin directory contains the executable scripts. Optionally, add it to your PATH to access Quarkdown more easily.

Java 17 or higher is required.

Getting started

Running the program with no command-line arguments runs it in REPL mode. This is great for familiarizing yourself with Quarkdown, but it's probably not what you're looking for.

Running quarkdown path-to-file.qmd will compile the given file, save the output to file and log its content.
If the project is composed by multiple source files, the target file must be the root one, i.e. the one that includes the other files.

Note

The qmd extension is conventionally the standard one, but any can be used.

Options:

• -o <dir> or --output <dir>: sets the directory of the output files. If unset, defaults to ./output.

• --pretty: produces pretty output code. This is useful for debugging or to read the output code more easily, but it should be disabled in production as the results might be visually affected.

• --clean: deletes the content of the output directory before producing new files. Destructive operation.

• --strict: forces the program to exit if an error occurs. When not in strict mode, errors are shown as boxes in the document.

• -Dloglevel=<level> (JVM property): sets the log level. If set to warning or higher, the output content is not printed out.

Targets

HTML is currently the only supported rendering target. LaTeX rendering is a future goal.

• HTML
  • ✅ Plain output (default)
  • ✅ Slides (via reveal.js)
  • ⚠️ Paged (book) (via paged.js) — currently unstable

The desired document type can be set by calling the .doctype function within the Markdown source itself:

• .doctype {slides}
• .doctype {paged}

Scripting

Iterative Fibonacci

.var {t1} {0}
.var {t2} {1}

.table
    .foreach {0..8}
        n:
        | $ F_{.n} $ |
        |:----------:|
        |    .t1     |
        .var {tmp} {.sum {.t1} {.t2}}
        .var {t1} {.t2}
        .var {t2} {.tmp}

$F_0$	$F_1$	$F_2$	$F_3$	$F_4$	$F_5$	$F_6$	$F_7$	$F_8$
0	1	1	2	3	5	8	13	21

Recursive Fibonacci

The recursive approach is significantly slower than the iterative one.

.function {fib}
    n:
    .if { .islower {.n} than:{2} }
        .n
    .ifnot { .islower {.n} than:{2} }
        .sum {
            .fib { .subtract {.n} {1} }
        } {
            .fib { .subtract {.n} {2} }
        }
  
.table
    .foreach {0..8}
        | $ F_{.1} $ |
        |:----------:|
        | .fib {.1}  |

$F_0$	$F_1$	$F_2$	$F_3$	$F_4$	$F_5$	$F_6$	$F_7$	$F_8$
0	1	1	2	3	5	8	13	21

Status

The project is under active development.

Future plans

• Wiki, getting started guides and tutorials
• New themes
• Contribution guidelines
• Auto-generated stdlib documentation (Dokka custom plugin)
• External libraries support
• LaTeX rendering
• GUI editor / IDE plugin