Updated 28-Jun-2024
I use Markdown daily. The flavor I use is Markdown Extra. I use this in WordPress websites with a very old (2013) version of the Markdown Extra plugin, which simply continues to work. I also use this in local files that I then turn into epub and pdf files using Pandoc, which supports Markdown Extra (markdown_phpextra).
For files, I use the .md extension and simply write in Markdown. I don't generally have to look at display code, except when working with complex tables. The open preview option in VSCode works well in this case. VSCode uses Markdown-IT implementation, which has nice extentions that make it pretty much like Markdown Extra, and better. For example the markdown-its-attrs and markdown-is-footnote mostly completes the Markdown Extra syntax I regularly use. There are also additions such as markdown-its-table-of-contents which makes it easy to create a wiki-like [[TOC]] table of contents.
There are additional ways to extend Markdown, such as supporting embedded media, such as for WordPress using the shortcodes to easily drop in YouTube videos and the like.
For VSCode and markdown-its extensions there are things like Markdown+Math which embeds KaTeX for math rendering, and Markdodwn Extended that includes a number of popular extensions in a bundle. There is also things like the Graphviz Markdown Preview extension.
Another option is to run Pandoc as the Markdown parser for preview, and there are extensions that enable that. In fact Pandoc might be a great global processor suitable for desktop and server implementations. Be that as it may, a multitude of implementations that can be tweaked to provide good enough markup support is really all that is needed, and is quite accessible.
Preface
Markdown, a sleepy little implementation and thousands of related projects has finally metastasized into several projects/collections aimed to provide better guidance. Basically it is growing up, Gruber be damned. As such, editing (and storing) markdown text is important as well. Commonmark and reference implementations such as Pandoc and Markdown-IT, with extensions, pretty much cover the version 2.0 of Markdown and offer guidance and support.
BELOW NEEDS TO BE DRASTICALLY REORGANIZED/CUT SO THAT ONLY THE IMPORTANT SYNTAX IS LEFT
What to Know - Markdown and Editors
Below are more resources, but in simple terms, markdown (now wrested out of Gruber's grasp), however it may be called or named, is the means by which we edit text that will be displayed in books and on the web and mobile devices. Yes, there are helpers and complementors, and TeX/LaTeX/XeLaTeX does not go away (but becomes more important).
So, all writing should be in this format, get rid of the WYSIWYG, stop using Google Docs, get everything into plaintext with simple markup. True, there are problems with spreadsheets as they don't markup easily/well, but we'll deal with that later. Editors should be open source, period. Yes, we can use cloud services, but all data in the cloud should be (with minor exceptions such as configuration) downloadable and editable offline (and of course portable, that is in plaintext). Github issues is a great example:
So, we go with the Atom editor. If that makes us a Github fanboy, so be it.
Markdown Initiatives
- Markua a superset being developed by Leanpub
- CommonMark a better Markdown (less buggy, modern implementations, and clarified specification)
- Pandoc a tool that supports the more common/important implementations
- StackEdit
- Github Flavored, including the updated spec, aka commonmark
- PHP Markdown Extra
- MultiMarkdown
Retarded Markdown
Markdown qua Markdown has been retarded since birth (or slightly thereafter). In that sense it is kind of a dwarf or a little person. That is, it can do some things, but not the kind of workload required of the fully grown. People make a big deal out of Markdown not being broken, and it certainly isn't, when taken at face value and measured at the level of a dwarf. But we need more grown up and developed markup in the modern world, and all the grafted-on appendages will not due. Hence the proliferation of Markdown extensions. People call these flavors, and they are certainly enhancements to make Markdown taste better (or really, become more functional). But this grafting on of limbs always has the feeling of personal modifications and the result a beauty contest between Frankenstein monsters.
Recent Developments in Markdown
Interestingly, there are two significant developments in Markdown, a more-fully-specified Markdown syntax called Common Markdown and an IETF/APPSAWG Markdown media type draft. Both represented long-needed steps forward, Gruber be damned. CommonMark has both C and Javascript implementations of Markdown as well.
These changes are significant in that, text/markdown can be recognized as a media type, that is a label for content, such as that transported via HTTP/HTTPS.
So better, let's start with a plan, not to operate on the small historical body of markdown, but to see it as a single species in a world of evolution, and to learn better and more from its better adapted cousins. Namely: TeX/LaTeX/XeLaTeX, HTML, and ePub (a form of HTML). For this is where we have come.
- Example of simple need to extend markdown but with the incessant rejoinders that extending it makes it not markdown
Markup for Publishers = MarkPub
What we have are several standards that we use, as well as specific needs (publishing, though that could be considered to be quite broad). And so, we can produce a markup which can be used in these cases (and possibly others).
There are several limitations of retarded markdown vis-a-vis html which make for an easy target, specifically the use of CSS classes.
Math Issues
MathJax (see StackEditor implementation) vs. MathML vs. other such...
Commenting
Some text1. Final bit of text for the paragraph.
Some more text, another paragraph here.
![This is the figure caption][fig_id]
[fig_id]: http://mmd.png "This is where the title goes" height=45px width=120px
To strike-through text:
This is is a test.
This is {--is --}a test.
This is is a test.
To add text:
This a test.
This {++is ++}a test.
This is a test.
to change text:
This isn't a test.
This {~~isn't~>is~~} a test.
This is a test.
to add comments:
This is a test {<>}
This is a test.
Bland Markdown
As noted, 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 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
> 
optionally include a 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:
> {.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:
> [{.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:
> ``
> Hence,
If URLs have link text, then use the image markup, minus the exclamation mark, as such:
> [Jeff Mcneill](https://jeffmcneill.com)
> Hence, 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]
> Hence, [^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...
Spicy Markdown
Spicy Markdown is a significant departure from Bland Markdown as well as many/most other Markdown implementations. Most such implementations try and limit themselves to the spirit of original markdown in terms of parsimony, and extend it only in terms of some additional incremental (but important) extensions. Pandoc tries to do a bit more.
Note: This post is under occasional update.
Difference in Spicy Markdown from other Markdown
- Spicy Markdown is different because it is an attempt not so much to extend Markdown but to create a superset of website tools. It might be better called - Spicy Shortcode instead of Spicy Markdown but indeed Markdown is the core markup.
- Spicy Markdown aims to produce a static html page that is fast, and includes ways of optimizing images for effective display.
- Spicy Markdown also supports various other kinds of features of Wordress (such as ``), image and video codes, slideshows/image sliders, and includes css enhancements (such as image alignment).
- Essentially, Spicy Markdown is meant to be the best tool for plain-text editing of web pages, as elegant and parsimonious as possible, but with full ability to do basic page composition (layout).
- Spicy Markdown is meant to work with SquidCache, and therefore will provide pre-fetched queries and include as little as possible realtime database access.
New Functionality of Spicy Markdown
- Images will include captions and figure numbering, as well as dimensions and alignment support.
- YouTube videos will be supported
- Footnotes and endnotes will be supported
- Alternative fonts will be supported (specifically useful in the case of different fonts for different languages).
- Image sliders will be supported (which will have JS/CSS elements)
Some Python Implementations
-
Here is the text of the footnote. ↩︎