Markdown is used almost anywhere you can enter text on this website for displaying to other visitors. Behind everything from reports, to news posts, to this very Shadow Academy course, is Markdown.
But what is it?
Markdown is a text-based mark-up syntax (like HTML) which is designed to produce formatted web content, while being easily readable in plain text (unlike HTML.)
It was originally developed by [John Gruber], and a lot of information and reference material can be found on his blog, [Daring Fireball].
During this course, I use the terms Markdown (a specific syntax for formatting text) and mark-up (the act of applying a syntax to text). These terms are not interchangeable.
By far the best way to get started with Markdown is to just start typing. In fact, if you have written something, the mark-up is half complete. Some things you might naturally do to emphasize text organically transfer to Markdown syntax. Once you're used to the system, you might find you use it more and more, even in places that don't use it. The good news is that, given Markdown's nature, if you use the syntax elsewhere it won’t look out of place.
If you want to have a go at practising any of the syntax you learn here, in a place that will show you results, I recommend [Dillinger.io's Markdown Editor][MD Editor].
The first thing you need to learn is how to emphasize text (applying italics and bold).
To italicize a word or section of text, place a single asterisk or underscore on either side.
This is *italic* text. _This sentence is also italic._
This is italic text. This sentence is also italic.
Bold is just a little more emphasis than italics, and as such requires two asterisks or underscores on either side of the text for the style to be applied.
This is __bold__ text. **This sentence is also bold.**
This is bold text. This sentence is also bold.
One final topic while we're talking about the basics of formatting: line feeds (or returns, depending on your persuasion.) Markdown will only interpret a paragraph if there is a blank line between the two bodies of text.
This is paragraph one
This is paragraph two
Even though this is two different lines, it will be displayed as one:
This is paragraph one This is paragraph two
If, however, you do want the text to appear on two separate lines - a situation where you would use a single <br /> in HTML - end the first line with two spaces
This is paragraph one
This is paragraph two
This is paragraph one
This is paragraph two
So now that you know how to put together a basic document, emphasize important text and ensure your lines of text are displayed as you intend, it's time to add a little structure.
As you've no doubt noticed, this course is broken up into sections. These sections are distinguished using headings.
Markdown provides two ways of displaying headings. The first, Atx-style, is placing 1 - 6 hashes at the start of the line, each hash signifying an "HTML header level."
# This is an H1
### This is an H3
###### This is an H6
If you come from an HTML background, you might be tempted to "close" these hash symbols, and you're in luck because this is supported.
#### This is a closed H4 ####
The second style is known as Setex-style. Is is only usable for H1 and H2 level headers, but is very aesthetically pleasing. To use this style, simply underline the heading with equals signs (H1) or dashes (H2). Any number will do, but I prefer to use enough to completely underline the heading text.
This is an H1
=============
This is an H2
-------------
This is also an H1
=====
Sometimes the best way to present information is to put it in a list. Markdown allows you to display unordered (bulleted) and ordered (numbered) lists.
Unordered lists are denoted by putting a *, + or - at the beginning of each item in the list. There should be a space between the symbol and the text, and a blank line before and after the list.
* Item one
* Item two
* Item three
Numbered lists are similar, except that each item is denoted by a number and a period (1.). The number itself does not matter, and the system interpreting the list will display the correct number for the item.
1. Item one
1. Item two
1. Item three
An item in a list can be multiple paragraphs; to do this, the additional paragraphs must be indented by either four spaces or a tab.
* Item one
Still item one
* Item two
* Item three
Item one
Still item one
Item two
Item three
What use is a web page if you can't link to other pages on the Internet? Luckily, Markdown has you covered.
The simplest way to include a link is to surround the text to display as a link in square brackets, and then the URL to the link in parentheses.
Visit the [DJB](www.darkjedibrotherhood.com/)
Visit the DJB
You can also elect to list your URLs at the end of the document, this keeps them all in one location and makes the main body of text much more readable. Either include the display text at the end of the document or provide a reference in the main body of text and then in the list of URLs later, both of these are illustrated here:
Visit the [DJB] or check out the [Wookieepedia][Wiki].
More text here
[DJB]: http://www.darkjedibrotherhood.com/
[Wiki]: http://starwars.wikia.com/
Visit the [DJB] or check out the [Wookieepedia][Wiki].
More text here
[DJB]: http://www.darkjedibrotherhood.com/ [Wiki]: http://starwars.wikia.com/
Now that you have the basics, try it out for yourself. Use an online editor, like [Ctrl Shift's Markdown Editor][MD Editor].
You might also want to read through documents that are already using Markdown. As mentioned earlier, the Shadow Academy uses Markdown for its course notes, and you can see the syntax behind all of them by adding ".text" to the end of the address to look at it.
https://www.darkjedibrotherhood.com/shadow_academy/courses/86.text
You can see everything behind this [course], and any other course that you want to find out how it was put together. This trick of adding ".text" also works on the [Daring Fireball] blog. I highly recommend seeing how the original creator put together his own documentation.
Take the exam for this course, and then proceed onto Markdown 102 to build onto the knowledge you now have.
[John Gruber]: http://en.wikipedia.org/wiki/John_Gruber [Daring Fireball]: http://daringfireball.net/projects/markdown/ [MD Editor]: https://dillinger.io/ [course]: https://www.darkjedibrotherhood.com/shadow_academy/courses/86.text
Please log in to take this course's exam