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

Development build

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

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 🎉

v1.9.2

This release brings a hotfix for an issue related to live preview in slides documents.

What's Changed

• fix(live-preview): fix live preview refreshing to the wrong slide in slides documents by @iamgio in #201

Full Changelog: v1.9.1...v1.9.2

Sponsors

v1.9.1

What's Changed

• fix: fix misaligned math formulas in boxes by @iamgio in #195
• fix: fix line numbers and first-line indentation of code blocks spanning across different pages by @iamgio in #196
• fix: allow setting only one dimension (width/height) of the page size by @iamgio in #197
• fix: don't constrain table of contents height in slides PDF by @iamgio in #198

Full Changelog: v1.9.0...v1.9.1

Sponsors

v1.9.0

Main features and changes

VS Code extension & language server

The official Quarkdown extension for VS Code has finally arrived!

Based on the brand-new language server, the extension provides syntax highlighting, user-first completions, in-editor live preview, documentation browsing, diagnostics, and much more.

Install the extension from the marketplace to get started.
This version (1.9.0) or above needs to be installed before the extension is enabled.

 

Live preview optimization

The architecture behind live preview has been redesigned and the experience should now be smoother and more reliable, as you can notice in the previous demo.

For more detailed information about the architecture, check out Inside Quarkdown - How does live preview work?.

 

Added sticky bottom anchor to preview

If the page is scrolled to the very end while in preview, hot reload will let the new scroll position stick to the end of the new document as well.

 

Preview browser selection

The new -b or --browser option for quarkdown c gives control over what browser should be opened when -p or --preview is used.

Accepted values:

• default (default)
• none
• chrome
• chromium
• firefox
• edge (Windows only)

The same option also applies for quarkdown start, with none as a default.
The --open flag was removed (now -b default).

Browser paths are looked up at specific fixed locations by the bootstrap script
and set in BROWSER_<name> environment variables. Overriding them will set the desired path.

 

PDF sandbox is now disabled by default on Linux

Until now, --pdf-no-sandbox was required on most Linux distributions, and not specifying it would cause the PDF export to fail.
Sandbox is now disabled by default on Linux (via the QD_NO_SANDBOX environment variable).

 

Improved stdlib documentation

The quality of stdlib documentation, available at quarkdown.com/docs and within the VS Code extension, has been vastly improved with more details and examples.

 

Fixed 'Input line is too long' error on Windows

Fixed an error that would prevent Quarkdown from launching on Windows if it's loaded from long paths, due to a Windows-specific length constraint.

 

Breaking changes

• (Only for third-party tools) The endpoint for live preview is now localhost:<port>/live instead of the former localhost:<port>, which now serves static resources only.

What's Changed

• feat(build): add Dockerfile by @iamgio in #177
• feat(cli): allow browser launcher selection by @iamgio in #182
• feat: let preview stick to the end of the document by @iamgio in #183
• fix(build): fix 'Input line is too long' startup error on Windows by @iamgio in #178
• fix: escape dot (.) in range parsing by @iamgio in #184
• feat: language server by @iamgio and @FrancescoRocca in #180
• perf!: optimize live preview by @iamgio in #188
• fix(pdf): fix stale page margins in slides PDF by @iamgio in #190
• fix(interaction): fix "NPM executable cannot be found at 'npm'" when .npmrc is present by @iamgio in #191

New Contributors

• @FrancescoRocca made their first contribution in #27

Full Changelog: v1.8.0...v1.9.0

Sponsors

v1.8.0

Main new features

Footnotes

Quarkdown introduces footnotes via three different syntaxes:

•  Some text[^: some note]

•  Some text[^note: some note] and some other text[^note]

• Some text[^note]
  
  [^note: some note]

Subdocuments

Quarkdown becomes closer than ever to a knowledge management tool! Linking to a Quarkdown document will generate a navigable subdocument. And you can even visualize the graph via .subdocumentgraph!

[My subdocument](my-subdoc.qd)

Speaker notes

The .speakernote function can be used to add speaker notes to the speaker view of your Quarkdown slides. Press S to enter speaker view, or export your notes to PDF.

Landscape view

The .landscape function makes it trivial to display some wide landscape content in a portrait page, ideal for printing.

What's Changed

• feat: footnotes by @iamgio in #121
• feat(slides): add speaker notes by @iamgio in #166
• fix(mermaid): fix arrows being hidden by @iamgio in #171
• feat(stdlib): add .br function for line break by @iamgio in #172
• feat: subdocuments & links by @iamgio in #173
• feat: add .landscape function for transposed content by @iamgio in #176

Full Changelog: v1.7.0...v1.8.0

Sponsors

v1.7.0

What's Changed

• fix: fix misaligned formulas in blockquotes by @iamgio in #145
• feat(stdlib): add .css and .cssproperties by @iamgio in #146
• feat: font size configuration by @iamgio in #147
• feat: custom font family configuration by @iamgio in #148
• feat: add text transformation properties to .container by @iamgio in #149
• perf(pdf): launch Puppeteer in shell headless mode by @iamgio in #150
• fix: fix math equations letting content overflow out of their page in paged documents by @iamgio in #151
• fix: fix error thrown when exporting to PDF with output directory not yet created by @iamgio in #152
• fix(mermaid): improve Mermaid diagrams auto-scaling by @iamgio in #154
• fix: center table captions by @iamgio in #156
• feat(bootstrap)!: assume Puppeteer's browser is installed. No longer set PUPPETEER_EXECUTABLE_PATH by @iamgio in #157

Full Changelog: v1.6.3...v1.7.0

Sponsors