/

Quarkdown

1.13.0

Docs

On this page

Quickstart

Welcome to Quarkdown! This guide walks you through the main features you need to create your first document.

If you use VS Code, we strongly recommend installing the official Quarkdown extension.

This guide provides a broad overview without diving deep into every detail. Each section includes links to other wiki pages where you can learn more about specific features.

Creating a document

Reference: Project Creator

To create a new document, run the project creator from your terminal:

quarkdown create my-document

This command creates a new folder named my-document. If you want to use the current working directory instead, you can omit the name.

For this quickstart, we recommend the following options:

Once the project is created, open my-document.qd in your favorite text editor. You can delete the existing content inside the first section if you want to start fresh.

## Quickstart

- Welcome to [Quarkdown](https://quarkdown.com)!
- This is the starting point of your document.
- ...

Choosing a document type

Reference: Document types

During the initial setup, you choose a document type from one of the following options:

Choosing a theme

Reference: Themes

Themes are split into two groups: color themes define the color scheme of a document, while layout themes set the general structural rules of the layout.

.theme {paperwhite} layout:{latex}

Some popular combinations include:

See Themes for a complete list of available themes.

Compiling

Reference: Compiler

Compile the document to make sure everything works as expected:

cd my-document
quarkdown c main.qd

You should see the HTML output inside the output directory.

To export to PDF, add the --pdf flag:

quarkdown c main.qd --pdf

See the PDF export page for more information about PDF export and its requirements. If you installed Quarkdown using a package manager or the install script, you should be ready to go.

Live preview

To launch live preview, append -p (preview) and -w (watch) to the compile command:

quarkdown c main.qd -p -w

This opens the default browser automatically. To use a different browser, specify it with the --browser option, for example --browser chrome.

If you use VS Code with the Quarkdown extension, you can launch the live preview by clicking the magnifying glass button or pressing Ctrl/Cmd+Shift+V.

Markup

Quarkdown builds upon Markdown and includes several GFM extensions. To try out basic markup, append the following to your document and experiment 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

![Logo](image/logo.png)
Markup

For a refresher on Markdown basics, see markdownguide.org.

Image size

References: Image size, Size

You might have noticed that the image in the previous example appears too large. Quarkdown overcomes this well-known Markdown limitation by allowing you to specify image dimensions:

!(50%)[Logo](image/logo.png)

Now the image is sized appropriately.

Image size

This sets the image width to 50% of the available width while maintaining the aspect ratio. Supported units include px, pt, cm, mm, in, and %. If you omit the unit, Quarkdown assumes px.

To specify both width and height:

!(6cm 2cm)[Logo](image/logo.png)

To specify only the height:

!(_ 2cm)[Logo](image/logo.png)

Figures

Reference: Figures

When an image stands alone, separated from other content, it automatically becomes a figure. Figures are centered and can have a caption.

Take the previous image:

!(50%)[Logo](image/logo.png)

You can add a caption by appending a title in quotes:

!(50%)[Logo](image/logo.png "The Quarkdown logo")
Figure

Equations and formulae

Reference: TeX formulae

You can include TeX equations using the $ expression $ syntax. Note that whitespace matters.

Add the following to the bottom of your document:

#### Equations

$ E = mc^2 $ is Einstein's mass-energy equivalence formula.

$ f(x, y) = \frac{x}{y} $

Notice that the second equation appears centered on its own line, even though it uses the same syntax. Just like figures, isolated equations automatically become block equations.

Equations

Function call syntax

Reference: Syntax of a function call

Before exploring more features, let’s look at Quarkdown’s function call syntax.

Function calls start with a dot and use curly braces for arguments. Arguments can be positional or named:

.pow {5} to:{2} is a mathematical operation.

Function calls can be inline or block, depending on whether they appear within other content or stand alone.

Block function calls also support an indented block argument, which always corresponds to the last parameter of the function:

.align {center}
    This multi-line paragraph is the block argument,
    and it's now centered in the document.

You can chain multiple function calls together, where the output of one becomes the first argument of the next:

Example 1

.sqrt {10}::round::multiply {2}

6

you can find a full list of available functions in the documentation.

Variables

Reference: Variables

Define a variable using the .var function and access it like any other function:

.var {name} {John}

My name is .name

To change a variable’s value, call it with a new argument:

.name {Jane}

Custom elements

Reference: Declaring functions, Boxes

You can define custom functions using .function. Functions are reusable components that encapsulate logic and content. In this section, we create a function that generates an Example box, commonly used in educational documents.

Start by defining a function without parameters:

.docauthors
    - ...

.function {example}
    .box {Example} type:{tip}
        This is my example!

## Quickstart
...

Now call it:

## Quickstart

.example

...

Calling .example produces a nicely formatted box.

Let’s enhance the function by adding a parameter for the box content. The syntax for parameters is param1 param2 param3:.

.function {example}
    content:
    .box {Example} type:{tip}
        .content

Update the call accordingly:

.example
    This is my example!
Custom element

Congratulations! You’ve created your first reusable element using boxes. Many more layout tools are available, such as containers and stacks.

For advanced styling of custom elements, you can use CSS rules. See CSS for more information.

For the sake of simplicity, let’s remove the function call for now:

- .example
-    This is my example!

Numbering

Reference: Numbering

Many documents, especially academic ones, require numbered elements such as sections, figures, tables, equations, and code. In Quarkdown, you can achieve this using the .numbering function.

Documents with the paged type come with default numbering enabled.

Add a numbering scheme at the top of your document, right before the content begins:

.docauthors
    - ...

.numbering
    - headings: 1.1.1
    - figures: 1.1

.function {example}
    ...

## Quickstart
...

This YAML-like syntax represents a dictionary data type.

Numbering

Valid symbols for numbering formats are:

Any other character is treated as literal text.

Table of contents

Reference: Table of contents

Longer documents often include a table of contents at the beginning that lists all sections and subsections.

In Quarkdown, simply call the .tableofcontents function where you want the table of contents to appear:

.numbering
    - ...

.tableofcontents

## Quickstart
...

Footnotes

Reference: Footnotes

Footnotes let you add additional information without cluttering the main text. Let’s add a footnote to our introduction:

### 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. Quarkdown also supports compact footnotes, which let you define a footnote inline, right where you reference it:

and much more[^: All Markdown features are supported in Quarkdown].

In plain documents, footnotes appear in the margin next to the reference, similar to side notes. In paged and slides documents, footnotes appear at the bottom of the page or slide.

Cross-references

Reference: Cross-references

Cross-references let you refer to numbered elements elsewhere in your document.

First, add an ID to the target element. Then reference it using the .ref {id} function.

Take 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}.
Cross-reference

