Development build

Full Changelog: https://github.com/iamgio/quarkdown/commits/latest

v1.15.1

Changed

Subdocument link to nonexistent file now produces a visual error

A subdocument link pointing to a nonexistent file now produces a clear visual error in the output document, rather than silently rendering [???].

Reduced code block font size on small screens

Code blocks in plain and docs documents now use a smaller font size when viewed on small screens, improving readability on mobile devices.

Plain documents are start-aligned on small screens

Text alignment in plain documents switches from justified to start-aligned on small screens.

Reduced caption font size on small screens

Captions for figures and tables in plain and docs documents now use a smaller font size on small screens.

Upgraded to Reveal.js 6

Upgraded Reveal.js, the library powering slides documents, to v6.0.0.
No breaking changes are expected in the rendered output.

Fixed

Split paragraphs in paged documents now justify the last line correctly

When a paragraph is auto-split across a page break in a paged document, the last line of the first part is now correctly justified, rather than start-aligned.

Thanks @OverSamu!

Fixed live preview not updating when an anchor is present

Fixed an issue that caused live preview to skip updates when navigating to an anchor link of the same document, e.g. from the navigation sidebar.

Thanks @OverSamu!

Fixed .filetree's 'ellipsis' text color

Ellipsis (...) items in file trees now display the correct color.

Thanks @cyphercodes!

Fixed captions not following global line spacing

Captions now follow the global configuration for line spacing and letter spacing.

Fixed Quarkdoc Wiki page broken links if they contain anchors

The @wiki documentation tag now correctly preserves # anchor separators in wiki URLs.

---

Sponsors

Thanks to our sponsors! 🎉

@vitto4

v1.15.0

Added

 

CSL bibliography styles (breaking change)

Quarkdown's internal bibliography management is now powered by CSL (Citation Style Language).

• A curated selection of citation styles from the CSL Style Repository is now supported. The style parameter now accepts a CSL style identifier (e.g. ieee, apa, chicago-author-date, nature). The default style is now ieee.

  Breaking change: plain and ieeetr styles do not exist anymore, and have been replaced by ieee.

• Along with BibTeX (.bib) files, the following file formats are now accepted:

  • CSL JSON (.json)
  • YAML (.yaml/.yml)
  • EndNote (.enl)
  • RIS (.ris)

• Rendered bibliography entries are now localized to the document locale, set via .doclang.

 

Multi-key citations

.cite now accepts a comma-separated list of keys (e.g. .cite {einstein, hawking}) to produce a single combined citation label, whose format depends on the active citation style (e.g. [1], [2] for IEEE, (Einstein, 1905; Hawking, 1988) for APA).

 

Formatted captions

Captions for all supported elements now accept inline formatting (including inline function calls), rather than plain text.

![Pi](pi.png "The symbol of *pi*, which approximately equals .pi")

 

Scoped page formatting

.pageformat now supports scoping formats to specific pages in paged documents via two combinable parameters:

• side (left or right): restricts formatting to recto or verso pages, enabling mirrored margins and other asymmetric layouts.
• pages (e.g. 2..5): restricts formatting to an inclusive range of page indices.

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

.pageformat pages:{1..3} borderbottom:{4px}

 

New syntax: Tight function calls

Inline function calls can now be wrapped in curly braces to delimit them from surrounding content, without relying on whitespace.

abc{.uppercase {def}}ghi

 

.heading primitive function

