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
Что это такое?Quarkdown — это система вёрстки на основе Markdown: вы пишете один исходник в Markdown, а на выходе получаете готовую к печати книгу, научную статью, базу знаний, сайт или интерактивную презентацию.
Так это обычный Markdown или придётся учить новый синтаксис?Это Markdown: Quarkdown Flavor отталкивается от CommonMark и GFM и расширяет их вызовами функций, переменными, условиями и циклами, превращая Markdown в язык с полнотой по Тьюрингу.
Как его установить и скомпилировать первый документ?Установите через скрипт или Homebrew на Linux/macOS, через скрипт или Scoop на Windows, либо через GitHub Action setup-quarkdown. Затем 'quarkdown create' создаёт проект с помощью мастера, а 'quarkdown c file.qd' компилирует его.
Нужно ли что-то дополнительно на компьютере для экспорта в PDF?Только браузер на движке Chromium, например chrome-headless-shell. Скрипт установки для Linux/macOS настраивает браузер автоматически; при ручной установке его нужно поставить самому.
Он работает на Windows, как на Mac и Linux?Да — это кроссплатформенный CLI с отдельными способами установки для Linux и macOS (скрипт, Homebrew) и для Windows (скрипт, Scoop), плюс интеграция с GitHub Actions для сборок в CI.
Документы Quarkdown могут содержать код — может ли скачанный .qd-файл залезть в мою систему?Не как угодно: система разрешений ограничивает, что документы могут делать с системными ресурсами, и включена по умолчанию.
Он правда бесплатный или есть подвох с лицензией?Он бесплатный и открытый: по умолчанию GPLv3, а модули CLI и Language Server с их бинарниками — AGPLv3. Никаких платных тарифов нигде нет.
Во что именно может скомпилироваться один документ?В HTML в четырёх режимах — обычный непрерывный поток в стиле Notion/Obsidian, постраничный (через paged.js) для статей и книг, слайды через reveal.js и docs для вики — выбирается через .doctype {plain|paged|slides|docs}. Всё, что экспортируется в HTML, также экспортируется в PDF, а ещё есть экспорт в GFM Markdown или обычный текст.
Есть ли живой предпросмотр, пока я пишу?Да: компилируйте с -p (автоматическая перезагрузка) и -w (перекомпиляция при изменении файла) вместе для живого предпросмотра, и это быстро — официальная вики из 100+ подокументов компилируется примерно за 2 секунды. Интерактивный REPL доступен через 'quarkdown repl'.
Чем он сравним с LaTeX и Typst?По сравнительной таблице из README, Quarkdown — единственный инструмент в этой группе, сочетающий лаконичный синтаксис в духе Markdown с полноценным скриптингом и экспортом во все форматы: HTML, PDF, Markdown и обычный текст — включая презентации и docs/wiki, которых в LaTeX нет. Порог вхождения у него между AsciiDoc и Typst.
Есть ли инструменты для редакторов и ИИ-агентов для кодинга?Да — есть расширение для VS Code, неофициальный плагин для IntelliJ IDEA и встроенный skill, который заставляет кодинг-агентов писать идиоматичный Quarkdown; README даже даёт ссылку на его оценку.
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 15Releasev2.6.4Oct 09
Age
2y
Commits · 90 Days