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.
-
Official Markdown - Referenced by Jupyter.
-
GitHub’s Markdown.
-
Programming in C++? Consider using Doxygen for your literate programming needs. It supports quite a lot of Markdown and has a pretty nice reference thereof here.
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.
And they have a nice live tester.
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.mdHTML 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.
Maybe a `filename` or code fragment.
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.
Headings
| Output markup | Markdown source |
|---|---|
H1 Heading - Used for document title. |
or |
H2 Heading |
or |
H3 Heading |
|
H4 Heading |
|
H5 Heading |
|
H6 Heading |
|
Minor Styling
| Output markup | Markdown source |
|---|---|
emphasized in italic emphasized in italic |
|
emboldened with bold emboldened with bold |
|
|
|
Links
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.
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.
## References
* [Section 1 - Link 1]: http://xed.ch/h/markdown
* [2]: http://xed.ch/h/markdown
* [something in brackets]: http://xed.ch/h/markdownImages
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.
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]: 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.