Kibble.js
A Bite-Size SPA Website Generator
Mar 1 2015

Intro to Markdown

Forget HTML. Markdown all the things!

•Markdown what?

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!

•The Basics

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.

Many tools exist to convert Markdown into actual HTML. Kibble.js relies on the kramed NPM module, as well as highlight.js to format code snippets.

So, how does one write Markdown?

Paragraphs

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

For an <hr> rule to separate paragraphs, just add a three or more dashes ---, asterisks ***, or underscores ___

***

Font Styles

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***

Headers

There are two ways to specify header titles in Markdown:

# Creates an <h1> heading #  

## Creates an <h2> heading ##

#### Creates an <h4> heading

Closing # chars are optional.

Another way to specify headers in Markdown is:

Creates an <h1> heading
=======================

Creates an <h2> heading
-------------

Any number of - or = chars will do..

h3 Headers in Kibble.js

In Kibble, <h3> headers have a special meaning — they generate major article "sections", such as this one.

### Headers

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. • or -.

### •Headers

Numbered or not, the bullets can be clicked to toggle-collapse a given section.

Block Quotes

To create an offset blockquote, hard-wrap a section of text, pre-pending each line with the > character:

> 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

Lists

Use *, +, or - 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'..

Tables

You can even generate HTML tables like so:

| What          | From          | Cost          |
| ------------- |:-------------:| -------------:|
| left aligned  | centered      | right aligned |
| Rivets        | USA           | $10           |
| Bolts         | China         | $1            |
What From Cost
left aligned centered right aligned
Rivets USA $10
Bolts China $1

Inline HTML

Markdown allows for HTML snippets to be mixed right in! The only rules are:

  • Block-level tags, e.g. <div>, <table>, <p>, <pre>, must be separated from other content by blank line(s)
  • HTML blocks cannot be indetend in
  • Inline-level elements can be used anywhere, and support Markdown syntax within them!
  • HTML is not supported by Bitbucket Readme files
<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

Example:

My preferred search provider is [Google] [1] rather than [Yahoo] [2].

[1]: http://google.com/     "Google"
[2]: 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>

Images

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

Alt Text

Code Spans, Blocks

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 <code> tags.

For a block-level code block, indent one or more lines by at least one tab. Markdown will wrap this block using both <pre> and <code> tags.

Additionally, Kibble.js integrates highlight.js for syntax highlighting.

Avoiding Formatting Conflicts

If you do not want a specific character interpreted by Markdown, you can "escape" it by prepending a \ backslash:

\*literal asterisks\*

In addition, there are two special-case characters, < and &, which may need to be escaped for HTML, via &lt; and &amp;, respectively.

AT&amp;T

Learn More

This should have you writing Markdown like a pro, but there is certainly a bit more to learn. To dive deeper, see: