This is mostly for me. These are the little things that sometimes confuse me about Markdown and I find myself having to search the web for. So I’ll write them down. Blogging as memory extension.
Know that your mileage may vary on this stuff, as there are many varietals of Markdown.
markdown=”1″
There is no concept of a <div> in Markdown syntax (or most other structural HTML elements), except that Markdown supports HTML so you can just use a <div> if you want to. But as soon as you do, nothing nested inside of it can be Markdown.
### Header
<div class="special-class">
1. Nope
1. Not
1. Happening
</div>Except it can! In many (most?) varietals of Markdown, you can put <div markdown="1"> on the element and it will allow Markdown inside of it.
### Header
<div class="special-class" markdown="1">
1. All
1. Fixed
1. Up
</div>Multiple paragraph lists and blockquotes
If a list item need multiple paragraphs in it, you can’t just break multiple lines and keep going. The next paragraph needs to be indented for it to be considered part of the same list item. Otherwise the list ends and new one starts.
1. one paragraph
more for 1st list item :)
1. another paragraphBlockquotes are similar:
> First bit.
> Second bit.There will be no line break there. Those two bits will be inside the same <p> inside the <blockquote>. To make them multiple paragraphs, you’ll need a blank line in between.
> First bit.
> Second bit.If you wanted them to be entirely separate <blockquote>s, without any other text in between, I’m not sure what’d you do.
Escaping characters
Certain characters have meaning in markdown, like how *asterisks* make text italic. But what if you want to actually display an asterisk? You escape it with a backslash, like \*.
You can even escape the backslash itself, meaning \\ is \.
ID’s
Markdown supports HTML, so if you need any special attributes on elements, you can just use HTML. But it’s nice to not have to.
Different varietals of Markdown handle it in different ways.
A somewhat common way is to allow them on headers like this:
### Custom IDs {#custom-id}Some varietals simply add an ID on all headings for you automatically.
This is also doable client side.
Images
It’s the same as the link syntax [link text](url) except it starts with a bang.
Slightly trickier still is nesting it to be a link:
[](https://css-tricks.com)Languages on Code Fences
The language comes right after the first set of backticks.
```css
body {
background: red;
}
```Tables
You basically draw them like ASCII art. Note the dashes to denote the header row, and the colons for alignment:
| header | header | header |
|--------|:------:|-------:|
| a | b | c |
| 1 | 2 | 3 |
| foo | bar | baz |
I guess I’m not alone
Here’s quite a thread of what other folks forget.
Use an HTML comment:
> blockquote 1<!-- -->
> blockquote 2
turns into
I should also note that there’s been a push for standardization of the markdown syntax which has led to CommonMark. Many of the features you’ve outlined are not included in that standard and are being discussed in various ways as extensions to the core language.
Just to note in more detail:
markdown=”1″
This is not necessary with CommonMark, as an opening/closing tag is valid by itself, it just needs to be closed by an empty line, eg.:
Note the empty lines after the tags, the one before it is just for aesthetic purposes.
Multiple paragraph lists and blockquotes, Escaping characters, Images, Languages on Code Fences works the same.
What’s entirely missing in CommonMark from the above is Tables and ID’s (attributes on markdown blocks).
Ok, html got filtered from the code block and somewhat the code block itself is a mess (it was in fences). :)
Point is, an empty line after the opening tag and an empty line after the closing tag and markdown inside html works in CommonMark.
Hello,
I’ve been wondering how could one make simple dedicated hosting to display markdown, like uploaded file written in markdown to open through the browser and see formatted text?
Cheers!
Daux.io for php docs, grav for php md CMS, php-markdown to Render yourself. Markdown-it and many many more for node js
The simplest answer is that if you just want to see your markdown as formatted text, you don’t need online hosting.
There’s a few options that avoid the need:
Use a markdown editing app
There are a number of different apps that are designed specifically for writing markdown and some text editors have markdown preview plugins too.
Run a local server that renders markdown on the fly
There are almost certainly many options for this, one approach might be to look for a nodejs package that compiled markdown and write a small server that responds with html when you request a markdown file.
Atom has built-in markdown editing/previewing capabilities.
Sublime Text has some plugins to support it.
There are also a large variety of browser plugins to view
.mdfiles.as long as you remember that Github markdown and markdown are completely different beasts
I believe for your question about line breaks in block elements (lists, block quotes, etc), the “official” way is to end the first line with two spaces. Took a while for it to stick, but now I use it all the time.
You had me at
markdown="1"Great set of tips!