I’ve added so much new stuff to my universal Markdown processor, Apex, that it’s hard to count. It’s developing quickly!
In case you missed the announcement, Apex is my latest project — a command line tool and C library that combines the best of various Markdown tools, supporting syntax from CommonMark, GitHub Flavored Markdown, MultiMarkdown, Kramdown, mmark, Pandoc, and even Marked’s own special syntax.
The first and most important change is that I fixed multiple bugs that caused Apex to hang on some files. In all of my testing, it no longer chokes on any file, no matter how complex. And while the rendering speed is slower than plain cmark, it’s far faster than it was previously, and slots into the middle of the pack for efficiency, with about a 70ms render time on a complex document.
I’ve added bibliography and index support. Citations work with multiple types of bibliography files, and Apex handles syntax from both Pandoc and MultiMarkdown. And you can create automatic indices for your documents using mmark or TextIndex format (a cool project by Matt Gemmell with a clever syntax that I like a lot).
Given that bibliography support is the #1 reason Marked users need to use Pandoc as an external processor, building citation support into Apex — as well as Pandoc metadata and other features — means a lot of users won’t need an external processor at all. I’m in no way trying to replace or replicate Pandoc entirely; it’s a brilliant tool with a ton of capabilities that Apex does not aspire to to include. I just want to support the features that make the most sense for a universal Markdown tool.
Almost all command line options can now also be controlled with metadata (YAML or MMD), allowing per-document control of options when operating on batches. It also means you can create a single configuration for Apex and then load it with something like apex --meta-file ~/.config/apex/main_config.yml my_document.md, and all of the options defined in main_config.yml will be applied to my_document.md.
MultiMarkdown allows you to include metadata in a document with [%key] syntax. Apex supports this, and adds on to it by allowing “transforms” — string transforms like [%title:title] or [%source:urlencode], and array transforms like [%tags:split:join(, )]. Transforms also include date parsing and transformation with strftime formatting, e.g. [%date:format(%B)]. This feature allows you to use metadata in a document, or common metadata across multiple files, to control text generation.
I’ve added some cool features to file inclusion, including “addressing”, inspired by mmark’s syntax. This allows you to include only parts of a file, based on line number ranges ({{filename.sh[START,LEN]}}) or regular expression searches ({{filename.md[/^## Introduction/,/^## Conclusion/]}}). You can also prefix every line of an included file ({{quotes.md[139,15;prefix:> ]}}).
I don’t have any specific next steps planned as far as feature additions — I want to see if I can get enough people to start using it that I get feature requests and feedback to guide development. Let me know what you want to see. It’s one of those projects that I start dreaming about around 1am and then end up awake and adding new features to by 3am.
I plan to add Apex to Marked. It will start as an optional “beta” processor, in addition to the built-in MultiMarkdown, Kramdown, CommonMark, and Discount processors, but I’d like to eventually replace all of the processor options with Apex and just allow it to run in different compatibility modes, with the “unified” mode being the default so users don’t even have to think about which processor they need. Marked will just render all syntaxes as expected. And having Apex available as a command line tool that supports relevant parts of Marked’s special syntax will mean users can get results similar to Marked from the command line and other automations.
If you have feature requests or questions about implementation, I’d love to hear about it in a GitHub Issue, or if you’re not a GitHub user, feel free to use the forum. I’m open to any and all feature suggestions, in the interest of making this as universal as possible.
If you want to try Apex out, you can find installation instructions on the Apex project page, and the full documentation in the wiki. Apex can be run as a command line tool (which you can build from source, or just download a pre-built binary for macOS or Linux), and there’s a full C API that can be used in your own projects, including an Xcode framework.
Apex is open source and code contributions are welcome. If you want to contribute money instead, donations are always appreciated.
You can view the full changelog on GitHub.
--wikilinks to enable.--enable-includes to --[no-]includes, allowing --no-includes to disable includes in unified mode and shortening the flag^text) and subscript (~text) syntax support
--[no-]sup-sub command-line option to enable/disable superscript/subscript--[no-]unsafe command-line option to control raw HTML handling<http://...>) to convert them to explicit markdown links, ensuring they work correctly with custom rendering paths.--[no-]autolink CLI option to control automatic linking of URLs and email addresses. Autolinking is enabled by default in GFM, MultiMarkdown, Kramdown, and unified modes.~text~ now renders as <u>text</u> when there’s a closing ~ with no space before it.--obfuscate-emails flag to hex-encode mailto links.--[no-]wikilinks to enable/disable wiki link processing> Term\n> : Definition)> > Term\n> > : Definition)[3,5] includes lines 3 to 5 (exclusive)[3,] includes from line 3 to end of file[/START/,/END/] includes lines between regex matches[3,5;prefix="C: "] prefixes each included line<<[file] syntaxes (not iA Writer /file)[%key:transform] syntax
--[no-]transforms to enable/disable transformsstrftime with date parsing--meta-file flag to load metadata from external files (YAML, MMD, or Pandoc format, auto-detected)--meta KEY=VALUE flag to set metadata from command line (supports multiple flags and comma-separated pairs)command-line > document > file--embed-images flag to embed local images as base64 data URLs in HTML output--base-dir flag to set base directory for resolving relative paths (images, includes, wiki links)--csl CLI option to specify citation style file--no-bibliography CLI option to suppress bibliography output--link-citations CLI option to link citations to bibliography entries--show-tooltips CLI option for citation tooltips<!-- REFERENCES --> marker<!--INDEX--> marker--indices CLI flag to enable index processing--no-indices CLI flag to disable index processingBase Header Level and HTML Header Level metadata to adjust heading levelsCSS to link external stylesheets in standalone HTML documentsHTML Header and HTML Footer metadata to inject custom HTMLLanguage to set HTML lang attribute in standalone documentsQuotes Language metadata to control smart quote styles (French, German, Spanish, etc.) This falls back to Language setting.--css CLI flag as alias for --style with metadata override precedenceAPEX_PROFILE=1) to measure processing time for all extensions and CLI operations
{: markers are present/^: / patterns are found[%title]--mode is specified^ marker now properly separates lists by creating a paragraph break instead of just blank lines^ marker are now removed from final HTML output==text==). Highlight processing now stops at line breaks to prevent interference with header parsing.< or URLs are now skipped during metadata extraction.\(...\) sequences contain actual math content (letters, numbers, or operators) before processing them. This prevents false positives like \(%\) from being treated as math when they only contain special characters.So give it a whirl and keep me posted! Again, feel free to help guide development by opening Issues or joining in on the forum!
Brett is a writer and developer living in Minnesota, USA. You can follow him as ttscoff on GitHub, Mastodon, and elsewhere.
Sign up for the email newsletter, and keep up with this blog by adding it to your favorite news reader, or following it on Bluesky or Mastodon at @brettterpstra.com@web.brid.gy.