This is currently a work in progress, but I have a 0.1.0 release of a “One Ring To Rule Them All” Markdown processor published.

The goal of Apex is to make it possible to write in any Markdown processor’s syntax, be it Kramdown (with IALs), MultiMarkdown (with v6 extensions), CommonMark (with GFM extensions), or any syntax that uses parts of those processors. Apex defaults to a unified mode that combines the features of all of these, automatically adjusting to the syntax it finds.

Where CommonMark is strict, Apex aims to be very permissive. While I advocate for clean, clear Markdown, you shouldn’t have to worry whether the Markdown you wrote for GitHub is going to work on your blog, or whether syntax you used in Marked is going to work when you export from the command line.

Speaking of Marked, yes, the ultimate goal of Apex is to have a Markdown processor option in Marked that’s essentially universal. It will default to Apex and the user won’t have to question why their Markdown from Obsidian isn’t working in Marked, and I won’t have to explain the differences between the processors anymore. Apex has a ways to go before it’s stable enough for production integration like that, but it’s already not far off. But I’m also open sourcing it, so please feel free to contribute (any code contributors will be named in Marked’s credits when it’s integrated). Even if that just means filing Issues, any help making this bulletproof is appreciated.

I’ll do a separate announcement of the Marked 3 public beta soon, but you can join now if you head over to markedapp.com.

I’ve set up a GitHub repo, and a pretty complete wiki for the project. It details installation, usage, syntax, and more.

Some of the special features include:

  • Use ^ to break consecutive lists
  • Use Marked, MultiMarkdown, or iA Writer syntax to include external files
    • automatically detects images, source code, and Markdown files and inserts the correct formatting
    • if a CSV file is included, it’s converted to a table
  • Marked and Leanpub pagebreak syntax, which can be styled to create page breaks in print and PDF
  • Advanced table syntax, allowing for rowspans and footers!
  • Relaxed table mode allowing any consecutive lines with an even number of piped cells to create a headless table, no alignment row required
  • Callout syntax from Bear/Obsidian and Xcode playgrounds works and generates basic markup you can style as needed (the --standalone mode can automatically include a basic stylesheet for these)
  • Table of Contents with min/max depth, using MMD or Marked syntax
  • configurable header id generation
    • No IDs
    • GFM style with dashes
    • MMD style with spaces compressed
  • GitHub style link anchors instead of header IDs
  • 350+ GitHub emojis recognized and rendered
  • Wiki linking

Plus: the IALs from Kramdown, which is a feature I use all the time. It allows you to add {: .callout} after an element to add a class="callout" to the block or span. It can add an id, multiple classes, and random attributes.

More to come, but I think it’s ready to put out there for testing and feedback. I haven’t fully tested every possible syntax yet, and there will definitely be bugs, so please report via GitHub issues and help me get it to 1.0.

You can install with Homebrew if you don’t want to build it yourself:

brew tap ttscoff/thelab
brew install ttscoff/thelab/apex

Check out the wiki for more details. I’ll be adding a project page for this soon, but it will mirror what’s in the GitHub README and link to the wiki for details anyway.