quarkdown Documentation

File: README.md Copy Chapter

Table of contents

1. About
2. Demo
3. Editor extensions
4. Targets
5. Comparison
6. Getting started
   1. Installation
   2. Quickstart
   3. Creating a project
   4. Compiling
7. Mock document
8. Contributing
9. Sponsors
10. Concept
11. License

About

Quarkdown is a modern Markdown-based typesetting system designed for versatility. It allows a single project to compile seamlessly into a print-ready book, academic paper, knowledge base, or interactive presentation.
All through an incredibly powerful Turing-complete extension of Markdown, ensuring your ideas flow automatically into paper.

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:

text Copy

.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.
You can even create awesome libraries for everyone to use.

text Copy

.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, :zap: fast compilation speed and great editor support, Quarkdown simply gets the work done,
whether it's an academic paper, book, knowledge base or interactive presentation.

In a nutshell, Quarkdown is...

• Familiar: built on the well-known Markdown syntax, for a flat learning curve
• Elegant: produces output that matches the quality of industry-leading tools
• Agent-friendly: comes with a built-in skill for idiomatic fluency of your coding agents (read the eval)
• Customizable: full control over document layout, aesthetics, and properties
• Secure by default: a restrictive permission system limits access to system resources
• Versatile: a single source compiles to multiple targets
• Reactive: low-latency live previews for rapid iteration. The official wiki (100+ subdocuments) compiles in ~2 seconds
• Reusable: repeated content can be turned into one-line function calls
• Easily deployable: set a CD workflow up in under 3 minutes (example)

Looking for something?

As simple as you expect... Copy Chapter

...as complex as you need.

Editor extensions

• VS Code
• IntelliJ IDEA (unofficial by @CarmJos)

Targets

• HTML

  • Plain
    Continuous flow like Notion/Obsidian, perfect for static websites and knowledge management - check out the author's personal website.

  • Paged ^{via paged.js}
    Perfect for papers, articles and books - check out the demo document.

  • Slides ^{via reveal.js}
    Perfect for interactive presentations.

  • Docs
    Perfect for wikis, technical documentation and large knowledge bases - check out Quarkdown's wiki.

• PDF

  • All document types and features supported by HTML are also supported when exporting to PDF.

• Markdown

  • GFM export.

• Plain text

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

• .doctype {plain} (default)
• .doctype {paged}
• .doctype {slides}
• .doctype {docs}

Comparison

[^control]: The ability to customize the properties of the document and of its output artifact through the language itself.

\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 Copy Chapter

1. First item
2. Second item

.center
This text is centered.

.row alignment:{spacebetween}

 

# Getting started

## Installation

### Install script (Linux/macOS)

