Specification

BaseML is a simplification of CommonMark inspired by Medium and Discord designed above all for maximum Markdown compatibility and ease of writing and parsing.

Version

BaseML uses semantic versioning to track the specification.

Version v0.17.0

This means the first initial version is still planned but the current experimental version is reasonably reliable at this point.

Jan 2019 is the projected deadline for v1 which will include a formal ABNF, reference parser implementations in JavaScript and Go, and Visual Studio Code extension.

ABNF

To come.

UNICODE

  • UTF-8 encoded
  • emojis and such written directly

Lines

  • always at the start of a line
  • nothing indented unless within fence
  • blank lines collapsed into single blank line
  • soft-wrapping, no hard line breaks

Spaces

  • spaces collapsed into single space

Headings

# Heading Level One

## Heading Level Two

### Heading Level Three

#### Heading Level Four

##### Heading Level Five

###### Heading Level Six
  • only ATX
  • no formatting

Formatting

*one star for italics.*

**two stars for bold.**

***three stars for bold italics.***

`backticks for preformatted code.`
  • never mixed
  • no strike-through
<https://baseml.soilsrc.org>

<foo@bar.example.com>

<tel:555-555-5555>

[text](link/)

[text](./link/)

[text](/link/)

[external](https://link/...)
  • anywhere in a paragraph or blocks
  • text only, never images
  • always use < and > for autodetected links
  • never depend on sensing http
  • only use inline-friendly []() version of links (no footnotes)
  • linked text under 20 characters

Slugs

## A 😁 Smiley Section Header

... back in the [smiley](#a-😁-smiley-section-header) section ...

  • local links header slugs can be assumed
  • international slug standard
  • not ASCII specific

💬 Here is the JavaScript source of the algorithm to be captured in a way that does not employ regular expressions later.

const removeDiacritics = require('diacritics').remove
// eslint-disable-next-line no-control-regex
const rControl = /[\u0000-\u001f]/g
const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'<>,.?/]+/g

module.exports = function slugify (str) {
  return removeDiacritics(str)
    // Remove control characters
    .replace(rControl, '')
    // Replace special characters
    .replace(rSpecial, '-')
    // Remove continous separators
    .replace(/\-{2,}/g, '-')
    // Remove prefixing and trailing separators
    .replace(/^\-+|\-+$/g, '')
    // ensure it doesn't start with a number (#121)
    .replace(/^(\d)/, '_$1')
    // lowercase
    .toLowerCase()
}

Images

![alt](/assets/image.png)

![alt](image.gif)

![alt](./image.jpg)
  • only raster images supported
  • suffixes required .jpg, .png, .gif
  • linkable like text
  • landscape preferred
  • large: 1366x768px (when detail needed)
  • preferred: 683x384px
  • animated GIF allowed
  • 12mb per image maximum size
  • images must be in their own paragraph
  • local links might need ./
  • local images preferred
  • no parentheses allowed in image path

AI files: large, preferred

Video

Watch [this video](./linked.mp4).
  • no form of Markdown has ever supported video
  • if embedded with HTML will be ignored
  • link from frame image instead
  • same syntax as images
  • only MP4 supported
  • suffix required: .mp4
  • large: 1366x768px (when detail needed)
  • preferred: 683x384px
  • local preferred for offline-first
  • secondary to written content

Audio

Listen to [this](./linked.mp3) when you can.
  • no form of Markdown has ever supported audio
  • same syntax as images
  • only MP3 supported
  • suffix required: .mp3
  • local preferred for offline-first
  • secondary to written content

Fences

```js
console.log('code block')
```
~~~md
Also a code block since sometimes you need ```
~~~
  • only three back ticks or tildes
  • any language identifier allowed
  • use no language identifier for simple preformatting
  • better than custom containers because compliant

Blocks

> Something someone said.
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent leo massa, pretium et dui et, blandit tempus risus. Fusce lacinia non magna quis pharetra.
> 
> Etiam fringilla purus non eros volutpat, sed pharetra ante imperdiet. Quisque tincidunt magna vitae ullamcorper ornare. Donec ut neque eu velit condimentum consequat. Nulla facilisi.
> 💬 A block with context based on the emoji.
  • soft-wrapping like paragraphs
  • blank indicates new block paragraph
  • add an initial contextual emoji when needed
  • better than non-compliant custom components

Paragraphs

Preferred:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent leo massa, pretium et dui et, blandit tempus risus. Fusce lacinia non magna quis pharetra. 

![Images Have Own Paragraph](./some.png)

Etiam fringilla purus non eros volutpat, sed pharetra ante imperdiet. Quisque tincidunt magna vitae ullamcorper ornare. Donec ut neque eu velit condimentum consequat. Nulla facilisi. 

Allowed:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent leo massa, 
pretium et dui et, blandit tempus risus. Fusce lacinia non magna quis pharetra. 

![Images Have Own Paragraph](./some.png)

Etiam fringilla purus non eros volutpat, sed pharetra ante imperdiet. Quisque
tincidunt magna vitae ullamcorper ornare. Donec ut neque eu velit condimentum
consequat. Nulla facilisi. 
  • contiguous line preferred (use soft-wrapping to edit)
  • promotes smaller paragraphs
  • hard wraps allowed but discouraged

Quotes

Just use simple "quote" marks. Renderers will convert.
  • simple quotes: ", '
  • smart quotes allowed in render but discouraged
  • rely on renderer to convert

Hard Breaks

PO Box 384  
Davidson, NC, 28036
  • more than two spaces in any text automatically inserts a hard break but does not start a new paragraph

Lists

* unordered
* list
* here
1. item One
1. item Two
1. item Three
  • only * for unordered
  • only 1. for ordered
  • never nested, one level only

Separators

Before the separator.

----

After the separator.
  • only four dashes at start of line with no spaces
  • four instead of three to avoid conflict with front matter
  • must be own paragraph (blank line before and after)
  • separates without specific format inferred
  • call it a separator (not horizontal rule)

HTML/XML

Here is a paragraph but it has a component after it.

<SomeComponent></SomeComponent>

And another paragraph.
  • allowed but ignored
  • all content within any HTML tags is passed over
  • enables passing to other handlers such as VuePress
  • does not include elements which include a colon

Front Matter

---

some: thing

---
---toml

some = thing

---
  • allowed but ignored
  • always three dashes
  • optional format/language tag
  • generally discouraged when separate file possible
Last Updated: 11/6/2018, 4:32:13 PM