Markdown is the latest fad. After using Asciidoc for 11 years, people have finally figured out what a good idea it is. Unfortunately, (as with version control) they’re taking their cues from GitHub. GitHub seems to have its own flavor of Markdown which has a lot more features than the sad little Perl-based Markdown processor I have naturally available to my Linux system. Even the Python one which I downloaded didn’t do things like tables.

Other reference documentation for Markdown syntax.



Seems legit.

We propose a standard, unambiguous syntax specification for Markdown, along with a suite of comprehensive tests to validate Markdown implementations against this specification. We believe this is necessary, even essential, for the future of Markdown.


When I found out that there was just an unremarkable Perl script to tepidly render Markdown I swear I was extremely close to writing it myself properly, in C. Looks like this person just beat me to it. Bravo!


I haven’t tried these yet.

  • python-markdown - text-to-HTML conversion library/tool.

  • python-html2text - Python module for converting HTML to Markdown text.

If you change s/python/python3/ apparently there are modern versions.

Converting Asciidoc to Markdown

Does this work?

pandoc -f asciidoc -t markdown file2.txt >

HTML to Markdown

The famous Aaron Swartz worked on this with html2tet.

Basic Styling


Starting a line with a number of # creates a heading. So one # is h1. Three ### is h3 and so on up to 6. As a special bonus a line with a same length set of = below it is also h1. And similarly a line with the same length of - below it is h2.

Minor Styling

  • em tags result from surrounding with single * or single _.

  • b tags result from surrounding with double ** or double __.

  • Can **do _both_**.

  • Strike through, which is sadly complicated in Asciidoc, is just surrounded with double ~~.

I do think Markdown links are a bit nicer than Asciidoc. The big complication with Markdown’s links is there are so many different ways to achieve the same effect. There are two major ways links are handled. The first way is a standalone link. The order of the link address target and the anchor text is reversed from Asciidoc.

[Chris' Web Site](

[Chris' Web Site]( "Special Hover Text")

[Nothing wrong with relative links](../index.html)

Sometimes will get magically promoted to a link.
More reliably, <> will sometimes get promoted to a link.
Depending on the link, even things like can get promoted.

The second major way to use links is to create references to them. I think this is a great idea as it allows you to collect all your long and messy URLs at the end of the document out of the way.

Links with references
Here is [anchor text][Section 1 - Link 1] for the first section's
first link. See below for how to make good on that.
Here is [anchor text academics will like][2] which uses numbers.
You can even just put [something in brackets] and use it as a link
reference and anchor text simultaneously.

Putting your links in the text without the real messy URL links requires that you define the real URLs somewhere else. This is how that is done.

Referents of used links
## References
* [Section 1 - Link 1]:
* [2]:
* [something in brackets]:


Like links, images can be specified in a couple of ways. The first is in line. I’m not sure if this can be in the middle of text or if it needs to be on a block alone, but here it is.

![alt text]( "Hover text")

I think in this example, "the link name" is invisible.

![alt text][the link name]

Later in the document...

## Links To Images
[the link name]: "Hover text"

Convert Markdown Images To Asciidoc

This will convert images from Markdown to Asciidoc.



Not nearly as nice as Asciidoc IMO. But here it is.

xs= [n[0] for n in coords]

No syntax highlighting. But roughly similar effect.


Similar to Asciidoc, it seems pretty flexible. It seems for unordered lists you can use *, -, or +. For numbered lists you can use any number followed by a period and it should recount if needed. Stuff like this.

* Unordered item 1.
* Unordered item 2.
  1. This will be numbered as item 1.
  1. This should be numbered as item 2.
  1. This should be numbered as item 3.
  99. This should be numbered as item 4.
* Unordered item 3.
  - sub list unordered item 1.
  - sub list item 2.
    + sub sub list item 1.
    + sub sub list item 2.
* Unordered item 4.


Not top line and no bottom line. Headers are defined by creating a dividing header line. Normal markdown works inside of tables. Like this.

| Column One    | Column Two    | Column Three  |
| ------------- |:-------------:| -------------:|
| left align    | center align  | right align   |
| because       | of the        | colons        |
| *Italic* etc  | **tables**    | still ok      |

Block Quote

Just like email.

> Just isolate it with blank lines and start it
> with some greater than symbols.


Markdown likes horizontal lines, a.k.a. horizontal rules, which is the hr tag in HTML. Just use 3 dashes, asterisks, or underscores on an otherwise blank line and you’ll get the same HR tag.