```shell
curl -fsSL https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/heads/main/install.sh | sudo env "PATH=$PATH" bash

Root privileges let the script install Quarkdown into /opt/quarkdown and its wrapper script into /usr/local/bin/quarkdown.
If missing, Node.js will be installed automatically using the system's package manager.

For more installation options, check out get-quarkdown.

Homebrew (Linux/macOS) Copy Section

brew install quarkdown-labs/quarkdown/quarkdown

Install script (Windows) Copy Section

irm https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/heads/main/install.ps1 | iex

Scoop (Windows) Copy Section

scoop bucket add quarkdown https://github.com/quarkdown-labs/scoop-quarkdown; scoop install quarkdown

GitHub Actions Copy Section

See setup-quarkdown to easily integrate Quarkdown into your GitHub Actions workflows.

Manual installation Copy Section

Instructions for manual installation

Download quarkdown.zip from the latest stable release and unzip it,
or build it with gradlew installDist.

Optionally, adding /bin to your PATH allows you easier access Quarkdown.

Requirements:

• (Only for PDF export) Node.js, npm, Puppeteer. See PDF export for details.

Quickstart Copy Chapter

New user? You'll find everything you need in the Quickstart guide to bring your first document to life!

Creating a project Copy Chapter

quarkdown create [directory] will launch the prompt-based project wizard, making it quicker than ever
to set up a new Quarkdown project, with all metadata and initial content already present.

Compiling Copy Chapter

Running quarkdown c file.qd 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?

If you would like to familiarize yourself with Quarkdown instead, quarkdown repl lets you play with an interactive REPL mode.

Options

The most commonly used options are:

• -p or --preview: enables automatic content reloading after compiling.

• -w or --watch: recompiles the source every time a file from the source directory is changed.

[!TIP]
Combine -p -w to achieve live preview!

• --pdf: produces a PDF file. Learn more in the wiki's PDF export page.

For the full list of options, check out the CLI options wiki page.

Mock document Copy Chapter

Mock, written in Quarkdown, is a comprehensive collection of visual elements offered by the language,
making it ideal for exploring and understanding its key features — all while playing and experimenting hands-on with a concrete outcome in the form of pages or slides.

• The document's source files are available in the mock directory, and can be compiled via quarkdown c mock/main.qd -p.
• The PDF artifacts generated for all possible theme combinations are available and can be viewed in the generated repo.

Contributing Copy Chapter

Contributions are welcome! Please check CONTRIBUTING.md to know how contribute via issues or pull requests.

Sponsors Copy Chapter

A special thanks to all the sponsors who supported this project!

Concept Copy Chapter

The logo resembles the original Markdown icon, 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.

License Copy Chapter

By default, Quarkdown and its modules are licensed under GNU GPLv3, except for modules that include their own LICENSE file:
the CLI (quarkdown-cli) and Language Server (quarkdown-lsp) modules and binaries are licensed under GNU AGPLv3.

Footnotes Copy Chapter

File: mock/README.md Copy Chapter

Mock

Mock, written in Quarkdown, is a comprehensive collection of visual elements offered by the language,
making it ideal for exploring and understanding its key features — all while playing with a concrete outcome in the form of pages or slides.

This document is also a great theme testing site.

To compile: quarkdown c mock/main.qd

• Add -p to open in-browser. Add -p -w to enable live reloading.
• Add --pdf to compile to PDF.

File: quarkdown-html/README.md Copy Chapter

html

This module provides an extension to render Quarkdown ASTs to:

• HTML, CSS and JavaScript;
• PDF (via Puppeteer).

Options Copy Chapter

• --render html for HTML rendering
• --render html --pdf or --render html-pdf for PDF rendering.

-r is short for --render.

Note that Quarkdown's CLI uses --render html by default, hence PDF rendering can be achieved via just --pdf.

File: quarkdown-interaction/README.md Copy Chapter

interaction

This module provides a library to allow Quarkdown components to interact with third-party services and processes.

File: quarkdown-libs/README.md Copy Chapter

libs

This module contains libraries written in Quarkdown (main/resources).

The Gradle build system will automatically copy the .qd files into the lib/qd directory of the distribution zip.
At runtime, the CLI option -l or --libs sets the path to the library directory to use, which clearly defaults to lib/qd.

In order to load a library from the library directory, the .include {name} function can be used.
After the library is loaded, the functions defined in the library can be used in the main document.

See wiki: Importing external libraries for further information.

File: quarkdown-quarkdoc/README.md Copy Chapter

quarkdoc

This module contains the Quarkdoc plugin for Dokka, the Kotlin documentation engine.

Quarkdoc extends Dokka by providing Quarkdown-level documentation for native libraries,
i.e. collections of strongly-typed Quarkdown functions written in Kotlin.

When a module adopts this plugin, its benefits include:

• Quarkdown-syntax function signatures;
• Package generation from Quarkdown modules: in a native Quarkdown library, a Module is a single source file.
  The plugin generates a pseudo-package for each module, making it easier to navigate library functions by module name;
• Function/parameter name adaptation via @Name (Quarkdown's functions don't always match their native signature);
• Listing of enum entries for enum-type function parameters;
• Function's document type constraints via @OnlyForDocumentType/@NotForDocumentType;
• Suppression of @Injected function parameters;

To see all enhancements, QuarkdocDokkaPlugin features a complete list.

File: quarkdown-server/README.md Copy Chapter

server

This module contains code for Quarkdown's local webserver,
which serves static files and drives live preview.

Endpoints:

• / for static files, relative to the origin directory;
• /live/[file] for wrapping HTML files with live preview capabilities;
• /reload for live reloading: GET opens a Server-Sent Events stream that subscribers (browser clients) listen on,
  while POST broadcasts a reload event to every active subscriber (used by Quarkdown CLI after each compile).

For architectural details, see Inside Quarkdown - How does live preview work?.

File: quarkdown-test/README.md Copy Chapter

test

This module contains unit tests that take actual Quarkdown sources as inputs, making sure they produce the expected
final output by correctly executing each step of the compilation pipeline, from lexing to rendering.

The programs make use of the stdlib, and libraries from libs can be also included.