### Example 1: _setup.qd configuration

Source: https://quarkdown.com/wiki/docs-library.md

Example _setup.qd file with language, theme, and a page margin link. This file is included automatically by the library.

```markdown
.doclang {English}
.theme {darko} layout:{minimal}

.pagemargin {topright}
    [GitHub](https://github.com/iamgio/quarkdown)
```

--------------------------------

### Example 2: _nav.qd navigation

Source: https://quarkdown.com/wiki/docs-library.md

Example _nav.qd file with navigation links grouped by decorative headings. The current page is automatically highlighted in the sidebar.

```markdown
###! Getting started
- [Quickstart](quickstart.qd)

###! Topics
- [Page 1](page-1.qd)
- [Page 2](page-2.qd)
  - [Section A](page-2.qd#section-a)
```

--------------------------------

### Context sharing setup files

Source: https://quarkdown.com/wiki/including-other-quarkdown-files.md

Defines the source files used to demonstrate context sharing behavior.

```markdown
.docname {New name}

.function {greet}
  name:
  Hello, **.name**!
```

```markdown
.docname {My document}
.include {file.qd} sandbox:{<value>}

1. .docname
2. .greet {John}
```

--------------------------------

### Document setup inclusion

Source: https://quarkdown.com/wiki/including-other-quarkdown-files.md

Shows how to move document configuration into a separate setup.qd file and include it in the main document.

```markdown
.docname {My document}
.docauthor {iamgio}
.doctype {slides}
.doclang {English}
.theme {darko} layout:{minimal}

.footer
   ...
```

```markdown
.include {setup.qd}

# My cool document

...
```

--------------------------------

### Example 1: .text with variant, size, and decoration

Source: https://quarkdown.com/wiki/text.md

Shows a Markdown example using the .text function with the variant:{smallcaps} option in a heading and size:{large} decoration:{underoverline} in a paragraph. The rendered output is also displayed.

```markdown
##! A demo of .text {Quarkdown} variant:{smallcaps}

The .text {quick brown fox} size:{large} decoration:{underoverline} jumps over the lazy dog.
```

--------------------------------

### Initial document content example

Source: https://quarkdown.com/wiki/quickstart.md

The default content structure found in a newly created .qd file.

```diff
## Quickstart

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

--------------------------------

### Print install directory with quarkdown doctor get install-dir

Source: https://quarkdown.com/wiki/cli-doctor.md

Prints the absolute path of the Quarkdown install directory (root containing bin/, lib/, docs/). Useful for locating bundled resources from shell scripts.

```shell
quarkdown doctor get install-dir
```

--------------------------------

### Styled container example

Source: https://quarkdown.com/wiki/container.md

Example 4 demonstrates styling a container with parameters like `fullwidth`, `borderstyle`, `padding`, `fontsize`, `fontstyle`, and `fontvariant`. The container accepts all element styling options.

```markdown
.container fullwidth:{yes} borderstyle:{dashed} padding:{1cm} fontsize:{medium} fontstyle:{italic} fontvariant:{smallcaps}
    This is a styled container. Fancy, isn't it?

    Quarkdown can truly give life to complex layouts with ease.
```

--------------------------------

### Simple chaining example

Source: https://quarkdown.com/wiki/syntax-of-a-function-call.md

A simpler example of chaining to understand the transformation. The compiler transforms .myvar::uppercase into .uppercase {.myvar}.

```markdown
.myvar::uppercase
```

--------------------------------

### Define a basic function

Source: https://quarkdown.com/wiki/localization.md

An example of defining a simple .theorem function that displays a static string.

```markdown
.function {theorem}
    **Theorem.**

.theorem This is my theorem
```

--------------------------------

### Full example of custom numbered elements

Source: https://quarkdown.com/wiki/numbering.md

Demonstrates multiple numbered blocks using the 'greetings' key with a '1.a' format.

```markdown
.numbering
    - headings: 1.1
    - greetings: 1.a

## Title 1

.numbered {greetings}
    number:
    **Hello!** This block has the number **.number**

.numbered {greetings}
    number:
    **Hey!** This has instead the number **.number**

## Title 2

.numbered {greetings}
    number:
    **Hi!** Here we have the number **.number**
```

--------------------------------

### BibTeX Entry Examples

Source: https://quarkdown.com/wiki/bibliography.md

Example BibTeX entries for an article and a book.

```text
@article{einstein,
  author = "Albert Einstein",
  ...
}

@book{hawking,
  author = "Stephen Hawking",
  ...
}
```

--------------------------------

### Configure Code Block Numbering

Source: https://quarkdown.com/wiki/numbering.md

Example 6 demonstrates how to enable numbering for code blocks using the .numbering configuration.

```markdown
.numbering
    - code: 1

```python
def hello():
    print("Hello, world!")
```

```kotlin
fun main() {
    println("Hello, world!")
}
```
```

--------------------------------

### Markdown input example

Source: https://quarkdown.com/wiki/pipeline---rendering.md

Example Markdown input used to illustrate the rendering process. It includes a heading, bold and italic text, and a list.

```markdown
## Title

This is **bold** and _italic_ text.

- Item 1
- Item 2
```

--------------------------------

### Multi-line arguments example

Source: https://quarkdown.com/wiki/syntax-of-a-function-call.md

Shows a function call with arguments spanning multiple lines. The indentation is optional and arbitrary. The output of this example is -0.33333334.

```markdown
.divide {
    .cos {.pi}
} by:{
    .sum {2} {1}
}
```

--------------------------------

### Configure Equation Numbering with Cross-References

Source: https://quarkdown.com/wiki/numbering.md

Example 4 shows how to enable equation numbering using cross-reference IDs.

```markdown
.numbering
    - equations: (1)

