Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/iamgio/quarkdown
🪐 Markdown with superpowers.
https://github.com/iamgio/quarkdown
markdown markdown-parser markup-language paper presentations programming-language scripting-language slides
Last synced: 5 days ago
JSON representation
🪐 Markdown with superpowers.
- Host: GitHub
- URL: https://github.com/iamgio/quarkdown
- Owner: iamgio
- License: gpl-3.0
- Created: 2024-01-30T21:13:04.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-21T01:39:14.000Z (14 days ago)
- Last Synced: 2025-01-22T09:01:35.635Z (12 days ago)
- Topics: markdown, markdown-parser, markup-language, paper, presentations, programming-language, scripting-language, slides
- Language: Kotlin
- Homepage: https://iamgio.eu/quarkdown/demo
- Size: 4.79 MB
- Stars: 385
- Watchers: 4
- Forks: 7
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Download the latest build here
Quarkdown is a modern Markdown-based typetting system, designed around the key concept of **versatility**, by seamlessly compiling a project
into a print-ready book or an interactive presentation.
All through an incredibly powerful Turing-complete extension of Markdown, ensuring your ideas flow automatically into paper.
Original credits: Attention Is All You Need
Born as an extension of CommonMark and GFM, the Quarkdown Flavor brings **functions** to Markdown, along with 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.
You can even create awesome libraries for everyone to use.
> ```
> .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.
Combined with live preview and :zap: fast compilation speed, Quarkdown simply gets the work done.
Check the [wiki](https://github.com/iamgio/quarkdown/wiki) to learn more about the language and its features.
---
Check out the demo presentation here
Built with Quarkdown itself — source code
(Desktop view is suggested)
---
## Targets
- **HTML**
- :white_check_mark: Plain output (default)
- :white_check_mark: Slides (via [reveal.js](https://revealjs.com))
- :white_check_mark: Paged (books, articles) (via [paged.js](https://pagedjs.org)) - *Requires a webserver. See [Server](#server) below.*
- Quarkdown's HTML is PDF-ready: check the [wiki](https://github.com/iamgio/quarkdown/wiki/pdf-export)
to learn how to convert an artifact to PDF.
The desired document type can be set by calling the [`.doctype` function](https://github.com/iamgio/quarkdown/wiki/document-metadata) within the Markdown source itself:
- `.doctype {slides}`
- `.doctype {paged}`
## Comparison
| | Quarkdown | Markdown | LaTeX | AsciiDoc | MDX |
|-----------------------|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|
| Concise and readable | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: | :white_check_mark: |
| Full document control | :white_check_mark: | :x: | :white_check_mark: | :x: | :x: |
| Scripting | :white_check_mark: | :x: | Partial | :x: | :white_check_mark: |
| Book/article export | :white_check_mark: | :x: | :white_check_mark: | :white_check_mark: | Third-party |
| Presentation export | :white_check_mark: | :x: | :white_check_mark: | :white_check_mark: | Third-party |
LaTeX
Quarkdown
```latex
\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}
```
```markdown
.tableofcontents
# Section
## Subsection
1. **First** item
2. **Second** item
.center
This text is _centered_.
.row alignment:{spacebetween}
```
## 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.
- The `lib/qmd` directory contains `.qmd` libraries that can be imported into a project.
Java 17 or higher is required.
## Getting started
Running `quarkdown c file.qmd` will compile the given file and save the output to file.
> 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.
>
> - [How to include other files?](https://github.com/iamgio/quarkdown/wiki/including-other-quarkdown-files)
If you would like to familiarize yourself with Quarkdown instead, `quarkdown repl` lets you play with an interactive REPL mode.
### Options
- **`-o `** or **`--output `**: sets the directory of the output files. If unset, defaults to `./output`.
- **`-p`** or **`--preview`**: enables automatic content reloading after compiling.
If a [server](#server) is not running yet, it is started and the document is opened in the default browser.
- **`-w`** or **`--watch`**: recompiles the source everytime a file from the source directory is changed.
*Tip: combine with `-p` to achieve live preview!*
- `--server-port `: optional customization of the local webserver's port. Defaults to `8089`.
- `-l ` or `--libs `: sets the directory where external libraries can be loaded from. If unset, defaults to `/lib/qmd`. [(?)](https://github.com/iamgio/quarkdown/wiki/importing-external-libraries)
- `--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.
### Server
Quarkdown's webserver allows direct communication between the compiler and the browser,
enabling automatic content reloading.
> [!IMPORTANT]
> A webserver is **mandatory** in order to show *paged* documents, because of a paged.js requirement.
> For that purpose, you can also use other servers, such as Visual Studio Code's *Live Preview*, if you prefer.
The server can be started via `quarkdown start`, with the following options:
- **`-f `** or **`--file `**: (*mandatory*) the file the server should point to. It would preferably be the output directory of the compilation.
- **`-p `** or **`--port `**: the webserver's port. If unset, defaults to `8089`.
- **`-o`** or **`--open`**: if set, opens the target file in the default browser.
> [!TIP]
> `quarkdown c ... --preview` is shorthand for `quarkdown c ... && quarkdown start -f -o`
## Themes
Quarkdown comes with a set of themes that can give a unique look to your document.
- [How to apply a theme?](https://github.com/iamgio/quarkdown/wiki/themes)
> [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 |
## Concept
The logo resembles the original [Markdown icon](https://github.com/dcurtis/markdown-mark), with focus on Quarkdown's completeness,
richness of features and customization options, emphasized by the revolving arrow all around the sphere.
What could be mistaken for a planet is actually a **quark** or, more specifically, a **down quark**,
an elementary particle that is a major constituent of matter: they give life to every complex structure we know of,
while also being one of the lightest objects in existence.
This is, indeed, the concept **Quarkdown** is built upon.