Why not just use Google Docs, Microsoft Word, Open Office or some other word processor?

A number of reasons:

  1. Compatibility
  2. Stability
  3. Sustainability
  4. Versioning

The short answer is for all the same reasons that software developers have been using it for the last decade. It is extremely rare to find any software documentation written in anything but Markdown these days. Most software development teams would literally laugh in your face if you asked them to document their work in a word processor of any kind.

šŸ’¬ There are ancient institutions and enterprises that still have ridiculous Word templates for everything but agile companies that are dominating the industry are way beyond those outdated and unsustainable practices.


Despite what many would have you believe these tools are not compatible with one another. The document format underneath what you see is wildly complicated, unnecessarily.


With all that bloated unnecessary stuff comes a high-degree of risk that stuff just won't work as expected. That you will get weird formatting conditions and bugs and spend all your time learning how to keep your word processor from crashing.


BaseML is the closest thing to digital paper that there is. It is 100% CommonMark, the closest thing to a web content documentation standard the world has ever known. It is universal and supported by every major text and word processor there is. You never have to worry about your content being held hostage by the eventually outdated applications you created it with. This is particularly important for educational content and the reason BaseML is the core language for all SOIL module knowledge source.


Keeping your knowledge source in this most basic form allows it to benefit from all the same approaches and tools that software source code does including versioning. There is no need to lock into a specific word processor's way of implementing some substitute for version management that resemblesā€”even copiesā€”the real thing used for the world's leading software source repositoriesā€”primarily Git. For example, you can review the entire change history of this content using the world's leading source management service GitHub. But here's the amazing part, anyone with a copy of that repository has all that same history as well in an internationally recognized format and open standard for source management. You will never get that with a word processor.

Why not use Ogg format for sound and video?

Because you no longer need it. No one does. The MP3 licensing officially ended on April 23, 2017.

BaseML is hard to read with just a plain text editor.

First of all, that is not a question. šŸ˜

You have to remember the priority of BaseML is not source readability, it is primarily convenience in writing and efficient parsing.

If your priority is readability of the plain text source perhaps stick with CommonMark or Pandoc.

Why not just use CommonMark?

BaseML is CommonMark, just a simplified subset of it.

CommonMark is great for larger documentation projects, as is Pandoc, but BaseML is designedā€”above allā€”to be compatible with services such as Medium.

A BaseML rendered document can be cut and paste without alteration directly into the Medium (and other) editors. CommonMark cannot.

The CommonMark team is aware of these limitations to the historical Markdown implementation and written up a great summary of the challenges which BaseML addresses directly by simply removing the complicated options entirely.

Can't I just use http instead of putting < and > around it?

No. Although most renderers will detect URLS by looking for http:// or https:// many do not since it was never a part of the original standard. Instead, put less-than (<) and greater-than (>) around any link.

Does BaseML impose any particular writing style?

No. But we recommend the SOIL style standard which prioritizes screen rendering.

Why did you exclude ...?

Nothing else from any markup claiming to be Markdown compatible is allowed. Specifically this means the following are not allowed in BaseML. Usually you can use many of these with other versions, just not BaseML.

Custom Containers

::: some

While these are very useful when creating Vuepress documentation they're not specifically needed nor standard. Use an initial contextual emoji with a normal blockquote instead:

šŸ’¬ Like this.

Use of Underscore for Formatting

Not only is this incredibly ugly and slightly harder to type. It is simply redundant and unnecessary.


This extension to Markdown is unnecessary and problematic when considering content that might be voiced. Essentially the same could be written out as the following:

I hate, um, I mean *strongly dislike* ..

Some argue that errata in a document justify it, but in every case an italicized update and explanation are always better.

Unordered Lists

Anything but * is unnecessary and redundant.

Ordered Lists

Not only is anything but 1. unnecessary and redundant but it stops renderers from using another language with a different numbering system. Think of 1. as a token and not a number.

This particular point in Markdown implementations is all over the map. Some allow using different numbering systems by changing the 1, others use the initial number to indicate what to start on and then the next one is the amount to increment by, still others do not respect different numbers forcing their own counting.

The simplest solution to all of this is to force it to 1. and just know that counting will begin at whatever the number one is in the target language.

Nested Lists

More than one study has shown that nested lists are too dense for most reasonable reading unless it is in a table of contents specifically. Medium agrees.