$ E = mc^2 $ {#energy}

$ F = ma $ {#force}
```

--------------------------------

### Use install-dir in a shell script to list docs

Source: https://quarkdown.com/wiki/cli-doctor.md

Captures the install directory into a variable and lists its docs folder, avoiding manual binary path resolution.

```shell
INSTALL="$(quarkdown doctor get install-dir)"
ls "$INSTALL/docs"
```

--------------------------------

### Configure Table Numbering

Source: https://quarkdown.com/wiki/numbering.md

Example 3 demonstrates how to set table numbering to a decimal format using the .numbering configuration block.

```markdown
.numbering
    - headings: 1.A.a
    - tables: 1.1

## Title

|           | Age | Favorite food |
|-----------|-----|---------------|
| **Anne**  | 24  | Hamburger     |
| **Lucas** | 19  | Pizza         |
| **Joe**   | 32  | Sushi         |
"Study results."

### Title

|           | Age | Favorite food |
|-----------|-----|---------------|
| **Anne**  | 24  | Hamburger     |
| **Lucas** | 19  | Pizza         |
| **Joe**   | 32  | Sushi         |

## Title

|           | Age | Favorite food |
|-----------|-----|---------------|
| **Anne**  | 24  | Hamburger     |
| **Lucas** | 19  | Pizza         |
| **Joe**   | 32  | Sushi         |
```

--------------------------------

### Float an image with alignment start

Source: https://quarkdown.com/wiki/float.md

Use .float {start} to float an image to the start (left) and allow text to wrap around it. The image is included with the !(70%)[Icon](assets/icon.svg) syntax.

```markdown
.float {start}
    !(70%)[Icon](assets/icon.svg)

.loremipsum
```

--------------------------------

### Positional argument example

Source: https://quarkdown.com/wiki/syntax-of-a-function-call.md

An example of a function call using positional arguments.

```markdown
.multiply {6} {3}
```

--------------------------------

### Create a full-bleed cover page

Source: https://quarkdown.com/wiki/book-cover.md

This example demonstrates how to configure the first page of a document to have no margins and a full-width image.

```markdown
.doctype {paged}

.pageformat pages:{..1} margin:{0}

.container fullwidth:{yes} margin:{0}
    !(100%)[Cover](cover.png)

# Introduction

...
```

--------------------------------

### Inline content example with .box

Source: https://quarkdown.com/wiki/markdown-content.md

Shows how to pass inline content to a function like .box. The content includes text and emphasis.

```markdown
.box {My _box_ title}
    ...
```

--------------------------------

### Chaining with variable declaration example

Source: https://quarkdown.com/wiki/syntax-of-a-function-call.md

Declares a variable and then uses chaining to call a function on it. The output of this example is HELLO!.

```markdown
.var {myvar} {hello!}

.myvar::uppercase
```

--------------------------------

### Example 2: Function definition and usage with .sourceresult

Source: https://quarkdown.com/wiki/typing.md

Defines a function 'sourceresult' that takes a 'source' argument, displays it as code via .code, and also parses it as Markdown content. The example shows the function definition, the source passed to it, and the resulting rendered output.

```markdown
.function {sourceresult}
    source:
    .code {markdown}
        .source
    .source

.sourceresult
    ##! Quarkdown 

    Quarkdown was born in **.sum {2000} {24}**

```

```markdown
##! Quarkdown 

Quarkdown was born in **.sum {2000} {24}**

```

--------------------------------

### Example 3: Override sidebar positions

Source: https://quarkdown.com/wiki/docs-library.md

Override the default sidebar positions by setting pagelistposition and tocposition variables in _setup.qd. This example swaps the left and right sidebars.

```markdown
.theme {darko}

.pagelistposition {righttop}
.tocposition {lefttop}
```

--------------------------------

### Format page numbers

Source: https://quarkdown.com/wiki/page-counter.md

Example showing how to use .formatpagenumber to change the numbering style to lowercase roman numerals starting from the second page.

```markdown
.pagemargin {topcenter}
    .currentpage

# First page

.formatpagenumber {i}

# Second page

# Third page
```

--------------------------------

### Markdown decorative heading example

Source: https://quarkdown.com/wiki/decorative-headings.md

Shows a markdown example with a decorative heading '#!' that is not numbered and not in the table of contents, followed by a regular heading and a loremipsum placeholder.

```markdown
```markdown
.center
    #! My document

## Introduction

.loremipsum
```
```

--------------------------------

### Reset page number

Source: https://quarkdown.com/wiki/page-counter.md

Example showing how to use .resetpagenumber to set the page number to 20 starting from the third page.

```markdown
.pagemargin {topcenter}
    .currentpage

# First page

# Second page

.resetpagenumber start:{20}

# Third page
```

--------------------------------

### Custom figure syntax example

Source: https://quarkdown.com/wiki/custom-figure.md

Demonstrates the use of .figure with a caption and a nested container block.

```markdown
.figure caption:{My caption.}
    .container padding:{1cm} background:{teal}
        Hello, world!
```

--------------------------------

### Markdown inline elements example

Source: https://quarkdown.com/wiki/pipeline---lexing.md

Example of markdown syntax representing inline-level elements like bold and italics.

```markdown
A **formatted** _text_.
```

--------------------------------

### Em-dash replacement example

Source: https://quarkdown.com/wiki/text-symbols.md

Demonstrates the automatic replacement of double hyphens with an em-dash.

```markdown
"Quarkdown"--a typesetting system--supports automatic text replacements.
```

--------------------------------

### Inline function call example (Example 9)

Source: https://quarkdown.com/wiki/syntax-of-a-function-call.md

Demonstrates an inline function call embedded within text. The call '.sum {26} {16}' is replaced by its output (42) in the parent block.

```markdown
Ever wondered what **26+16** equals? It's .sum {26} {16}. Here you go.
```

--------------------------------

### Mixed positional and named arguments

Source: https://quarkdown.com/wiki/syntax-of-a-function-call.md

An example demonstrating how to mix positional and named arguments. Note that all arguments following a named argument must also be named.

```markdown
.multiply {6} by:{3}
```

--------------------------------

### Block content example with .center

Source: https://quarkdown.com/wiki/markdown-content.md

Shows how to pass block content to a function like .center. Includes a heading, paragraph, blockquote, and a nested .row function call.

```markdown
.center
    # My centered title

    This is a paragraph in a **centered** block!

    > This is a _blockquote_.
    >
    > It spans over multiple sub-paragraphs.

    <!-- A nested block function call -->
    .row
        ...
```

--------------------------------

### HTML output example

Source: https://quarkdown.com/wiki/pipeline---rendering.md

The HTML output generated from the Markdown input, showing the translation of the AST into HTML elements.

```html
<h1>Title</h1>
<p>This is <strong>bold</strong> and <em>italic</em> text.</p>
<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>
```

--------------------------------

### Markdown block elements example

Source: https://quarkdown.com/wiki/pipeline---lexing.md

Example of markdown syntax representing block-level elements like headings, paragraphs, quotes, and lists.

```markdown
# A heading

A paragraph

> A quote

- A list
- of multiple items
```

--------------------------------

### Grid with columns and alignment

Source: https://quarkdown.com/wiki/stacks.md

Example 4: A .grid stack with 2 columns and spacearound alignment, containing four blocks: A, *B*, **C**, and ***D***.

```markdown
.grid columns:{2} alignment:{spacearound}
    A

    *B*

    **C**

    ***D***

```

--------------------------------

### Define a size group

Source: https://quarkdown.com/wiki/sizes.md

Example of using a vertical/horizontal size group for padding.

```markdown
.container padding:{10px 60px} background:{teal}
    Quarkdown
```

--------------------------------

### Apply paragraph style with lineheight, spacing, and indent

Source: https://quarkdown.com/wiki/paragraph-style.md

Example of using .paragraphstyle to set specific line height, paragraph spacing, and indentation values.

```markdown
.paragraphstyle lineheight:{2.5} spacing:{0} indent:{2}
```

--------------------------------

### Chaining with additional arguments example

Source: https://quarkdown.com/wiki/syntax-of-a-function-call.md

Shows appending an additional argument to a function in a chain. The chained value is always the first argument of the next call. The output of this example is 30.

```markdown
.sum {10} {5}::multiply {2}
```

--------------------------------

### Define a single size

Source: https://quarkdown.com/wiki/sizes.md

Example of using single size values with units in a container definition.

```markdown
.container width:{50px} height:{2cm} background:{teal}
```

--------------------------------

### Row with images

Source: https://quarkdown.com/wiki/stacks.md

Example 3: A .row stack containing two image blocks, each on its own line with a blank line between them.

```markdown
.row
    ![](assets/icon.svg)

    ![](assets/icon.svg)

```

--------------------------------

### Declaring only used parameters in .extend

Source: https://quarkdown.com/wiki/extending-functions.md

All wrapper parameters are optional; you only need to declare the ones you use. This example only declares 'name' and uppercases it, leaving other parameters unchanged.

```markdown
.function {greet}
    greeting name surname:
    .greeting, .name .surname!

.extend {greet}
    name:
    .super name:{.name::uppercase}

.greet {Hello} name:{John} surname:{Doe}
```

```text
Hello, JOHN Doe!
```

--------------------------------

### Correct approach: row with containers

Source: https://quarkdown.com/wiki/container.md

Example 3 shows the correct way to achieve the desired layout. Each `.container` resets the layout rules, allowing the row to treat them as separate blocks of content.

```markdown
<!-- Correct! -->
.row alignment:{center} gap:{1cm}
    .container
        ##! Left
        Text on left column.

    .container
        ##! Right
        Text on right column.
```

--------------------------------

### Define setup.qd

Source: https://quarkdown.com/wiki/quickstart.md

Configuration file containing document metadata and formatting settings.

```markdown
.docname {MyDocument}
.doctype {paged}
.doclang {English}
.theme {paperwhite} layout:{latex}

.docauthors
    - Quarkdown

.pagemargin {bottomright}
    .currentpage / .totalpages

.numbering
    - headings: 1.1.1
    - figures: 1.1

.extend {heading}
    ...
```

--------------------------------

### Clip general content to a circle

Source: https://quarkdown.com/wiki/clip.md

Clipping works with any content, not just images. This example clips a container with padding and background color.

```markdown
.clip {circle}
    .container padding:{2cm} background:{teal}
        #! Hello!
```

--------------------------------

### Composed row and column stacks

Source: https://quarkdown.com/wiki/stacks.md

Example 5: A .row stack with spacearound alignment containing two .column stacks, each with a name, company, and email link.

```markdown
.row alignment:{spacearound}
    .column
        **Michael Scott**

        Dunder Mifflin Paper Company, Inc.

        [michaelscott@example.com](mailto:michaelscott@example.com)

    .column
        **Forrest Gump**

        Bubba Gump Shrimp Co.

        [forrestgump@example.com](mailto:forrestgump@example.com)

```

--------------------------------

### Include files in my-document.qd

Source: https://quarkdown.com/wiki/quickstart.md

Demonstrates replacing document content with .include directives for setup.qd and content.qd.

```diff
- .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
-
- .extend {heading}
-     ...

+ .include {setup.qd}
+ .include {content.qd}

- .tableofcontents
-
- # Quickstart
-
- ...
```

--------------------------------

### Example 1: Dynamic value conversion in .if and .uppercase

Source: https://quarkdown.com/wiki/typing.md

Shows a variable holding a boolean true being used in .if (expects Boolean) and .uppercase (expects String). The output 'My value is TRUE' demonstrates the conversion.

```markdown
.var {myvar} {true}

.if {.myvar}
    My value is .uppercase {.myvar}

```

--------------------------------

### Repeat a block with .repeat

Source: https://quarkdown.com/wiki/loops.md

Example 5: Uses .repeat {3} as a shorthand for .foreach {1..3}. The implicit first parameter .1 is output for each iteration.

```markdown
.repeat {3}
    .1
```

--------------------------------

### Launch live preview

Source: https://quarkdown.com/wiki/quickstart.md

Uses the -p and -w flags to enable live preview and file watching.

```shell
quarkdown c main.qd -p -w
```

--------------------------------

### Iterate with implicit first parameter .1

Source: https://quarkdown.com/wiki/loops.md

Example 2: Uses .foreach with a range {1..3} and the implicit first parameter .1. The lambda's first parameter is referenced as .1.

```markdown
.row alignment:{spacearound}
    .foreach {1..3}
        .1
```

--------------------------------

### Markdown image reference with media storage

Source: https://quarkdown.com/wiki/media-storage.md

Example of a Markdown image reference that triggers media storage. The source path '../my-img.png' is copied to the media directory and the image node is updated to point to the new file.

```markdown
![Image](../my-img.png)
```

--------------------------------

### Iterate over a range with .foreach

Source: https://quarkdown.com/wiki/loops.md

Example 1: Uses .foreach with a range {2..4} and a lambda parameter n to output the current item. The result is an ordered iterable collection of the same size as the input.

```markdown
.foreach {2..4}
    n:
    The number is: **.n**
```

--------------------------------

### Print agent skill directory with quarkdown doctor get agent-skill

Source: https://quarkdown.com/wiki/cli-doctor.md

Prints the absolute path of the bundled agent skill directory containing the SKILL.md entrypoint for AI agent tools.

```shell
quarkdown doctor get agent-skill
```

--------------------------------

### Include an external file

Source: https://quarkdown.com/wiki/including-other-quarkdown-files.md

Demonstrates how to include the content of file.qd into main.qd.

```markdown
### Hello Quarkdown

This is external content.
```

```markdown
.include {file.qd}
```

--------------------------------

### Per-range formatting with pages parameter

Source: https://quarkdown.com/wiki/page-format.md

Restricts the format to an inclusive range of page indices (1-based). This example applies a 3cm margin to pages 2 through 5.

```markdown
.pageformat pages:{2..5} margin:{3cm}
```

--------------------------------

### Create and iterate a collection from a Markdown list

Source: https://quarkdown.com/wiki/iterable.md

Example 1: A Markdown list is automatically converted to an ordered collection. The .var directive assigns the list to a variable, and .foreach iterates over it, applying the .1::lowercase operation to each element.

```markdown
.var {letters}
    - A
    - B
    - C

.foreach {.letters}
    .1::lowercase
```

--------------------------------

### Basic .row stack with gap

Source: https://quarkdown.com/wiki/stacks.md

Example 1: A .row stack with a 1cm gap between three separate blocks (A, B, C). Each block is a separate paragraph, so they are treated as distinct items.

```markdown
.row gap:{1cm}
    A

    B

    C

```

--------------------------------

### Initialize Bibliography

Source: https://quarkdown.com/wiki/bibliography.md

Use the .bibliography function to include a bibliography file in your document.

```markdown
.bibliography {bibliography/file.bib}
```

--------------------------------

### Nested function calls example

Source: https://quarkdown.com/wiki/syntax-of-a-function-call.md

Shows a function call nested within an argument to compose a complex expression. The output of this example is 28.274334.

```markdown
.multiply {.pow {3} to:{2}} by:{.pi}
```

--------------------------------

### Create a new project with the CLI

Source: https://quarkdown.com/wiki/quickstart.md

Run this command in your terminal to initialize a new project folder. Omitting the name will use the current working directory.

```shell
quarkdown create my-document
```

--------------------------------

### Chapter navigation pattern with .marker and focus

Source: https://quarkdown.com/wiki/table-of-contents.md

Defines a custom .chapter function that combines .tableofcontents with maxdepth:{0} and focus:{.name} along with .marker {.name} to create a chapter-level overview for slide presentations. Invoke with .chapter {My chapter} at the start of each section.

```markdown
.function {chapter}
    name:
    .tableofcontents maxdepth:{0} focus:{.name}
    .marker {.name}
```

--------------------------------

### Create Multi-Series XY Chart with Categorical Tags

Source: https://quarkdown.com/wiki/xy-chart.md

Example 6 shows how to use .tablecolumns to extract multiple columns for lines and the first column for X-axis categorical tags.

```markdown
.var {columns}
    .tablecolumns
        .csv {assets/sales.csv}

.xychart xtags:{.columns::first} x:{Years} y:{Sales}
    .columns::second
    .columns::third
```

```mermaid
xychart-beta
	x-axis "Years" [2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025]
	y-axis "Sales"
	line [230.0, 190.0, 180.0, 175.0, 200.0, 250.0, 290.0, 350.0, 470.0]
	line [85.0, 100.0, 135.0, 180.0, 240.0, 320.0, 430.0, 580.0, 800.0, 0.0]
```

--------------------------------

### Example 3: Use `.let` with implicit positional parameters

Source: https://quarkdown.com/wiki/let.md

Shows `.let` with an implicit positional parameter (`.1`) inside a `.center` block. The lambda uses the implicit parameter to perform successive string transformations. Produces 'QUARKDOWN, quarkdown, Quarkdown' output.

```markdown
.center
    .let {Quarkdown}
        .uppercase {.1}, .lowercase {.1}, .capitalize {.1}
```

--------------------------------

### Compile with --allow permissions

Source: https://quarkdown.com/wiki/cli-compiler.md

Compiles main.qd while granting the network and global-read permissions. The final permission set is computed as defaults + allowed - denied.

```shell
quarkdown c main.qd --allow network --allow global-read
```

--------------------------------

### Handle missing environment variable with optionality function

Source: https://quarkdown.com/wiki/environment.md

Uses `.env {COLOR}` with `::otherwise {teal}` to provide a fallback when the variable is not set. The example shows a container with a teal background.

```markdown
.container background:{.env {COLOR}::otherwise {teal}}
    Hello, world!
```

--------------------------------

### Example 2: Use `.let` with explicit parameter in `.center`

Source: https://quarkdown.com/wiki/let.md

Sets a temporary variable named `name` to the value `Quarkdown`, then uses it in a centered block. The lambda references the variable by its given name `.name` in the subsequent expressions. Renders the result 'QUARKDOWN, quarkdown, Quarkdown'.

```markdown
.center
    .let {Quarkdown}
        name:
        .uppercase {.name}, .lowercase {.name}, .capitalize {.name}
```

--------------------------------

### Combine subdocument name with site name using .ifnot and .htmloptions

Source: https://quarkdown.com/wiki/seo-aeo-optimization.md

Sets the HTML title to 'Subdocument name | My site' for non-root pages. Place in a common setup file like _setup.qd.

```markdown
.ifnot {.docname::equals {My site}}
    .htmloptions title:{.docname | My site}
```

--------------------------------

### Use .foreach with .multiply for arithmetic

Source: https://quarkdown.com/wiki/loops.md

Example 4: Iterates over a range {1..5} and uses .multiply to square each number. The lambda parameter n is used in the multiplication.

```markdown
.row alignment:{spacearound} 
    .foreach {1..5}
        n:
        .multiply {.n} by:{.n}
```

--------------------------------

### Improved but not ideal: row with columns

Source: https://quarkdown.com/wiki/container.md

Example 2 shows using columns inside a row, which works but is not the intended concept. It applies a layout rule instead of resetting the document flow.

```markdown
<!-- Could be improved -->
.row alignment:{center} gap:{1cm}
    .column cross:{start}
        ##! Left
        Text on left column.

    .column cross:{start}
        ##! Right
        Text on right column.
```

--------------------------------

### Create theorem and proof blocks

Source: https://quarkdown.com/wiki/paper-library.md

Use .theorem and .proof to structure mathematical content with an end-of-proof character.

```markdown
.theorem
    .loremipsum

.proof
    .loremipsum
```

--------------------------------

### Iterate over a Markdown list with .foreach

Source: https://quarkdown.com/wiki/loops.md

Example 3: Defines a variable .letters as a Markdown list and iterates over it with .foreach. The iterated elements preserve their type.

```markdown
.var {letters}
  - A
  - B
  - C

.foreach {.letters}
  ###! .1

  The letter is **.1**.
```

--------------------------------

### Block function call example

Source: https://quarkdown.com/wiki/syntax-of-a-function-call.md

Shows a block function call isolated on its own line, surrounded by paragraphs. The call '.myfunction {arg1} {arg2}' is a block-level call.

```markdown
Paragraph 1

.myfunction {arg1} {arg2}

Paragraph 2
```

--------------------------------

### Mermaid with Quarkdown function calls

Source: https://quarkdown.com/wiki/mermaid-diagrams.md

Example 2: Shows how Mermaid code can accept Quarkdown function calls. The .var and .sum functions are used to compute values inside the diagram, and the second block shows the resulting Mermaid code.

```markdown
.var {n1} {2}
.var {n2} {3}

.mermaid
    flowchart TD
        A([Start]) --> B{.n1 + .n2 = ?}
        B -- .sum {.n1} {.n2} --> C([Correct])
```

```mermaid
flowchart TD
    A([Start]) --> B{2 + 3 = ?}
    B -- 5 --> C([Correct])
```

--------------------------------

### Create a definition block

Source: https://quarkdown.com/wiki/paper-library.md

Use the .definition command to create a titled definition block.

```markdown
.definition
    Let $ \Delta x $ be an object's change in position over a time interval $ \Delta t $,
    then the average velocity is defined as $ v = \frac {\Delta x} {\Delta t} $.
```

--------------------------------

### Combine side and pages for scoped formatting

Source: https://quarkdown.com/wiki/page-format.md

Combines `side` and `pages` to target specific sides within a range. This example sets a green border on left pages 1 to 3.

```markdown
.pageformat side:{left} pages:{1..3} bordercolor:{green}
```

--------------------------------

### Bulk include files

Source: https://quarkdown.com/wiki/listing-files.md

Composes .listfiles with .includeall to load multiple files.

```markdown
.listfiles {chapters} sortby:{name}::includeall
```

--------------------------------

### Include multiple files with .includeall

Source: https://quarkdown.com/wiki/quickstart.md

Use .includeall to include a list of files for larger projects.

```markdown
.includeall
    - setup.qd
    - content.qd
```

--------------------------------

### Extending .code primitive with .extend

Source: https://quarkdown.com/wiki/code.md

Shows how to extend the .code primitive to affect all code blocks. The example uses .extend with a where condition to disable line numbers for JavaScript blocks.

```markdown
.extend {code} where:{lang: .lang::equals {javascript}}
    .super linenumbers:{no}

```javascript
function greet(name) {
    return `Hello, ${name}!`;
}
```
```

--------------------------------

### Extending built-in functions like .heading

Source: https://quarkdown.com/wiki/extending-functions.md

Built-in functions such as .heading can be extended. This example adds a background color to headings with depth less than 4, affecting H2 and H3 but not H4.

```markdown
.extend {heading} where:{depth: .depth::islower than:{4}}
    content:
    .super background:{teal}

## H2

## H3

## H4
```

```text
## H2

### H3

#### H4
```

--------------------------------

### Configure Bibliography Style

Source: https://quarkdown.com/wiki/bibliography.md

Example of applying the APA citation style to a bibliography block in Markdown.

```markdown
.bibliography {bibliography.bib} style:{apa}
```

--------------------------------

### Emoji Shortcode Variants

Source: https://quarkdown.com/wiki/emojis.md

Examples of using shortcodes for simple emojis and those with skin tone modifiers.

```text
.emoji {wink}
```

```text
.emoji {waving-hand~medium-dark}
```

```text
.emoji {people-holding-hands~medium-light,medium-dark}
```

--------------------------------

### Tight function call with wrapping braces (Example 8)

Source: https://quarkdown.com/wiki/syntax-of-a-function-call.md

Wrapping the entire function call in curly braces allows it to appear anywhere, even adjacent to word characters. The braces are consumed and do not appear in the output.

```markdown
H{.text {2} script:{sub}}O
```

--------------------------------

### Emulating else with .let

Source: https://quarkdown.com/wiki/conditional-statements.md

Demonstrates how to emulate an else statement by storing a condition in a variable using .let and checking it with .if and .ifnot.

```markdown
.let {.iseven {3}}
    condition:
    .if {.condition}
        3 is even!
    .ifnot {.condition}
        3 is odd!
```

--------------------------------

### Create and iterate a nested collection

Source: https://quarkdown.com/wiki/iterable.md

Example 2: Nested Markdown lists represent nested collections. The .foreach iterates over the outer collection, and .1::first accesses the first element of each inner collection.

```markdown
.var {letters}
    - - A
      - B
    - - C
      - D
    - - E
      - F

.foreach {.letters}
    .1::first
```

--------------------------------

### Example 1: Define scoped variable `area` with `.let`

Source: https://quarkdown.com/wiki/let.md

Defines a temporary variable `area` holding the result of `.multiply {4} {2}`. Within the lambda, the value is referenced via `.area`, and also used in another expression `.divide {.area} by:{2}`. The output is computed and displayed below the code.

```markdown
.let {.multiply {4} {2}}
    area:
    The area of the rectangle is .area.
    If it were a triangle, it would have been .divide {.area} by:{2}.
```

--------------------------------

### Focusing a table of contents entry with focus:{A.B}

Source: https://quarkdown.com/wiki/table-of-contents.md

Adds the focus parameter to highlight a specific entry in the table of contents. In this example, focus:{A.B} highlights the A.B entry, drawing attention to the current section.

```markdown
.tableofcontents maxdepth:{2} focus:{A.B}
```

--------------------------------

### Per-side formatting with mirrored margins

Source: https://quarkdown.com/wiki/page-format.md

Applies different margins to left and right pages for book-style layouts. The first call sets the page size, and subsequent calls override margins for each side. This is Example 3 from the Per-side formatting section.

```markdown
.pageformat size:{A4}
.pageformat side:{left} margin:{2cm 3cm 2cm 1cm}
.pageformat side:{right} margin:{2cm 1cm 2cm 3cm}
```

--------------------------------

### Create a box with a title

Source: https://quarkdown.com/wiki/box.md

Demonstrates the basic syntax for creating a box container with a specified title.

```markdown
.box {Box title}
    Welcome to the **Quarkdown wiki**!
    Here you'll learn how to get started with your first document.
```

--------------------------------

### Bulk include with directory listing

Source: https://quarkdown.com/wiki/including-other-quarkdown-files.md

Combines .includeall with .listfiles to automatically include all files in a directory.

```markdown
.includeall {.listfiles {somedirectory} sortby:{name}}
```

--------------------------------

### Basic .if usage

Source: https://quarkdown.com/wiki/conditional-statements.md

Demonstrates the basic syntax of the .if function, which executes the provided lambda only if the condition is true.

```markdown
.if {yes}
    Hello, Quarkdown!
```

--------------------------------

### Locate SKILL.md for ChatGPT and other agents

Source: https://quarkdown.com/wiki/agent-skill.md

Run this command to output the file path for SKILL.md, which can then be uploaded or pointed to by your agent.

```shell
echo "$(quarkdown doctor get agent-skill)/SKILL.md"
```

--------------------------------

### Configure page format and margins

Source: https://quarkdown.com/wiki/quickstart.md

Set the page size and margins using the .pageformat function.

```markdown
.pageformat {letter} margin:{2cm}
```

--------------------------------

### Function call syntax with positional and named arguments

Source: https://quarkdown.com/wiki/quickstart.md

Demonstrates the basic syntax for function calls using a dot prefix and curly braces for arguments.

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

--------------------------------

### Basic usage of .heading

Source: https://quarkdown.com/wiki/headings.md

Creates a level 2 heading equivalent to standard Markdown ## syntax.

```markdown
.heading {My heading} depth:{2}
```

--------------------------------

### Basic image size syntax with pixel units

Source: https://quarkdown.com/wiki/image-size.md

Loads image.png with label 'Alt' and constrains it to 300px by 100px. The delimiter can be 'x', '*', or a space.

```markdown
!(300x100)[Alt](image.png)

<!-- or -->

!(300*100)[Alt](image.png)

<!-- or -->

!(300 100)[Alt](image.png)
```

--------------------------------

### Create an initially open collapsible block with .collapse open:{yes}

Source: https://quarkdown.com/wiki/collapsible.md

Creates a collapsible block that is initially expanded by passing `open:{yes}`. The `open` argument defaults to `false` (collapsed).

```markdown
.collapse {A _collapsible_ block. **Click me!**} open:{yes}
    Not so hidden content anymore!
```

--------------------------------

### Add an icon to external links

Source: https://quarkdown.com/wiki/quickstart.md

Intercept the .link primitive function to append an icon to links that do not start with the specified URL.

```markdown
.extend {link} where:{url: .url::startswith {https://quarkdown.com}::not}
    content:
    .super
        .content .icon {box-arrow-up-right}
```

--------------------------------

### Retrieve a column with .tablecolumn

Source: https://quarkdown.com/wiki/table-manipulation.md

Extracts the second column as an Iterable and stores it in a variable, then gets the first element. The output is 25.

```markdown
.var {values}
    .tablecolumn {2}
        | Name | Age | City |
        |------|-----|------|
        | John | 25  | NY   |
        | Lisa | 32  | LA   |
        | Mike | 19  | CHI  |

.values::first
```

--------------------------------

### Declare function with parameters and invoke with positional arguments

Source: https://quarkdown.com/wiki/declaring-functions.md

Declares a function 'greet' with two parameters 'to' and 'from'. Invokes it with positional arguments, producing 'Hello, world from John!'.

```markdown
.function {greet}
    to from:
    Hello, .to from .from!

.greet {world} {John}
```

--------------------------------

### Create an abstract block

Source: https://quarkdown.com/wiki/paper-library.md

Use the .abstract command to generate a titled abstract block.

```markdown
.abstract
    This is my *abstract*! Here goes the summary of the document.  
    .loremipsum

This is not part of the abstract, instead.
```

--------------------------------

### Inline TeX equation without paragraph break

Source: https://quarkdown.com/wiki/tex-formulae.md

Example showing that without paragraph interruption the formula is treated as inline, not block.

```markdown
The following function is a **Fourier Transform**:
$ F(u) = \int^{+\infty}_{-\infty} f(x) e^{-i 2\pi x} dx $
```

--------------------------------

### Basic function extension with .extend and .super

Source: https://quarkdown.com/wiki/extending-functions.md

Shows the simplest use of .extend to wrap a function and call the original via .super. The extension applies .super::uppercase to the output, transforming 'Hello, world!' to 'HELLO, WORLD!'.

```markdown
.function {greet}
    name:
    Hello, .name!

.extend {greet}
    .super::uppercase

.greet {world}
```

```text
HELLO, WORLD!
```

--------------------------------

### Invalid manual page break example

Source: https://quarkdown.com/wiki/page-break.md

The <<< pattern does not trigger a page break if it does not interrupt the current block, such as when not preceded by an empty line.

```markdown
Page 1
<<<
Page 2
```

--------------------------------

### Mermaid diagram with empty caption for numbering

Source: https://quarkdown.com/wiki/mermaid-diagrams.md

Example 4: Uses an empty caption string to number the diagram without displaying a caption.

```markdown
.mermaid caption:{}
    flowchart TD
        A([Start]) --> B[Enter username and password]
        B --> C{Correct?}
        C -- Yes --> D[Redirect to dashboard]
        C -- No --> E[Show error message]
        D --> F([End])
        E --> F
```

--------------------------------

### Mermaid diagram with caption

Source: https://quarkdown.com/wiki/mermaid-diagrams.md

Example 3: Adds a caption to the Mermaid diagram using the caption argument, which also enables figure numbering.

```markdown
.mermaid caption:{My Mermaid diagram.}
    flowchart TD
        A([Start]) --> B[Enter username and password]
        B --> C{Correct?}
        C -- Yes --> D[Redirect to dashboard]
        C -- No --> E[Show error message]
        D --> F([End])
        E --> F
```

--------------------------------

### Force Equation Numbering with Underscore ID

Source: https://quarkdown.com/wiki/numbering.md

Example 5 illustrates how to force numbering on equations that lack cross-references by using an underscore as the ID.

```markdown
$ E = mc^2 $ {#_}

$ F = ma $ {#_}
```

--------------------------------

### Set page margin to 4cm

Source: https://quarkdown.com/wiki/page-format.md

Sets the margin area to 4cm on all sides, reducing the content area. This is Example 1 from the Margins section.

```markdown
.pageformat margin:{4cm}
```

--------------------------------

### Create boxes with specific types

Source: https://quarkdown.com/wiki/box.md

Shows how to define the box type using the type:{type} syntax for tip, note, and warning boxes.

```markdown
.box {Box title} type:{tip}
    This is a tip box!

.box {Box title} type:{note}
    This is a note box!

.box {Box title} type:{warning}
    This is a warning box!
```

--------------------------------

### Read environment variable with .env {SHELL}

Source: https://quarkdown.com/wiki/environment.md

Returns the value of the SHELL environment variable, or `none` if not set. Example output shows /bin/bash.

```markdown
This page was compiled with .env {SHELL} as the default shell.
```

--------------------------------

### Clip a figure to a circle

Source: https://quarkdown.com/wiki/clip.md

When clipping a figure, only the content is clipped, leaving the caption intact. The example shows the original figure and the clipped version.

```markdown
![Sky](assets/sky.jpg "A blue sky.")

.clip {circle}
    ![Sky](assets/sky.jpg "A blue sky.")
```

--------------------------------

### Clip an image to a circle

Source: https://quarkdown.com/wiki/clip.md

Use `.clip {circle}` to clip an image to a circular shape. The example shows the original image and the clipped version.

```markdown
![Sky](assets/sky.jpg)

.clip {circle}
    ![Sky](assets/sky.jpg)
```

--------------------------------

### Display an icon using .icon

Source: https://quarkdown.com/wiki/icons.md

Use the .icon function followed by the icon name in curly braces to display an icon.

```markdown
Quarkdown is on .icon {github}
```

--------------------------------

### Live preview sequence diagram (Mermaid)

Source: https://quarkdown.com/wiki/inside-live-preview.md

Shows the interaction between browser, server, and CLI during live preview: the browser requests the live preview wrapper, connects to the WebSocket, and reloads the iframe when the server broadcasts a reload message.

```mermaid
sequenceDiagram
    participant Browser
    participant Server
    participant CLI

    Browser->>Server: GET /live/:file
    Server-->>Browser: Live preview HTML wrapper
    Browser->>Server: WebSocket connect /reload
    CLI->>Server: WebSocket message /reload
    Server->>Browser: WebSocket broadcast /reload
    Browser->>Browser: Reload iframe content
```

--------------------------------

### Create XY Chart from Single CSV Column

Source: https://quarkdown.com/wiki/xy-chart.md

Example 5 demonstrates extracting a single column from a CSV file to plot as a line chart.

```markdown
.xychart
    .tablecolumn {2}
        .csv {assets/sales.csv}
```

```mermaid
xychart-beta
	line [85.0, 100.0, 135.0, 180.0, 240.0, 320.0, 430.0, 580.0, 800.0]
```

--------------------------------

### Sort a table with .tablesort and order:descending

Source: https://quarkdown.com/wiki/table-manipulation.md

Sorts the table by the second column in descending order. The example uses a CSV file as the table source.

```markdown
.tablesort {2} order:{descending}
    .csv {assets/people.csv}
```

--------------------------------

### Lazy lines in .row stack

Source: https://quarkdown.com/wiki/stacks.md

Example 2: A .row stack where A, B, and C are in the same paragraph due to lazy lines, resulting in only one item.

```markdown
.row gap:{1cm}
    A
    B
    C

```

--------------------------------

### Bulk include files

Source: https://quarkdown.com/wiki/including-other-quarkdown-files.md

Uses the .includeall function to include a list of subfiles in a main document.

```markdown
.includeall
    - setup.qd
    - headings.qd
    - paragraphs.qd
    - lists.qd
    - images.qd
    - tables.qd
    - code.qd
    - textformatting.qd
    - colorpreview.qd
    - quotes.qd
    - boxes.qd
    - math.qd
    - footnotes.qd
    - mermaid.qd
    - collapsibles.qd
    - errors.qd
    - keybindings.qd
    - filetrees.qd
    - icons.qd
    - separators.qd
    - alignment.qd
    - stacks.qd
    - crossreferences.qd
    - bibliography.qd
    - localization.qd
```

--------------------------------

### Chaining function calls

Source: https://quarkdown.com/wiki/quickstart.md

Illustrates how to chain multiple function calls using the double colon syntax, where the output of one function becomes the input for the next.

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

--------------------------------

### Conditional styling with ref startswith

Source: https://quarkdown.com/wiki/element-styling.md

Styles math elements whose cross-reference identifier starts with 'einstein' using the `where` parameter and `.ref::startswith {einstein}`.

```markdown
.extend {math} where:{ref: .ref::startswith {einstein}}
    .super foreground:{skyblue} fontsize:{larger}

$ E=mc^2 $ {#einstein-relativity}

$ F=ma $
```

--------------------------------

### Configure multi-language font fallbacks

Source: https://quarkdown.com/wiki/font-configuration.md

Demonstrates using multiple .font calls to set a primary font and a fallback font for different character sets.

```markdown
.font {GoogleFonts:Ma Shan Zheng}
.font {GoogleFonts:Corinthia}
```

--------------------------------

### Create dictionary with .dictionary and iterate with .foreach

Source: https://quarkdown.com/wiki/dictionary.md

Explicitly creates a dictionary using the .dictionary function to avoid ambiguity with iterable syntax, then iterates over it with .foreach, destructuring key-value pairs.

```markdown
.var {mydictionary}
    .dictionary
        - key1: value1
        - key2: value2
        - key3: value3

.foreach {.mydictionary}
    key value:
    **.key**: .value
```

--------------------------------

### List files with full paths

Source: https://quarkdown.com/wiki/listing-files.md

Retrieves absolute paths for all entries in the directory.

```markdown
.listfiles {assets/folder}
```

--------------------------------

### Automatic figure conversion in Markdown

Source: https://quarkdown.com/wiki/figure.md

When a paragraph contains only a single image, Quarkdown automatically converts it into a figure. The example shows an image isolated between two paragraphs of text.

```markdown
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

![Icon](assets/icon.svg)

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

--------------------------------

### Quarkdown .code with focus range

Source: https://quarkdown.com/wiki/code.md

Focuses on a range of lines using the focus argument. The range starts from 1, and line numbers must be enabled for this feature to work.

```markdown
.code focus:{5..8}
    .read {assets/point.ts}
```

```plaintext
export class Point {
    x: number;
    y: number;

    constructor(x: number, y: number) {
        this.x = x;
        this.y = y;
    }
}
```

--------------------------------

### Set base URL with .htmloptions

Source: https://quarkdown.com/wiki/html-options.md

Sets the base URL for the generated website, adding a canonical link and generating sitemap.xml if there is at least one subdocument. Recommended for publishing as a website, especially for docs projects.

```markdown
.htmloptions baseurl:{https://example.com}
```

--------------------------------

### Quarkdown .code with lang argument for TypeScript

Source: https://quarkdown.com/wiki/code.md

Specifies the language for the .code function using the lang argument. The example loads a TypeScript file and displays it with TypeScript syntax highlighting.

```markdown
.code lang:{typescript}
    .read {assets/point.ts}
```

```typescript
export class Point {
    x: number;
    y: number;

    constructor(x: number, y: number) {
        this.x = x;
        this.y = y;
    }
}
```

--------------------------------

### Add icon to external links with content modification

Source: https://quarkdown.com/wiki/element-styling.md

Extends the `link` primitive to add an icon to external links (URLs not starting with https://quarkdown.com) by modifying the content argument.

```markdown
.extend {link} where:{url: .url::startswith {https://quarkdown.com}::not}
    content:
    .super
        .content .icon {box-arrow-up-right}

Check out the [docs](https://quarkdown.com/docs)
and the [repo](https://github.com/iamgio/quarkdown)
```

--------------------------------

### Block HTML injection with .html function

Source: https://quarkdown.com/wiki/html.md

Shows how to use the .html function to inject a block of HTML. The output is unsanitized and not target-agnostic.

```markdown
.html
    <div style="transform: scaleY(0.6);">
        My HTML container
    </div>
```

--------------------------------

### Declare and invoke a simple function

Source: https://quarkdown.com/wiki/declaring-functions.md

Declares a function named 'helloworld' with no parameters and invokes it. The function body is a lambda block; the invocation outputs 'Hello, world!'.

```markdown
.function {helloworld}
    Hello, world!

.helloworld
```

--------------------------------

### Define content.qd

Source: https://quarkdown.com/wiki/quickstart.md

Content file containing the main document body.

```markdown
.tableofcontents

## Quickstart

...
```

--------------------------------

### Create reusable elements with custom functions

Source: https://quarkdown.com/wiki/css.md

Define a custom function that uses .text with a custom class to create reusable styled elements. The example defines a function 'mytext' and then uses it twice.

```markdown
.function {mytext}
    content:
    .text {.content} classname:{my-custom-class}

This is a .mytext {text} and here is .mytext {another}.
```

--------------------------------

### Compile document to PDF

Source: https://quarkdown.com/wiki/quickstart.md

Adds the --pdf flag to the compile command to export the document as a PDF.

```shell
quarkdown c main.qd --pdf
```

--------------------------------

### Compile with process permission

Source: https://quarkdown.com/wiki/environment.md

Command to compile a Quarkdown document with the `process` permission, required for reading environment variables.

```shell
quarkdown c main.qd --allow process
```

--------------------------------

### Tight function call without wrapping braces (Example 7)

Source: https://quarkdown.com/wiki/syntax-of-a-function-call.md

Shows that a function call directly adjacent to a word character is not recognized. The call 'script:{sub}' is not wrapped, so it remains as literal text.

```markdown
H.text {2} script:{sub}O
```