Bland Markdown

The Need for Bland Markdown

Markdown

There are various flavors of markdown (see also whatismarkdown.com), including original markdown, as well as Github Flavored, Reddit flavored, StackOverflow flavored, SourceForge flavored, Tumblr markdown (possibly PHP Markdown Extra), PHP Markdown Extra, MultiMarkdown, and Pandoc flavored. This is not to mention supersets such as Maruku and Kramdown.

Non-Implementation Syntax Recommendation

So, due to this proliferation, we introduce a non-implementation recommendation. The need for this is felt most by editors and writers (and publishers), for whom implementation details are not important, but a single style guide syntax to follow is a necessity. In order for one's Markdown code to be as portable as possible, a single subset that is most widely used is seen as the best approach for an organization as well as individuals who produce and edit Markdown markup now and in the future. Hence, Bland Markdown aka Markdown bland aka Mb.

Bland Markdown

Bland Markdown Syntax Rationale

The main features animating the decision regarding the particular syntax of Bland Markdown is to define a set of syntax that is easy to use and edit. This means that in some cases where there are several options for particular Markdown markup, a single markup is chosen for memorability and ease of use, along with the widest Markdown flavor implementation support. We use a modified icon based on the Markdown icon, with the down arrow replaced with a lower case b for bland.

Note that a recommended bland syntax is preferable over testing tools such as Babelmark 2 (which doesn't fully work properly as the PHP Markdown is not parsing, as of this posting). (See also the PHP Markdown dingus for markdown reformatting.)

Note also that Jeff Atwood tried to do a call for large site users of Markdown to get together and create a standard, which unfortunately has not gotten much mileage, another reason for a bland syntax.

Update: this actually did get takeup and became CommonMark. And there are still yet reasons for a non-implementation syntax recommendation, along the lines of a Markdown Style Guide.

Bland Markdown Syntax

License: Bland Markdown is released under a Creative Commons Attribution license.

Headers

Hash/Pound sign is used to denote H1, H2, etc., as in:

# Header
## Subhead

Ordered and Unordered Lists

Ordered lists are numbered lists, and unordered lists are bulleted lists. Bulleted lists are to be created using the minus sign.

- We suggest the minus sign, as it is easier to type than a plus sign
- And will not be confused with the asterisks used for bold and italics

Whereas ordered lists have actual numbers and periods in them (though in fact ordered lists ignore the actual number and create a new numbered order starting at 1).

1. The first item
2. The second item

Bold and Italics (aka Strong and Emphasis)

*Italics*
**Bold**
***Bolded Italics***

Notes: For a while I was using underscores (_italics_, __bold__, and ___bold italics___) but I ran across some incompatibilities in some markdown implementations. At the time I was also using * as bullets, but prefer to use a character to mean only one thing in the Bland syntax recommendation (either bullets, or italics/bold, but not both). If you can support both formats, then that would be the most compatible and portable in terms of markdown marked up content.

For more about _ vs * for em/strong See: Commonmark discussion. Note that it is useful to go back to the typewriter, which had only two options:

  • Underscore was used for emphasis, which has now become italics in printed material (and on the web is replaced by html markup or a typeface), though some typographic philistines still use underscore.
  • ALL CAPS was used for STRONG, which still exists but is largely replaced by bold strong (which is now, as with italics/emphasis, in html markup or a typeface).

Bland Markdown is a syntax recommendation that tries for compatibility and portability of content across systems, which is why we want to use asterisks for both italics and bold, as it behaves more consistently, and has the merits of providing a better visual indicator in untransformed text (along with a hyphen used for unordered list items).

Images

![Alt text](URL to image)

optionally include a title

![Alt text](URL to image "Optional Title")

Note also that we do not recommend any kind of Figure markup, as this is not straightforward and can best be handled manually (in a separate paragraph, say with manually numbered and italicized text) or with external scripts.

  • Thanks to Andy Van Den Heuvel of Shuttle for pointing out that Alt Text is required in HTML.

Another great feature of Markdown Extra is the ability to add classes and IDs, such as:

![Alt text](URL to image "Optional Title"){.img-right}

This would add class="img-right" which in the css style could image float right.

Note, if you wanted to have an image link to a different image, the syntax can follow this image style guide:

[![](/images/mcneill/2016/future-of-the-desktop/intel-compute-stick-t.jpg "Intel Compute Stick"){.img-right}] (/images/mcneill/2016/future-of-the-desktop/intel-compute-stick-l.jpg "Intel Compute Stick")

(Note the code here has been artificially truncated for legibility, the four lines above are a single line.)

URLs

URLs are either plain (where the link text is nearly identical to the URL) or with custom link text. In the case of plain URLs, simply enclose in angle brackets (less than and greater than signs), as such:

``

If URLs have link text, then use the image markup, minus the exclamation mark, as such:

[Jeff Mcneill](https://mcneill.io)

Jeff Mcneill

Code Blocks

Paragraph-level code blocks simply have four spaces to begin each line, whereas inline code is marked up with backticks, as in:

This is marked up `code`

Escaping backticks is performed by using double backticks to enclose the code block and inside single backticks will be exposed as literals.

Fenced Code Blocks

Fenced code blocks come in many flavors: Github, PHP Markdown Extra, Pandoc (a superset) and MultiMarkdown just adopted the Github style of fenced code blocks (following Github). Four spaces or three backticks and a newline provide Github style, as well as some syntax highlighting by naming the code being fenced. PHP Markdown Extra uses three tildes, and also supports class naming (as does Pandoc).

Line Breaks

Handily, line breaks can be instituted by typing two spaces at the end of a line. For visuals, simply add a single hard return after the two spaces, and not two hard returns as normally to institute a paragraph break.

Note: This alone (the use of two spaces to create a <br />) should be a caution to people who have the unfortunate two spaces after each period habit.

Horizontal Rule

Five asterisks separated by two hard returns above and below is the most compatible format, as such:

*****

Quoted Text

Taken from email correspondence, quoted text simply has a greater-than symbol > and a space for each line, as such:

> Quoted text

Tables

Tables are trouble for several reasons. While Markdown is an improvement over basic HTML, tables are difficult to edit in terms of viewing the data. Also, not all Markdown flavors support Markdown inside of the tables, and there is also a variety of formatting that would need to be done in raw HTML. Finally, there are many viewers, i.e., early ebook readers, which do not deal with tables well if at all. Therefore, most tables are best rendered as images and then used and shared as such. That said, sometimes an HTML table is something to have. Therefore we suggest the following syntax:

Right | Left | Default | Center -----:|:-----|---------|:-----: 12 | 12 | 12 | 12 123 | 123 | 123 | 123 1 | 1 | 1 | 1

Renders as follows:

Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1

Bland Markdown Extended (aka Spicy Markdown)

There are two kinds of extensions to Bland Markdown, one for the web, and another for print/epub (sometimes for both). In the future, this may be dispensed with, but each has some requirements that can both be met. A full implementation of Spicy Markdown (SM) will be developed in 2014.

Superscript and Subscript

MultiMarkdown recently adopted a similar syntax for superscript and subscript to that of Pandoc. For syntax, use carets or tildes, as in:

x^2 or x^2^ y~z or y~z~

The single delimiter terminates at first whitespace or punctuation. Dual delimiter allows for punctuation to be scripted, but not white space.

Footnotes

Footnotes are supported similarly (though not identically) in PHP Markdown Extra, MultiMarkdown and Pandoc. The markdown consists of a named footnote marker (rendered as a superscripted number), and the footnote itself.

[^footnote-name]

[^footnote-name]: Footnote text

Math Formulas

We recommend the use of LaTeX (XeLaTeX) and for the web some kind of plugin to parse the native LaTeX markup, such as Enable LaTeX or LaTeX for WordPress.

Document metadata

This part is left to be done, including Pandoc, MultiMarkdown and LaTeX document metadata styles.

CriticMarkup

As more applications integrate CriticMarkup this somewhat unwieldy markup, it can be used (or perhaps a more streamlined version).

Image Markup

A part of the syntax recommendation should also be image naming and location, but that is more along the lines of a Common URL Structure.

Another key factor of image markup has to do with captioning as well as figure numbering. This can be done in CSS (for x/html/ebook implementations) as well as LaTeX, but there should be something that works well in Markdown. Unfortunately, the MMD syntax doesn't work for Pandoc, or something is screwy. I've got to work this out further. See a fork of the Php Markdown extra...

Better would be to also include layout information such float:left;margins 0 10px 0 0. People make a big deal about partitioning this information, but that becomes harder to maintaim. When one is inserting an image, they are thinking about layout and presentation, which is why having that facility is important.

Video Markup

There is a handy Smart YouTube plugin which allows for appending a v at the end of http of a YouTube video url, and will embed it (along with HTML5 support). Other video sources are also supported. In addition, there are many controls for default site-wide YouTube video settings in the plugin.

A better approach would be simply embedding a YouTube video URL within something like [ embed ] . . . [ /embed ]

Embedded Slideshows

Slideshare slideshows can be embedded in WordPress with a plugin. That supports the embedding of the Slideshare share code for wordpress.com but better is the use of open-source slideshows and/or documents (especially open standards). Wikipedia and other wiki projects have struggled with this with alternative viewers/players and such, but if we focus on syntax there should be some kind of embedding or playing that could have a markdown-like syntax (perhaps in the future).

Note also that I've yet to work out Markdown markup for slideshows that could then be converted into X/HTML/ePub/PDF slideshows and then uploaded to Slideshare (to be embedded as such). There are various syntax options out there for this, such as found in Pandoc. TBD...

Markdown Postings on mcneill.io

Previous Postings on Markdown Editors

Powered by WordPress. Designed by WooThemes