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

Full Changelog: https://github.com/iamgio/quarkdown/compare/v1.12.1...v1.13.0

Sponsors

Shout out to our sponsors! 🎉

@vitto4