Books and slides from Markdown: Quarkdown 2.0 is here
The Markdown dialect Quarkdown 2.0.0 has been released, offering more security, better offline usability, and higher speed.
(Image: heise medien)
The Markdown dialect Quarkdown has been released in version 2.0.0. The update focuses on a new permission system that restricts document access during compilation and an HTML output that works completely offline. It also includes parallel rendering, new HTML options for canonical links and a sitemap.xml, as well as a public/ directory for static assets. Several breaking changes also affect the default output directory, the name of the output directory for --preview, and a renamed module in the standard library.
Quarkdown extends the markup language with a Turing-complete function language. Unlike classic Markdown, the open-source project allows variables, functions, and control structures directly in the document. It aims for HTML and PDF outputs for books, technical texts, knowledge bases, and presentations. Those familiar with Markdown can best imagine Quarkdown as Markdown with a built-in scripting and layout layer.
Permission system as a sandbox
The most important innovation is the permission system. It defines what a document is allowed to access during compilation. If the compiler attempts an action without the appropriate permission, it aborts with an error. Users set permissions and prohibitions via --allow and --deny; options include project-read, global-read, network, native-content, and all. The feature primarily acts as a sandbox: because Quarkdown documents can do much more than plain Markdown thanks to their function language, it provides better security for executing third-party documents.
The revised HTML output is also central. Quarkdown now ships fonts, code highlighting themes, and optional libraries with the installation and copies them into the generated documents instead of loading them from CDNs or Google Fonts. This makes the output fully functional offline. According to the release notes, this also ensures more predictable rendering and faster page loads. Only Chinese fonts for .doclang {zh} and explicitly selected Google Fonts remain remote. The trade-off is larger output directories and a slightly slower initial run; subsequent compilations are not slowed down by checksum checks, according to the project.
For HTML projects, Quarkdown also introduces the new .htmloptions function. With baseurl set, it generates canonical links in the <head> of each page and writes a sitemap.xml with absolute URLs for main and sub-documents. This brings Quarkdown closer to typical static site generators without users having to add such SEO metadata retrospectively.
Static Assets and New Functions
The new public/ directory in the project root directory is also practical for web outputs. Its content – such as robots.txt, CNAME, or other static files – is copied unchanged to the output root directory. Additionally, Quarkdown now understands the root path symbol @ for HTML export: a reference like @/assets/logo.png points to the output root and is therefore suitable for assets shared by multiple sub-documents. The concept is reminiscent of the public/ folders in common web frameworks.
Also new is the primitive function .image, which makes images more finely configurable, including an opt-out from media storage via mediastorage:{no}. Quarkdown now renders cross-references via .ref as links for all referenceable types – not just headings, but also figures, tables, code blocks, equations, and custom numbered blocks. This significantly improves navigation consistency in longer technical documents.
Among the smaller but useful convenience features are multi-line function calls using a backslash at the end of the line and the new .keybinding function for keyboard shortcuts. The latter displays shortcuts as stylized key labels and accounts for platform differences, for example, using ⌘ instead of Ctrl on macOS. This is practical for areas such as documentation, knowledge bases, and UI-related content.
Videos by heise
More Speed and Bug Fixes
Under the hood, Quarkdown 2.0 now renders sibling elements in parallel, which is intended to speed up large documents. The project has also revised the input and output of Media Storage: Quarkdown now copies files by reference instead of by content, supplemented by checksums that prevent unnecessary copies.
Existing setups need to prepare for some incompatibilities. The default output directory is now ./quarkdown-output instead of ./output. For --preview without --out-name, Quarkdown will now assign static names in the pattern preview-<mainfile>-<hash>, instead of orienting itself on .docname. Additionally, there is a renaming in the standard library: the previous module Injection is now called Html; existing references to the module's documentation and its functions must therefore be adjusted.
License and Installation
All information about Quarkdown 2.0.0 can be found in the release notes on GitHub. The project is open source: Quarkdown and its modules are under GNU GPLv3 by default; GNU AGPLv3 applies to the modules and binary packages of quarkdown-cli and quarkdown-lsp. The software can be installed via an installation script on Linux, macOS, and Windows, or via Homebrew or Scoop; alternatively, the project points to a quarkdown.zip from the current stable release or a build via gradlew installDist.
(fo)
