BaseML is for writers and writing apps. It contains the simplest parts of CommonMark Markdown making it 100% compatible with everything. This makes it incredibly fast to memorize, easy to write, and requires very little programming to parse. It is inspired by modern writing, social media, and self-publishing services and prioritizes ease of writing and parsing above all. It's ideal for articles, blogging, and conversational user interfaces. In fact, BaseML, rendered or raw, can usually be directly cut and paste into another editor with little or no change.

BaseML is also great when you want to include basic CommonMark support in something without bloating it to include a full CommonMark parsing and rendering engine, for example, when developing anything that does not need a full web pane to render like with Qt or GTK+. This opens up many possibilities for things like

  • light, open reader apps,
  • modern writing standards,
  • an essential web of signed, light-weight content, or even
  • a decentralized knowledge net with no web dependency at all.

For traditional publishing CommonMark and Pandoc are recommended.

One Best Way

BaseML gets out of the way and let's you create. This seems to be the largest motivator for the original Markdown which was created by a writer and podcaster. BaseML is even more opinionated than Markdown, and for good reason. Opinions are decisions made for you that reduce the cognitive overhead required to make them yourself freeing you to focus on your content and message. Since the opinions are based on well-established best practices you need'nt worry.

💬 This constraint is exactly the reason behind the extraordinary success of Medium.

Down, Not Up

Current Markdown parsers such as markdown-it and CommonMark are floating away from the original intent of Markdown. They are going up in complexity, extension, and complication while the original intent of Markdown was to take these things down and away from complicated markup made by academics, scientists, and programmers for academics, scientists, and programmers. BaseML is our response to this problem, a markup for the least tech savvy among us.


Modern web development favors a JAMstack approach to make best use of content delivery networks and offline first design. M is for "Markup" but could equally mean "Markdown" since most web content starts out written in it. Because BaseML is the fastest way to write Markdown it is therefore the quickest way to create JAMstack sites and applications. In fact, with as little as a single README.md file and VuePress you instantly have a progressive web app that is ready for JAMstack deployment.


For now the BaseML specification is informal but ready for an ABNF specification to be submitted to the IETF.

We already have a standard for CommonMark but we need one for a simpler form, one that primarily does not include HTML dependencies.

Transitive Conversion

Perhaps the biggest reason to consider BaseML is the notion of transitive conversion which means going back and forth between rendered and raw BaseML.

Any rendered BaseML, on GitHub for example, can be copied and pasted directly into blogging sites without a problem.

The same is true in reverse. Most blog content document that is cut and paste from rendered HTML can be easily converted to BaseML for use elsewhere.

The applications of this are many. Most importantly this allows the core content to be maintained as a GitHub repository and simply copied by dragging and dropping. This is common when a writer wants to maintain their own content but enjoy the benefits of posting to a specific blogging site or community.


Minimal blogging services with constraints on formatting have successfully demonstrated that readers and writers of all types prefer a consistent, predictable format to allow the focus to be on the content, the writing. The cognitive overhead to learn and process a different presentation unnecessarily distracts writers from their writing. This makes BaseML particularly useful when paired with frameworks like VuePress for documentation and educational content and distribution.

Semantic Macrostructure

Semantic macrostructure is the idea that the structure of the content itself provides meaning and levels of importance. No MIME headers, properties, JSON, hashtags or extra keywords and categories are needed. The content itself provides this.

💬 Semantic macrostructure cannot be gamed by those looking to manipulate an SEO ranking without being completely obvious to anyone ready the content.

Here is how a BaseML document is broken down and ranked in terms of relevance:


  • level one heading
  • short summary (first sentence)


  • long summary (first paragraph)
  • level two heading


  • level three heading
  • image alt text
  • list content


  • paragraphs
  • blocks


  • fenced content
  • link addresses

Links can be easily identified and cataloged as they are parsed as well providing a collection of all outbound links that can be checked for validity or extracted into an index.

This set structure allows creators of BaseML search engines to easily provide users the ability to set their own search priorities without any guess work about how things are ranked.

Last Updated: 9/30/2018, 8:27:24 PM