The new .heading function creates headings with granular control over their behavior, unlike standard Markdown headings (#, ##, ...).
It allows explicit control over numbering (numbered), table of contents indexing (indexed), page breaks (breakpage), depth, and reference ID (ref).

 

.pagebreak primitive function

The new .pagebreak function provides an explicit way to insert a page break as an alternative to the <<< syntax.

 

File tree

The new .filetree function renders a visual file tree from a Markdown list.

.filetree
    - src
      - main.ts
      - ...
    - README.md

Bold entries (**name**) are highlighted with a distinct background color, useful for drawing attention to specific items.

.filetree
    - src
      - **main.ts**
      - utils.ts
    - README.md

 

Better heading configuration for table of contents and bibliography

Both .tableofcontents and .bibliography now accept the following optional parameters to control the heading that precedes them:

• breakpage: controls whether the heading triggers an automatic page break.
• headingdepth: the depth of the heading (1-6).
• numberheading: controls whether the heading is numbered in the document hierarchy.
• indexheading: when enabled, the heading is included in the document's own table of contents.

 

Subscript and superscript text

The .text function now accepts a script parameter with sub and sup values for subscript and superscript text.

 

Changed

 

Removed includeunnumbered parameter from .tableofcontents (breaking change)

The includeunnumbered parameter has been removed, in favor of the more granular heading configuration previously mentioned.
Now all indexable headings are included in the ToC by default, regardless of their numbering.

 

.container's margin now suppresses children's margins

When an explicit margin is applied to a .container, it now suppresses the margins of its direct children, for a more intuitive and flexible layout configuration.

 

.fullspan now relies on .container

.fullspan, used to create a block spanning over multiple columns in a multi-column layout, is now shorthand for .container fullspan:{yes}.

 

Fixed

 

Stabilized multi-column layout

The multi-column layout via .pageformat columns:{N} is no longer experimental, and now works reliably across all document types.

 

Added call stack limit

Infinite recursion in function calls is now detected and reported as a clear error.

 

Fixed default browser not opening on Linux (Wayland and XDG environments)

On Linux systems where the Java AWT Desktop API does not support the BROWSE action (e.g., Wayland), --browser default now falls back to xdg-open automatically.
Additionally, --browser xdg is now a supported named choice for the --browser CLI option.

Thanks @szy1840!

 

Fixed scroll position not fully restored during live preview on long paged documents

When editing long paged documents with live preview, the scroll position could sometimes be restored only partially because of long paged.js load times. The swap now reliably waits for the content to be fully loaded.

 

Fixed Mermaid diagrams preventing page breaks

Fixed an issue that caused Mermaid diagrams in paged documents to cause subsequent content to overflow instead of being pushed to the next page.

 

Fixed tree traversal not reaching non-body nodes

Fixed an issue that caused tree traversal-dependent features, such as cross-references, to not work in titles of .box and .collapse, and in block quote attributions.

 

Improved lexer performance

The lexer has been optimized to reduce regex builds to a minimum, resulting in significantly improved performance for large documents.

---

Sponsors

Thanks to our sponsors! 🎉

@vitto4

v1.14.1

Added

Escaped characters in numbering formats

A backslash (\) in a numbering format string now escapes the next character, treating it as a fixed symbol. For example, \1 produces a literal 1 instead of a decimal counter.

Fixed

Fixed live preview sometimes timing out on Windows

Fixed an IPv6-related issue that caused connections to Quarkdown's server to time out on Windows. Please also update to the latest version of the VS Code extension to v1.1.2 or later.

Fixed block function call incorrectly matching lines with trailing content

Fixed an issue that caused a line like .sum {1} {2} .sum {3} {4} to be incorrectly lexed as two block function calls rather than a single paragraph with two inline function calls.

Changed

Improved lexer performance

The lexer no longer restarts its regex search from scratch when a function call advances the scan position, resulting in slightly improved performance, especially for documents with many function calls.

---

Sponsors

Shout out to our sponsors! 🎉

@vitto4

v1.14.0

This version is the biggest release to date, with a large number of new features and improvements, and a new official wiki, written in Quarkdown, that fully replaces the GitHub wiki for a better experience.

Going forward, next minor releases will be smaller and more frequent.

Thank you for using Quarkdown!

Added

docs document type

docs is the fourth document type available in Quarkdown, alongside plain, paged and slides. It is designed for technical documentation, wikis and knowledge bases.

It derives from plain, and adds a customizable navigation sidebar, a ToC sidebar, a header, accurate client-side search, and next/previous page navigation buttons.

You can see it in action in the new official wiki! To get started with a new docs document, you can rely on quarkdown create as usual.

 

New themes: Galactic (color) and Hyperlegible (layout)

Inspired by Astro, this new theme combination is the one used in the new wiki for improved readability and modern look.

 

GitHub-style alerts

GitHub's alert syntax is now supported, making it easier to migrate from other tools:

> [!NOTE]
> This is a note

Note that Quarkdown's original syntax is still supported and recommended, especially for English documents:

> Note: This is a note

 

Subdocument links now allow anchors

Links to Quarkdown subdocuments now support anchors, to link to specific sections:

[Page](page.qd#section)

 

Customizable page numbering format

The .formatpagenumber {format} function overrides the page numbering format from the current page onward. It accepts the same format specifiers as .numbering, and applies to both page counters and table of contents.

.pagemargin {topcenter}
    .currentpage

# First page

.formatpagenumber {i}

# Second page

# Third page

Thanks @OverSamu!

 

Horizontal/vertical gap customization of .grid

The .grid function now accepts hgap and vgap parameters to customize the horizontal and vertical gaps between grid items. gap still works as a shorthand for both.

Thanks @OverSamu!

 

none is now converted to null

When invoking a native function from the stdlib, none is now supported by nullable parameters, and converted to null.

Before:

.function {rectangle}
    width height background?:
    .if {.background::isnone}
        .container width:{.width} height:{.height}
    .ifnot {.background::isnone}
        .container width:{.width} height:{.height} background:{.background}

After:

.function {rectangle}
    width height background?:
    .container width:{.width} height:{.height} background:{.background}

 

Icons

The new .icon {name} function relies on Bootstrap Icons to display pixel-perfect icons in your documents.

Quarkdown is on .icon {github}

 

New output target: plain text

Quarkdown can now render to plain text (.txt) via --render plaintext.

This has no particular use case. It was needed to implement the docs search feature in the first place.

 

Get path to root directory

The new .pathtoroot {granularity?} function returns the relative path from the current source file to the parent directory of:

• the root document, if granularity is project (default)
• the subdocument, if granularity is subdocument

 

Changed

.css doesn't require !important anymore

The .css function now applies !important automatically at the end of each rule.

 

Revised navigation sidebar

The navigation sidebar, visible in plain and paged documents on web view, is now easier to navigate, with all entries visible at once, and more accessible for screen readers.

Additionally, its generation is now performed at compile time rather than runtime, providing major performance improvements for large documents.

 

Flexible naming strategy for subdocument output files

--no-subdoc-collisions was removed in favor of --subdoc-naming <strategy>, which is a flexible way to choose how subdocument output files are named:

• file-name (default): each subdocument output file is named after its source file
• document-name: each subdocument output file is named after its .docname value
• collision-proof: former --no-subdoc-collisions

 

Revamped create CLI

The quarkdown create command is now more intuitive, for a smoother onboarding experience.

 

Libraries now include content

.include {library} now also includes top-level Markdown content from the library, just like .include {file.qd} does for regular files.

 

Page content border adjustments

Page content border (.pageformat bordercolor) is now supported in plain documents, and refined for slides documents, especially in PDF output.

 

Improved code diff styling

Code blocks using the diff language now have improved and clearer styling for added and removed lines.

 

Fixed

Major improvements to live preview

Live preview has undergone major performance improvements and increased reliability, especially in combination with the new VS Code extension update.

Live reloading not being performed when editing subdocuments has also been fixed.

 

Fixed subdocument resolution from included files

Linking to subdocuments from files included via .include from a different directory now correctly resolves the subdocument path.

 

Fixed unresolved reference of local variables in body arguments

The following snippet used to cause an unresolved reference error for y:

.function {a}
    x:
    .x

.function {b}
    y:
    .a
        .y

.b {hello}

 

Fixed paragraph spacing with floating element

Fixed an issue that caused no spacing to be present between two paragraphs if a floating element was in-between, via .float.

 

Fixed ToC with no level 1 headings

Table of contents are no longer empty if no level 1 headings are present, or if all are decorative.

 

Fixed line spacing in table cells

Table cells now correctly apply the same line spacing as paragraphs and lists.

---

Sponsors

Shout out to our sponsors! 🎉

@vitto4

@serkonda7

v1.13.0

🎄 This release focuses on Quarkdown as a reliable static site generator. The HTML output is now ready to be deployed straight out of the compiler, with enhanced SEO, polished responsiveness, and better support for multi-page (subdocuments) projects.

Check out iamgio.eu, my new personal website, for an example of a website fully powered by Quarkdown, with even a blog!

The sources are available here, and its deployment on GitHub Pages uses the brand-new Quarkdown GitHub Action.

Main features and changes

Enhanced metadata

Quarkdown now takes better care of HTML metadata for an improved SEO, to let your websites rank higher in search engines.

Additionally, new metadata functions are introduced: .docdescription and .dockeywords.

.docname {Quarkdown}
.docdescription {A Markdown-based typesetting system}

.dockeywords
  - markdown
  - typesetting
  - papers

 

Improved viewport for plain documents

Plain documents are now more beautifully responsive than ever, for portable websites.

• On small (mobile) screens, the navigation sidebar is hidden, spacing is refined, font size is slightly increased, and footnotes appear at the bottom.
• On very large screens, the maximum width of the content area is capped to improve readability.

 

Scoped page margins

When used in paged and slides documents, the .pagemargin function now takes effect only from the page where it's declared onward. This allows for different page margin settings in different parts of the document.

If you used to call the function at the start of the document to set global margins, this behavior is unchanged.

.pagemargin {topcenter}
    On all pages

# First page

# Second page

.pagemargin {topleft}
    From second page

# Third page

Thanks @sanoakr!

 

Page number resets

The new .resetpagenumber {from?} function allows overwriting the current page number at any point in a paged or slides document.

These changes are reflected in .currentpage and page numbers in the table of contents.

.pagemargin {topcenter}
  .currentpage

# First page

# Second page

.resetpagenumber from:{20}

# Third page

Thanks @sanoakr!

 

Page numbers in slides' table of contents

Along with paged documents, table of contents in slides documents now also shows page numbers for each entry.

 

List files in a directory

The new .listfiles function returns a collection of the files in a directory on the file system. It's unordered by default, or can be sorted by name or date.

The output can be iterated upon, or supplied to other functions. For example, it's possible to perform automatic bulk inclusions:

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

 

Subdocument function

A new .subdocument {path} {label?} function has been added as a more flexible alternative to the [Label](path.qd) syntax to register subdocuments to the knowledge graph and link to them.

As opposed to the static link syntax, the function accepts dynamic paths. Thus, it's possible to use .listfiles to automatically link all documents in a directory.
Great for blogs!

.foreach {.listfiles {somedirectory}}
    path:
    .path::subdocument label:{.path::filename extension:{no}}

The example also shows the new .filename {path} function, which allows retrieving a file name from its path.

 

Control over .include's sandbox

The main difference between inclusion and subdocuments is how the included document is sandboxed:
by default, .include lets all changes propagate to the parent document, while subdocuments isolate them.

Now, .include accepts an optional sandbox parameter to control this behavior. In ascending order of isolation:

• share (default): all changes propagate to the parent document.
• scope: like share, but function and variable declarations do not propagate.
• subdocument: changes, including metadata and layout options, do not propagate.

 

Rich content in CSV

mode:{markdown} can now be used in .csv to parse cell content as inline Quarkdown source code. This allows for formatting, rich content, and even function calls inside CSV.

 

Alphanumeric sorting

String sorting operations performed in the stdlib now prefer alphanumeric comparisons. This applies to .tablesort and .listfiles.

• Before: abc120 < abc30
• Now: abc120 > abc30

This is more natural and correct. .tablesort can now be used for real-world leaderboards!

 

Changed text replacement for em-dashes

Up to now, a dash (-) surrounded by spaces was replaced by an em-dash (—). Now, it produces an en-dash (–) instead.

To get an em-dash, use two dashes (--), not necessarily surrounded by spaces.

 

Sidebar now ignores decorative headings

Decorative headings (#! Title) are now ignored in the navigation sidebar.

 

Document modifications in a subdocument do not affect the parent document

When importing a subdocument, modifications to document metadata, layout, or other properties no longer propagate to the parent document.

This allows, for instance, to call .docname in a subdocument to set its own title, which will be shown in the browser tab when viewing that subdocument.
Unset properties will still fall back to the parent document's values.

 

Working directory now correctly updates on .include

When including documents from different directories via .include, the working directory is now updated accordingly. This allows relative paths to work as expected inside included documents.

Consider the tree:

main.qd
dir/
|  other.qd
|  image.png

From main.qd:

.include {dir/other.qd}

Previously, in order to access image.png from other.qd:

![](dir/image.png)

Now, with the updated working directory:

![](image.png)

 

Changes to subdocument HTML export

When exporting multi-document projects as HTML:

• Subdocuments are now directories rather than HTML files, for better URLs (example.com/subdoc rather than example.com/subdoc.html).
• Each subdocument now has its own media storage (media subdirectory), rather than having a shared one for all subdocuments.

 

What's Changed

• feat(postrenderer): export authors to html metadata by @iamgio in #248
• feat(postrenderer): always set viewport meta by @iamgio in #249
• feat(postrenderer): add document description metadata by @iamgio in #250
• feat(project-creator): add document description by @iamgio in #251
• feat: add .dockeywords metadata function by @iamgio in #252
• feat(project-creator): add keywords metadata by @iamgio in #253
• fix(theme): improve mobile responsiveness of plain doc margins by @iamgio in #255
• feat(stdlib): add .listfiles by @iamgio in #260
• feat(stdlib): add .subdocument by @iamgio in #261
• feat(stdlib): add alphanumeric sorting by @iamgio in #262
• feat!: let .include change the working directory by @iamgio in #266
• fix(parser): trim initial spaces from fenced code block by @iamgio in #274
• feat(stdlib): allow parsing inline Markdown in csv by @iamgio in #277
• feat: let subdocuments edit their own document metadata by @iamgio in #278
• feat!: add en-dash text replacement, change em-dash by @iamgio in #279
• feat: Page number reset support with TOC integration by @sanoakr in #280
• feat: Scoped page margins with reset support by @sanoakr in #281
• feat: change subdocument HTML generation by @iamgio in #282
• feat(stdlib): add sandbox parameter to .include by @iamgio in #283

Full Changelog: v1.12.1...v1.13.0

 

Sponsors

Shout out to our sponsors! 🎉

@vitto4

<a href="https://f...

v1.12.1

This version fixes two issues related to table parsing:

• Escaping the cell separator (\|) now correctly renders | only, even inside inline code.
• || is now parsed as a valid cell.

What's Changed

• fix(parser): fix empty table header || being skipped by @iamgio in #245
• fix(parser): unescape escaped table cell separators by @iamgio in #247

Full Changelog: v1.12.0...v1.12.1

Sponsors

Shout out to our sponsors! 🎉

@vitto4

v1.12.0

Important

If you're using the VS Code extension, please update it to v1.0.4. The preview will fail to launch on previous versions.

Author's message
I, @iamgio, am currently relocating to a new country. I won't be able to dedicate much time to Quarkdown development for the next few weeks, so little patches will be most common.
Thank you for your understanding and support! Active development will resume as soon as I am fully settled.

Main features and changes

This small release comes with some quality-of-life improvements, especially for the CLI.

 

Pipe mode (--pipe)

The HTML output is no longer printed to stdout by default, and it's now replaced by a short message:

• For normal compilation:

  Success @ <output path>
  

• For live preview:

  Success in <elapsed time>
  

A new pipe mode has been introduced, which can be enabled with the --pipe option. In this mode, the HTML output is printed to stdout as before, files are not generated, and all other logs are suppressed.

This mode is useful for piping the output to other commands or files. For example:

quarkdown c input.qd --pipe > output.html

 

Enhanced error reporting

Error boxes now show a snippet of the affected source code.

Runtime errors, such as unresolved files in .read, now show more detailed information.

 

Improved browser selection

The --browser (-b) option of quarkdown c and quarkdown start has been improved to support more flexible browser selection:

• Lookup by name is no longer fixed to a predefined set. You can now specify any browser whose path is present in the environment variable BROWSER_<NAME> (e.g. BROWSER_OPERA for -b opera).
  The previous predefined names are still supported.

• You can now also specify the full path to the browser executable (e.g. -b /usr/bin/firefox).

Note

Browser processes are launched as <path> <url>.
It must be the user's responsibility to ensure the genuinity of the executable.

 

Unnumbered headings in table of contents

The .tableofcontents function now accepts an optional includeunnumbered boolean parameter.

When set to true, decorative headings (#! Heading) are also included in the generated table of contents.

Thanks @sanoakr!

What's Changed

• [dev] chore(deps): bump dependencies by @iamgio in #235
• Add option to include unnumbered sections in table of contents by @sanoakr in #232
• feat(cli): enhance browser selection by @iamgio in #236
• [dev] refactor: make pipeline stages composable by @iamgio in #238
• feat(cli): add --pipe option by @iamgio in #239
• feat: enhance errors by @iamgio in #240

Full Changelog: v1.11.0...v1.12.0

Sponsors

Shout out to our new sponsor: @vitto4 🎉

v1.11.0

Main features and changes

Persistent headings

Used in combination with page margin content, the new .lastheading function allows for persistent headings, such as chapter titles or section names, to be displayed in the page margins of paged and slides documents.

.pagemargin {topcenter}
    *.lastheading depth:{1}*

# Chapter 1

.repeat {10}
    .loremipsum

 

Mirror positions in page margins

The .pagemargin function now accepts new positions:
topoutsidecorner, topoutside, topinsidecorner, topinside, bottomoutsidecorner, bottomoutside, bottominsidecorner, bottominside.

Contrary to fixed positions such as topright or bottomleft, these mirror positions adapt based on whether the page is left or right, great for printing.

.pagemargin {topoutside}
    **This** is a margin content.

The function also no longer has topcenter as the default position.

 

Custom CSS class names

Specific elements can be assigned custom CSS class names by means of the classname parameter, available in .container (for blocks) and .text (for inlines).

.container classname:{my-custom-class}
    This is a block with a custom class.

---

This is an .text {inline text} classname:{my-custom-class} with a custom class.

.css
    .my-custom-class {
      padding: 8px;
      background: linear-gradient(to right, pink 0%, lightblue 100%);
    }

Tip

You can return custom elements from user-defined functions for enhanced reusability and readability!

 

Multiple font configurations

.font calls can now be stacked to create multiple font configurations, which are applied in order. Each configuration acts as a fallback for the next one, in case the current font does not contain glyphs for certain characters.

This is particularly useful for multi-language documents. For example, you may set a primary font for Latin characters and a fallback font for CJK characters:

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

 

Emojis from shortcodes

Emojis can now be inserted using shortcodes via the .emoji function.

Type	Result	Code
Simple shortcode	😉	.emoji {wink}
One skin tone	👋🏾	.emoji {waving-hand~medium-dark}
Two skin tones	🧑🏼‍🤝‍🧑🏾	.emoji {people-holding-hands~medium-light,medium-dark}

For a complete list of supported shortcodes, refer to the Emoji Cheat Sheet.

Fun fact: the cheat sheet was generated with Quarkdown + Hugo!

 

Table generation by rows

The new .tablebyrows function allows for dynamic table generation by rows.

.var {headers}
   - Name
   - Age
   - City

.tablebyrows {.headers}
  - - John
    - 25
    - NY
  - - Lisa
    - 32
    - LA
  - - Mike
    - 19
    - CHI

Name	Age	City
John	25	NY
Lisa	32	LA
Mike	19	CHI

 

.codespan

.codespan {text} can now be used to create inline code spans, similar to backticks (`text`).

Just like .code as an alternative to triple-backtick code blocks, the difference is that .codespan supports function calls, allowing
for dynamic content, whereas backticks do not.

 

Faster frontend and PDF generation

The web frontend underwent a complete rewrite, with performance and maintainability in mind.
The number of synchronous tasks has been reduced, making initial page load faster, with impact on PDF generation time as well.

What's Changed

• [dev] refactor: improve robustness of module management by @iamgio in #214
• refactor/feat: TypeScript frontend migration + persistent headings implementation by @iamgio in #220
• feat: emojis and table generation by rows by @iamgio in #224
• build(deps-dev): bump happy-dom from 20.0.0 to 20.0.2 in /quarkdown-html by @dependabot[bot] in #225
• feat: allow stacking font configurations by @iamgio in #226
• feat: add classname parameter to .container by @iamgio in #227
• feat: add classname parameter to .text by @iamgio in #228
• feat: page margins mirror positions by @iamgio in #230
• [dev] refactor(ts): add page abstraction, simplify page numbers and page margins handlers by @iamgio in #231

Full Changelog: v1.10.0...v1.11.0

Sponsors

Shout out to our new sponsor: @RayOffiah 🎉

v1.10.0

Tip

The new quickstart guide for beginners is available! Check it out in the wiki: Quickstart

Main features and changes

This version brings enhancements in the area of element numbering.

Cross-references

It's now possible to reference sections, figures, tables, equations, code blocks and custom elements across the document.

The Quarkdown logo is shown in .ref {logo}.

![Logo](icon.svg "The Quarkdown icon") {#logo}

 

Code block numbering and captions

Code blocks can now be numbered and captioned.

.numbering
    - code: 1.1

```python "Fibonacci function"
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)
```

 

Numbered equations

Math blocks with a cross-reference ID are now numbered.
If you want to number an equation without referencing it, you can conventionally use _ as the ID.

.numbering
	- equations: (1)

$ f(x) = x^3 $ {#cubic}

$$$ {#_}
f(x) = \begin{cases} 
  x^2, & \text{if } x \ge 0 \\
  -x, & \text{if } x < 0
\end{cases}
$$$

.ref {cubic} is a cubic function.

 

Changed .numbering default behavior [Breaking change]

The .numbering function now merges the new configuration by default.

Consider the following:

.doctype {paged}

.numbering
	- figures: a

# Title

![](img.png "Caption")

The paged document type comes with its own default numbering for most element types.

Prior to this update, setting a new numbering format (e.g. figures: a) would completely reset the current numbering,
leaving headings, tables and other elements unnumbered.

Starting with this update, the current and new configurations are merged, resulting in a for figures, and the original defaults for the rest.

To stick with the original behavior, set merge:{no}.

 

Tables are now always numbered [Breaking change]

In earlier versions, a table is numbered only if it contains a caption, even if empty, as long as an active table numbering format is applied.

From now on, a caption is no longer required: having a table numbering format will be enough to number all tables in the document.

 

Fixed missing trailing symbols in numbering formats

Fixed an issue in .numbering formats that would cause trailing non-counting symbols to be cut off.
For instance, the format (1.1) would wrongly output (1.1.

 

Fixed wrong inline math tokenization

Fixed an issue that would cause multiple inline math expressions on the same line to be wrongly tokenized as a single math block,
if the line started with an inline math expression and ended with another one.

 

Added French localization

French is now supported. Thanks @Pallandos!

 

Changelog

• feat!: let .numbering merge by default. add merge parameter by @iamgio in #202
• feat: add french translations by @Pallandos in #204
• [dev] refactor: make DocumentInfo and sub-properties immutable by @iamgio in #205
• feat: add cross-reference by @iamgio in #208
• feat!: number all tables, no longer require caption by @iamgio in #209
• feat: add captions to code blocks by @iamgio in #210
• feat: add numbering and cross-reference to math blocks by @iamgio in #212
• fix(lexer): fix multiple inline math that could be tokenized as a single block by @iamgio in #213

New Contributors

• @Pallandos made their first contribution in #204

Full Changelog: v1.9.2...v1.10.0

Sponsors

Shout out to our new sponsor: @RayOffiah 🎉