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.

But hey, it’s better than complete chaos. Markdown is easy and there’s little excuse for anyone to not be comfortable with it, even people who have a similar but better system.

Other reference documentation for Markdown syntax.

Ecosystem

CommonMark

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.

Discount

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!

Python

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 > file1.md

HTML to Markdown

The famous Aaron Swartz worked on this with html2tet.

Basic Styling

Example

Title Can Be Like So
====================

# The H1ish Heading
Here's some stuff in the first section.
## The First Subsection
And here's some more stuff.
There could be [links](http://xed.ch)!
## The Second Subsection
There could be a list.
* Some thing.
* Another thing.
  * It's Additional.
  * It's a thing.
* Yet another thing.
Looks like ordered lists are just using `1.` instead of `*` but that
looks bad.
## The Third Subection
Let's look at images.
![World's largest undocumented computer](http://xed.ch/blog/2019/i/1006-7edb-stonehenge.jpg)

Headings

Output markup Markdown source

H1 Heading - Used for document title.

H1 Title Heading
================

or

# H1 Title Heading

H2 Heading

## H2 Heading

or

H2 Heading
----------

H3 Heading

### H3 Heading

H4 Heading

#### H4 Heading

H5 Heading

##### H5 Heading

H6 Heading

###### H6 Heading

Minor Styling

Output markup Markdown source

emphasized in italic

emphasized in italic

_emphasized in italic_
*emphasized in italic*

emboldened with bold

emboldened with bold

__emboldened with bold__
**emboldened with bold**

Strikethrough is easy in Markdown!

~~Strikethrough~~ is easy in Markdown!

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](https://www.xed.ch)

[Chris' Web Site](https://www.xed.ch "Special Hover Text")

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

Sometimes http://www.xed.ch will get magically promoted to a link.
More reliably, <http://www.xed.ch> will sometimes get promoted to a link.
Depending on the link, even things like example.com 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]: http://xed.ch/h/markdown
* [2]: http://xed.ch/h/markdown
* [something in brackets]: http://xed.ch/h/markdown

Images

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.

Inline
![alt text](http://xed.ch/b/2016/i/1204-4353-carcrash2.jpg "Hover text")

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

Reference-style
![alt text][the link name]

Later in the document...

## Links To Images
[the link name]: http://xed.ch/b/2016/i/1204-4353-carcrash2.jpg "Hover text"

Convert Markdown Images To Asciidoc

This will convert images from Markdown to Asciidoc.

s@!\[\(.*\)]\[\(.*\)]@image:\2[\1]@

Code

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

```python
xs= [n[0] for n in coords]
print(xs)
```

```
No syntax highlighting. But roughly similar effect.
```

Lists

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.

Tables

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.

HR

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.