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](stdlib/src/main/kotlin/eu/iamgio/quarkdown/stdlib),
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.
---
```markdown
.tableofcontents
# Section
## Subsection
1. **First** item
2. **Second** item
.center
This text is _centered_.
.row alignment:{spacebetween}
![Image 1](img1.png)
![Image 2](img2.png)
![Image 3](img3.png)
```
## Installation
Download `quarkdown.zip` from the [releases](https://github.com/iamgio/quarkdown/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 `** or **`--output `**: 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.
- **`--no-media-storage`**: turns the media storage system off. [(?)](https://github.com/iamgio/quarkdown/wiki/Media-storage)
- **`-Dloglevel=`** (JVM property): sets the log level. If set to `warning` or higher, the output content is not printed out.
## Themes
Themes are split in two groups: *color* themes, which define the color scheme of a document, and *layout* themes, which set the general structural rules of the layout.
Combining them can create a document that truly stands out.
A theme can be set via the `.theme {colortheme} layout:{layouttheme}` function.
#### Layout themes
- `minimal`
- `latex`
- `beamer`
- `plain`
#### Color themes
- `darko`
- `paperwhite`
- `beaver`
- `plain`
Some suggested combinations are:
- `minimal+darko` (used by the demo presentation)
- `latex+paperwhite` (LaTeX look, great for `paged` documents)
- `beamer+beaver` (Beamer look).
> [Theme contributions](core/src/main/resources/render/theme) are welcome!
> Please make sure they work well with all the three document types before submitting.
## 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 |