quarkdown README

The project's README from github.com/iamgio/quarkdown. As one markdown file: README.md.

Quarkdown banner
Wiki Docs Release Visual Studio Code Extension Version FMT: Ktlint CodeFactor

iamgio%2Fquarkdown | Trendshift iamgio%2Fquarkdown | Trendshift
Quarkdown - Markdown with superpowers: from ideas to stunning documents. | Product Hunt

Releases
Latest   |   Stable 

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.

 

Paper demo

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, 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, :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.

 

Live preview

 

In a nutshell, Quarkdown is...

 

Looking for something?

Check out the wiki to get started and learn more about the language and its features!

 

As simple as you expect...

Paper code demo

Inspired by: X-ray flashes from a nearby supermassive black hole accelerate mysteriously

 

...as complex as you need.

Chart code demo

Editor extensions

 

Targets

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

 

Comparison

Quarkdown LaTeX Typst AsciiDoc MDX
Concise and readable :white_check_mark: :x: :white_check_mark: :white_check_mark: :white_check_mark:
Full document control[^control] :white_check_mark: :white_check_mark: :white_check_mark: :x: :x:
Scripting :white_check_mark: Partial :white_check_mark: :x: :white_check_mark:
Book/article export :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark: Third-party
Presentation export :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark: Third-party
Static site export :white_check_mark: :x: Experimental :white_check_mark: :white_check_mark:
Docs/wiki export :white_check_mark: :x: :x: :white_check_mark: :white_check_mark:
Learning curve :green_circle: :red_circle: :orange_circle: :green_circle: :green_circle:
Targets HTML, PDF, MD, TXT PDF, PostScript HTML, PDF HTML, PDF, ePub HTML

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

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}
    ![Image 1](img1.png)

    ![Image 2](img2.png)
    
    ![Image 3](img3.png)

 

Getting started

Installation

Install script (Linux/macOS)

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.
The browser required for PDF export is installed automatically.

For more installation options, check out get-quarkdown.

Homebrew (Linux/macOS)

brew install quarkdown-labs/quarkdown/quarkdown

Install script (Windows)

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

Scoop (Windows)

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

GitHub Actions

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

Manual installation

Instructions for manual installation

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

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

Requirements:

  • (Only for PDF export) A Chromium-family browser, such as chrome-headless-shell. See PDF export for details.

 

Quickstart

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

 

Creating a project

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

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.

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:

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

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

 

 

Mock document

 

Mock document demo

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.

Contributing

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

Sponsors

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

Falconer

RayOffiah

vitto4 aaditkamat

LunaBluee  dcopia Pallandos imogenxingren serkonda7

Concept

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.

Quarkdown icon

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

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

quarkdown (iamgio/quarkdown)

Searching Database…

16.3K ·GitHub
Quarkdown
What is this?Quarkdown is a Markdown-based typesetting system: you write a single Markdown source and it compiles into a print-ready book, academic paper, knowledge base, website, or interactive presentation.
So is it plain Markdown, or do I have to learn a new syntax?It is Markdown: the Quarkdown Flavor starts from CommonMark and GFM and extends them with function calls, variables, conditionals and loops, turning Markdown into a Turing-complete language.
How do I get it and compile my first document?Install via the script or Homebrew on Linux/macOS, the script or Scoop on Windows, or the setup-quarkdown GitHub Action. Then 'quarkdown create' scaffolds a project through a wizard, and 'quarkdown c file.qd' compiles it.
Do I need anything extra on my machine for PDF export?Only a Chromium-family browser such as chrome-headless-shell. The Linux/macOS install script sets the browser up automatically; with a manual install you need to provide it yourself.
Does it work on Windows as well as Mac and Linux?Yes — it is a cross-platform CLI with dedicated install options for Linux and macOS (script, Homebrew) and for Windows (script, Scoop), plus a GitHub Actions integration for CI builds.
Quarkdown documents can contain code — can a .qd file I downloaded touch my system?Not freely: a permission system restricts what documents can do with system resources, and it is enabled by default.
Is it really free to use, or is there a licensing catch?It is free and open source under GPLv3 by default; the CLI and Language Server modules and their binaries are AGPLv3 instead. No paid tiers anywhere.
What exactly can a single document compile into?HTML in four modes — plain continuous flow in Notion/Obsidian style, paged (via paged.js) for papers, articles and books, slides via reveal.js, and docs for wikis — selected with .doctype {plain|paged|slides|docs}. Everything HTML supports also exports to PDF, and GFM Markdown or plain text export is available too.
Is there live preview while I write?Yes: compile with -p (automatic reload) and -w (recompile on file change) together for live preview, and it is fast — the official wiki of 100+ subdocuments compiles in about 2 seconds. An interactive REPL is available via 'quarkdown repl'.
How does it compare to LaTeX and Typst?Per the README's comparison table, Quarkdown is the only tool in the group combining concise Markdown-style syntax with full scripting and export to all of HTML, PDF, Markdown and plain text — including the presentation and docs/wiki targets that LaTeX lacks. Its learning curve sits between AsciiDoc and Typst.
Does it come with tooling for editors and AI coding agents?Yes — there is a VS Code extension, an unofficial IntelliJ IDEA plugin, and a built-in skill that makes coding agents write idiomatic Quarkdown, which the README even links an evaluation for.
What are similar projects?openwiki, pandoc, typst, craftinginterpreters, gollum, mkdocs, mdBook, gzh-design-skill
Which topics is it in?presentations, markup, scripting-language, typesetting, pdf-generation, academic-writing, documentation-tool, jetbrains, slides, wiki, books, static-site-generator
Creator
iamgio
Size
35.2 MB
Stars
16.3K
Updated
CommitOct 16Releasev2.6.4Oct 09
Age
2y
Commits · 90 Days