One level of nesting also makes text-to-speech seem more natural.

Nested Blockquotes

Nested blockquotes might have occurred in 1990s emails and newsgroups but they are no longer useful. Why would we want to encourage cutting and pasting from deeply nested email threads anyway? A better approach is to isolate any specific quotable content of value and put that into a single blockquote.

Indented Blocks

Fences and hard breaks cover ever use case for this and do so without the ambiguity of using the number of spaces.


Tables have dubious value both in HTML and Markdown. They are unresponsive, take longer to render than div in HTML, and are usually far too dense to provide meaningful content to the reader. This is why Medium does not support them.

Instead, if such a graphic is required put it into an image instead, which is equally easy to maintain and provides consistent appearance.

Footnote style link syntax provides a more pleasant reading experience when looking at plain text Markdown source, but it comes at a huge cost in cognitive overhead and efficiency when writing documents because one always has to look to the bottom of the document to check the link.

Also, when that content is cut and paste into another document the footnoted links must be also copied and pasted removing the ease of modularity if the link is place inline instead.

Inline links are far easier to parse programmatically because the parenthesis signals caching of the link URL until the ending parenthesis is scanned. Footnoted links require complicated approaches that wait until the entire document is parsed before the links can be activated. As the length of BaseML documents might be very long, this delays rendering unnecessarily.

Remotely Sourced Images

At worst, remotely sourcing an image is illegal, at best, an unnecessary dependency on an Internet connection and usage of bandwidth. If an image is needed it is always better to make a copy (appropriately) and include it locally. If you absolutely need an external link to an image, perhaps because it is dynamically generated, then link to it instead without adding it as a linked image. This has the added benefit of tagging the external link visually in renderers such as VuePress.

Remote images are commonly used on GitHub and other services to display the current status of the project or content. This creates an unnecessary dependency on the Internet which is trumped by the priority of creating offline-first content.

Images other than PNG, GIF, JPG

Raster Only

These raster image formats are widely supported and provide the least complication to both inclusion and rendering. For example, Medium does not support anything but JPEG, PNG, and GIF. A simple screenshot can be added without a problem.

SVG images are not included because of the added complexity required for renderers to parse and render them. When an SVG is needed include it locally with a link in the text.

Horizontal Rules Other Than Four Dashes

Redundant and unnecessary.

Typographer shortcuts: (c)

Use either the text standard or an standard emoji directly.

Inserted text

Unnecessary and never part of the original.

Marked Text

Unnecessary and never part of the original.

Emoji Escapes

Defunct now that editors can directly insert the emoji.

Emoticon Shortcuts

Defunct now that editors can directly insert the emoji.

Sub and Superscript

Unnecessary extension and not part of original Markdown. Use a UNICODE character instead.


Unnecessary and never part of the original.

Definition lists

Unnecessary and never part of the original.


Unnecessary and never part of the original.

Preformatting with 4+ Spaces

While this looks better in plain text form, whitespace is never a good thing to codify in a language. Use a fence instead.

Backslash Escapes

The minimal nature of BaseML means that backslash escapes are simply not needed.


No BaseML construct has indentation. All must be at the start of a line. When indented content is needed use a fence.

Line Returns

No line returns are allowed in any BaseML construct except fences and blocks including formatting and paragraphs.

The http is universally recognized as beginning a link. No need to force them to be wrapped in <>. Email addresses, telephone and other future types do need them however.

Although no one uses them much in practice. Links in CommonMark are allowed to have a space and a title. BaseML does not allow this.

Latex, KaTeX, MathML

The biggest reason not to use Latex and friends for anything is that it cannot be easily spoken by voice synthesis standards. It is always better to use raster images of the equations instead. The equation can be written out in natural language in the alt text of the image and be better uttered by conversational user interfaces.

There are several converters out there.

While these are amazing innovations in the publishing world they have never been included in any particular Markdown standard and are therefore incompatible extensions. If you absolutely must have them consider using Pandoc instead.

Front Matter

Strictly speaking front matter is not excluded, just discouraged. It is always better to put front matter data in another file when possible,

  • Maintains separation of concerns;
  • Allows syntax checkers to work;
  • Avoid decentralizing important data.
Last Updated: 11/6/2018, 4:32:13 PM