-
-
Notifications
You must be signed in to change notification settings - Fork 212
Quickstart
Welcome to Quarkdown! In this page, we'll explore the main steps and features that will help you create your first document.
Tip
If you're using VS Code, we strongly recommend installing the official Quarkdown extension.
This guide provides a shallow overview and won't go into the specific details of each feature. In each section you'll find links to other wiki pages for in-depth explanations of relevant features we'll be using.
Reference: Project Creator
To create a new document, run the project creator from your terminal:
quarkdown create my-document
This will create a new folder named my-document
.
If you wish to use the working directory instead, you can omit the name.
For this quickstart, we recommend the following options:
- Project name:
Quickstart
- Authors: <your name>
- Document type:
plain
- Document language:
English
Once the project is created, open my-document.qd
in your favorite text editor.
You may also delete the existing content inside the first section.
# Quickstart
- Welcome to [Quarkdown](https://quarkdown.com)!
- This is the starting point of your document.
- ...
Reference: Document types
During the initial setup, you'll be asked to choose a document type, which can be one of the following:
-
plain
- Continuous flow like Notion/Obsidian, great for knowledge management and web viewing. -
paged
- Traditional document with page breaks, ideal for PDFs. -
slides
- Presentation format with interactive navigation.
Reference: Themes
Themes are split into two groups: color themes, which define the color scheme of a document, and layout themes, which set the general structural rules of the layout.
.theme {paperwhite} layout:{latex}
Popular combinations are:
-
paperwhite + latex
- Clean academic look (default) -
darko + minimal
- Dark theme with minimal styling -
beaver + beamer
- Academic presentation style
See Themes for a complete list of available themes.
Reference: Compiler
Compile the document to ensure everything is working as expected:
cd my-document
quarkdown c my-document.qd
You should see the HTML output inside the output
directory. Great!
To export to PDF:
quarkdown c my-document.qd --pdf
See the PDF export page for more information about PDF export and its requirements. If you installed Quarkdown via a package manager or install script, you should be all set.
To launch live preview, append -p
(preview) and -w
(watch) to the compile command:
quarkdown c my-document.qd -p -w
This launches the default browser by default.
To use a different one, use, for example, --browser chrome
.
If you're using VS Code with the Quarkdown extension,
you can launch the live preview using the corresponding 🔍 button
or pressing Ctrl/⌘+Shift+V
Quarkdown is built upon Markdown, with several GFM extensions.
To try out basic markup within Quarkdown, you can append the following to the existing content of my-document.qd
,
and feel free to play around with it:
## A Quarkdown tour
No need to reinvent the wheel: you can make text **bold** or *italic*,
~~strike through~~, add `inline code`,
create [links](https://quarkdown.com), and much more.
- An unordered list
- With multiple items
1. An ordered list
2. With multiple items


You may refer to resources such as markdownguide ↗ to know more about Markdown.
References: Image size, Size
You might have noticed the image in the previous example was way too large.
Quarkdown overcomes a well-known Markdown limitation by allowing image size specification:
!(50%)[Logo](image/logo.png)
Great! The image is now perfectly sized.

This sets the image width to 50% of the available width, while keeping the aspect ratio.
Supported units include px
, pt
, cm
, mm
, in
, and %
.
If the unit is omitted, px
is assumed.
If you wish to specify both width and height:
!(6cm 2cm)[Logo](image/logo.png)
If you wish to specify only the height:
!(_ 2cm)[Logo](image/logo.png)
Reference: Figures
When an image is isolated from other content, like in the previous example, it becomes a figure, which is automatically centered and can have a caption.
Let's go to the previous image:
!(50%)[Logo](image/logo.png)
and enhance it with a caption:
!(50%)[Logo](image/logo.png "The Quarkdown logo")

Reference: TeX formulae
TeX equations can be included by means of the $ expression $
syntax (beware of whitespaces).
Let's try adding equations to the bottom of our document:
### Equations
$ E = mc^2 $ is Einstein's mass-energy equivalence formula.
$ f(x, y) = \frac{x}{y} $
You might notice that, despite having the same syntax, the second appears centered and on its own line. Just like figures, isolated equations automatically become block equations.

Reference: Syntax of a function call
Before going deeper into other features, let's briefly explore Quarkdown's function call syntax.
Function calls start with a dot and use curly braces for arguments, which may be positional or named:
.pow {5} to:{2} is a mathematical operation.
Function calls can be inline or block, depending on whether they are isolated or not from other content.
Block function calls also allow an indented block argument, which always refers to the last parameter of the function, positionally speaking:
.align {center}
This multi-line paragraph is the block argument,
and it's now centered in the document.
Multiple function calls can also be chained together, so that the output of one refers to the first parameter of the next:
.sqrt {10}::round::multiply {2} <!-- 6 -->
Tip
A full list of available functions can be found in the docs.
Reference: Variables
A variable is defined using the .var
function,
and can be accessed like any function.
.var {name} {John}
My name is .name
A variable can be overwritten by supplying an argument:
.name {Jane}
Reference: Numbering
Many documents, especially academic ones, require some elements to be numbered, such as sections, figures, tables, equations and code. In Quarkdown, this can be achieved using the .numbering
function.
Note
paged
documents come with a default numbering.
Head to the top of our document's source code, right before the beginning of content, and set up a simple numbering scheme:
.docauthors
- ...
.numbering
- headings: 1.1.1
- figures: 1.1
# Quickstart
...
This YAML-like syntax represents a dictionary data type.

Valid symbols are:
-
1
(decimal) -
A
(uppercase letters) -
a
(lowercase letters) -
I
(uppercase Roman numerals) -
i
(lowercase Roman numerals)
Any other character will be treated as literal text.
Reference: Table of contents
It's common for longer documents to have a table of contents at the beginning, listing all sections and subsections.
In Quarkdown, it's as easy as calling the .tableofcontents
function where you want the table of contents to appear, for example before the first section:
.numbering
- ...
.tableofcontents
# Quickstart
...
Reference: Footnotes
Footnotes are a great way to add additional information without cluttering the main text. For our quickstart, let's go back to our introduction and add a footnote to it:
## A Quarkdown tour
No need to reinvent the wheel: you can make text **bold** or *italic*,
~~strike through~~, add `inline code`,
create [links](https://quarkdown.com), and much more[^1].
[^1]: All Markdown features are supported in Quarkdown
This is the GFM footnote syntax, which Quarkdown fully supports, along with compact footnotes, which allow defining a footnote inline, right where it's referenced:
and much more[^: All Markdown features are supported in Quarkdown].
In plain
documents, footnotes are more like side notes, and appear in the margin, next to the reference.
In paged
and slides
documents, footnotes appear at the bottom of the page or slide.
Reference: Cross-references
Cross-references allow referring to other elements in the document which can be numbered.
The first step is to add an ID to the target element.
After that, the element can be referenced using the .ref {id}
function.
Let's go back to our figure:
!(50%)[Logo](image/logo.png "The Quarkdown logo")
add the logo
ID to it, and reference it in the text:
!(50%)[Logo](image/logo.png "The Quarkdown logo") {#logo}
The Quarkdown logo is shown in .ref {logo}.

See Cross-references to learn how to add IDs to other elements, such as sections, tables, equations and code blocks.
References: Page format, Page margin content, Page counter
In paged
and slides
documents, you'll likely need a page counter
to improve navigation and provide context to readers.
First off, let's switch to the paged
document type by changing .doctype
's value at the top of our document:
- .doctype {plain}
+ .doctype {paged}
The default page format is A4. Along with other properties, it can be changed using the
.pageformat
function:.pageformat {letter} margin:{2cm}
Let's now add a page counter to the bottom-center area of each page:
.docauthors
- ...
.pagemargin {bottomcenter}
.currentpage / .totalpages
.numbering
- ...
This way, each page will show its number, and the total number of pages.
In general, .pagemargin
can be used to add any kind of content to each page.
See Page margin content to see the available margin positions.
Reference: Inclusion vs. subdocuments
There are two main ways to split a large document into multiple source files: inclusion and subdocuments.
Reference: Including other Quarkdown files
The .include
function allows including the content of another Quarkdown file
into the current one.
This approach is common in LaTeX and other markup languages, in order to split a large document into smaller, more manageable files, such as one per chapter or section.
For our quickstart, we could decide to split setup and content into two separate files:
my-document.qd
- .docname {Quickstart}
- .doctype {paged}
- .doclang {English}
- .theme {paperwhite} layout:{latex}
-
- .docauthors
- - ...
-
- .pagemargin {bottomright}
- .currentpage / .totalpages
-
- .numbering
- - headings: 1.1.1
- - figures: 1.1
+ .include {setup.qd}
+ .include {content.qd}
- .tableofcontents
-
- # Quickstart
-
- ...
setup.qd
.docname {MyDocument}
.doctype {paged}
.doclang {English}
.theme {paperwhite} layout:{latex}
.docauthors
- Quarkdown
.pagemargin {bottomright}
.currentpage / .totalpages
.numbering
- headings: 1.1.1
- figures: 1.1
content.qd
.tableofcontents
# Quickstart
...
Here we used .include
twice. For a larger number of files,
you might consider using .includeall
instead:
.includeall
- setup.qd
- content.qd
Reference: Subdocuments
The second approach involves subdocuments, particularly common in the area of knowledge bases and wikis.
Subdocuments are independent units of content which share the same setup and configuration, and can be referenced from other documents through links.
my-document.qd
- [Introduction](introduction.qd)
- [Chapter 1](chapter1.qd)
- [Chapter 2](chapter2.qd)
- [Conclusion](conclusion.qd)
The knowledge graph formed by subdocuments can also be visualized:
.subdocumentgraph

Congratulations! You've completed the Quarkdown quickstart guide and are now familiar with its main features that will assist you with your first real document.
From here, you can explore more advanced topics in the wiki and docs.
- Figures
- Image size
- TeX formulae
- Table caption
- Code caption
- Decorative headings
- Alerts (quote types)
- Quotation source
- Cross-references
- Page breaks
- Text symbols (text replacement)
- Document metadata
- Theme
- CSS
- Fonts
- Page format
- Page margin content
- Page counter
- Automatic page break
- Numbering
- Paragraph style
- Caption position
- Table of contents
- Bibliography
- Footnotes
- Stacks (row, column, grid)
- Container
- Align
- Float
- Figure
- Clip
- Box
- Collapsible
- Landscape
- Whitespace
- Variables
- Optionality
- Math
- Conditional statements
- Loops
- Let
- Destructuring
- String manipulation
- Table manipulation: sorting, computing, and more
- Generators
- String
- Number
- Markdown content
- Boolean
- None
- Enumeration entry
- Iterable
- Dictionary
- Range
- Lambda
- Size(s)
- Color
- Dynamic
- Paper: abstract, definitions, theorems, and more