See Cross-references to learn how to add IDs to other elements, such as sections, tables, equations, and code blocks.

Page margins and counter

References: Page format, Page margin content, Page counter

In paged and slides documents, you typically want a page counter to help readers navigate and understand where they are in the document.

First, switch to the paged document type by changing the .doctype value at the top of your document:

- .doctype {plain}
+ .doctype {paged}

The default page format is A4. You can change it, along with other properties, using the .pageformat function:

.pageformat {letter} margin:{2cm}

Now add a page counter to the bottom center of each page:

.docauthors
    - ...

.pagemargin {bottomcenter}
    .currentpage / .totalpages

.numbering
    - ...

Each page now displays its number and the total number of pages.

The .pagemargin function can add any kind of content to each page. See Page margin content for all available margin positions.

Persistent headings

Reference: Persistent headings

Page margins can also display the current section title on each page. The following example shows the current level-1 heading in the bottom left margin:

.pagemargin {bottomcenter}
    ...

.pagemargin {bottomleft}
    .lastheading depth:{1}

.numbering
    - ...

Multi-file projects

Reference: Inclusion vs. subdocuments

There are two main ways to split a large document into multiple source files: inclusion and subdocuments.

Including files

Reference: Including other Quarkdown files

The .include function inserts the content of another Quarkdown file into the current one. This approach is common in LaTeX and other markup languages for splitting a large document into smaller, more manageable files, such as one per chapter or section.

For our quickstart, we could 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
-
- .pagemargin {bottomleft}
-     .lastheading depth:{1}
-
- .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, consider using .includeall instead:

.includeall
    - setup.qd
    - content.qd

Referencing files

Reference: Subdocuments

The second approach uses subdocuments, which are particularly common for knowledge bases and wikis.

Subdocuments are independent units of content that share the same setup and configuration. You can reference them from other documents through links.

my-document.qd

- [Introduction](introduction.qd)
- [Chapter 1](chapter1.qd)
- [Chapter 2](chapter2.qd)
- [Conclusion](conclusion.qd)

You can also visualize the knowledge graph formed by subdocuments:

.subdocumentgraph
Subdocuments

Conclusion

Congratulations! You have completed the Quarkdown quickstart guide and are now familiar with its main features. You are ready to create your first real document.

From here, you can explore more advanced topics in the rest of this wiki and in the documentation.