Bland Markdown – Syntax Recommendation

The Need for Bland 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.

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

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.

Some other goodies include http://ift.tt/1j5nrxH and http://ift.tt/1j5nrxH.

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***

Images

![Optional Alt](URL to image)

Note that optionally we suggest the use of embedded Flickr Gallery shortcodes to Flickr images, but that is outside of the scope of Bland Markdown (see Salt and Pepper below).

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.

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:

<mailto:info@parliamentpress>
<http://ift.tt/1fX7kI2;

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

[Parliament Press](http://ift.tt/1j5nrxI)

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 four lines, 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, 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

Using social media images from Flickr is straightforward with the Flickr Gallery plugin on WordPress. (Yes, we know it has not been updated in two plus years, however with only a little core hacking it works fine.) The code used is “ where 1234567890 is the Flickr image ID.

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

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…

via Jeff McNeill http://ift.tt/1fX7kYD

Advertisements

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s