Markdown is a simple text syntax for writing documents for the Web. It lets you embed text formatting without sacrificing readability of the document. Markdown is very similar to the original Wiki and it's the syntax of choice for ReadMe files on GitHub, BitBucket, many static website generators such as Jekyll, Pelican, and now Kibble.js. Markdown's legibility and simplicity make it awesome!
No special editing software is required — any text editor will do. You just write in plain text and save your files with the
.md extension. If you are new coding, I recommend Atom or SublimeText.
So, how does one write Markdown?
One or more continuous lines of text will be interpreted as paragraphs and wrapped in HTML
<p> tags. To separate your paragraphs, insert one or more blank lines between them.
This is the first paragraph.. This is the second paragraph..
<hr> rule to separate paragraphs, just add a three or more dashes
***, or underscores
To achieve emphasis via
<strong> or to italicize via
<em>, surround desired sections of your text by
* asterisks (no spaces):
*This text is Italic* **This text is Bold** ***This text is Bold-Italic***
There are two ways to specify header titles in Markdown:
# Creates an <h1> heading # ## Creates an <h2> heading ## #### Creates an <h4> heading
# chars are optional.
Another way to specify headers in Markdown is:
Creates an <h1> heading ======================= Creates an <h2> heading -------------
Any number of
= chars will do..
<h3> headers have a special meaning — they generate major article "sections", such as this one.
By default, each Kibble section header within an article gets a large consecutively-numbered "bullet". If you don't want a section to receive a number, prepend the header text with any non-alphanumeric character to be used instead, e.g.
Numbered or not, the bullets can be clicked to toggle-collapse a given section.
To create an offset blockquote, hard-wrap a section of text, pre-pending each line with the
> This is a blockquote, first paragraph. > This is a blockquote, second paragraph. > > This is nested blockquote.
Blockquotes can be formatted within, such as headers and lists:
> ## Title Header > > 1. Item A > 2. Item B
- to achieve unordered (bulleted) lists:
* Item A * Item B * Item C
Use numbers followed by periods for ordered (numbered) lists. The numbers not need be sequential:
1. Item A 2. Item B 3. Item C
Nested lists (periods represent N number of spaces):
* Item A ..* Item Aa 1. Item A ..* Unordered sub-list 2. Item B ..1. Ordered sub-list ...Indent subsequent paragraph by N spaces to match list.. ...Add two trailing spaces for newline (without paragraph break)..
To make the inner items each wrapped in a
<p> tag, separate each item with a blank line.
Just make sure that your lists are not indented in, otherwise you will get a 'code block'..
You can even generate HTML tables like so:
| What | From | Cost | | ------------- |:-------------:| -------------:| | left aligned | centered | right aligned | | Rivets | USA | $10 | | Bolts | China | $1 |
|left aligned||centered||right aligned|
Markdown allows for HTML snippets to be mixed right in! The only rules are:
<pre>, must be separated from other content by blank line(s)
<div> Hello HTML! </div>
Links can be inserted within paragraphs text using the following format:
[External Link](http://example.com) [Relative Link](/about/)
Markdown also supports "reference" links, which allow the URLs to be specified later on in the article, as not to clutter the paragraph itself:
[Ref Link][id] "Optional Attribute Title" [id]: http://example.com
My preferred search provider is [Google]  rather than [Yahoo] . : http://google.com/ "Google" : http://www.yahoo.com/ "Yahoo"
The create "anchor" links within the same article, you can utilize inline HTML:
* [About](#about) <h4 id="about">About</h4>
The syntax for adding images is nearly identical to links, with the addition a leading
! exclamation point:
![Alt Text](/path/to/img.jpg "Optional Title")
Kibble applies the alt attribute text as a photo caption. See Kibble Docs
When writing about programming code, you want a mono-spaced font.
To format a fragment of code within a paragraph sentence, surround the desired word(s) with ` back-ticks ` which will wrap that portion of text in span-level
For a block-level code block, indent one or more lines by at least one tab. Markdown will wrap this block using both
Additionally, Kibble.js integrates highlight.js for syntax highlighting.
If you do not want a specific character interpreted by Markdown, you can "escape" it by prepending a
In addition, there are two special-case characters,
&, which may need to be escaped for HTML, via
This should have you writing Markdown like a pro, but there is certainly a bit more to learn. To dive deeper, see: