Markdown is a plain text formatting syntax that is designed to keep formatting readable, but provide hints to convert to common HTML markup elements when published online. Personally, most of my own (longer) notes I write to myself are in Markdown - because the structure it shows, even without converting, makes it easy to read. I suspect, I’m not the only developer to do that either.
Markdown was created with the goal of writing content for the web, easier, avoiding having to open and close tags around blocks of text for the most common of text alterations
There are several ‘flavours’ of Markdown, which mostly differ if the more advanced extensions. Contract Availability has a fairly generic version that follows the main standards. If you are wondering if a particular syntax works - try it, and see what the result it. The worst that could happen is having to change it to a HTML equivalent, which might be a little bit more complicated.
There are a number of other sites that also use Markdown, and they have their own help pages for Markdown that you might find useful. Again, not all of the formatting listed on these pages will be available
- John Gruber’s original Markdown page - Basics and syntax
- Stackoverflow Markdown help
- Github Markdown masics
The Markdown syntax is geared towards basic word processing tasks and their HTML equivalents
Here’s a great example of a Devops Engineer - Jan Garaj’s profile on Contract Availability (and he’s also looking for a new Devops role from mid-January 2016!)
Here is how he does some of the parts of his profile:
Headers are really easy - just add hashes to make a heading - the more hashes (usually three or four levels are enough)
# header 1 - very big ## header 2 - big ### header 3 - still pretty big
There is another way to do simple headings - with equal signs and dashes for headers, levels 1 and 2.
top level H1 === second levels ---
That only gives two levels though - the hashes allow you up to 6 - corresponding to the H1 - H6 tags in HTML.
A horizontal line can be done a few ways - most usually with several dashes - but other characters can also work:
Since simple text is probably the most common thing - they are also the easiest - just add blank lines between the text to have it recognised as a paragraph. Markdown, like HTML, doesn’t generally care how many blank lines you have between paragraphs or other sections, so feel free to pad it out to make it easier to look at in the raw Markdown form if you want.
block quotes start with a Greater Than sign.
> block quotes start with a Greater Than sign
Simple lists - unordered:
- list items
- list items
* list items * list items
Numbered lists start with a number:
- They don’t have to be different though - the same number, repeated, is also recognised
1. hello 1. hello 1. They don't have to be different though...
link tags are easy enough in Markdown, or plain HTML - these will look the same on screen:
[example](http://example.com "title tag") <a href="https://example.com" title="title tag">example</a>
Using HTML within Markdown text
Since Markdown also allows HTML (and this site has the feature enabled), you can add icons, and even larger versions of them:
<i class="fa fa-stack-overflow fa-3x"></i> <http://careers.stackoverflow.com/alister>
With a little HTML, you can add the icon into the text to click.
<a href="https://github.com/monitoringartist"><i class="fa fa-github"></i> Monitoring Artist Github</a>
The website is currently using Font Awesome v4.5 and you can see all the possible icons you could use at https://fortawesome.github.io/Font-Awesome/icons/ You can just sprinkle your own profile with little bit of HTML - like this:
<i class="fa fa-stack-overflow"></i>
It’s also easy to link to other things:
**[Happy New Year Zenpack](http://youtu.be/mz9djnjlpws)**: RRD, Python, Zenoss
Here, the “Happy New Year Zenpack” is the link text, and it is also bolded (with
** on each side). It’s going to a YouTube page.
The link above was made bold with two astericks either side - the other thing you can do is italics - with just a single asterisk each side. With three each side - it is italic, and bold!.
Images in Markdown
Here, Jan Garaj has wrapped an image as a link:
[image tag - in Markdown](http://youtu.be/mz9djnjlpws), but anything more complex, like changing the size of the image would be a lot easier to do in plain HTML.
The end result is clickable image that goes to play a YouTube video.
It may be less complicated to do it with some HTML - but in Markdown, its always an option to be able to drop to raw HTML. If you want to use some more HTML attributes, like sizing the image better on the page, it’s probably easier to use HTML.
<a href="https://github.com/monitoringartist/Zabbix-Docker-Monitoring"> <img src="https://raw.githubusercontent.com/monitoringartist/Zabbix-Docker-Monitoring/master/doc/zabbix-docker-container-cpu-graph.png" width="480"> </a>
You can also put StackOverflow, or StackExchange ‘flair’ on your profile easily - just copy the HTML from the ‘flair’ tab on your profile (SO, SE, or other sites). This is an image, that links back to my own profile there.
I’ve got some plans to be able to put some specific site links into their own space on the main profile page - things like StackExchange, Github, LinkedIn and so on. They will be in a new part of the profile editing pages when they are ready.
Disallowed - because ‘security’
In Summary - the basic syntax
The original Jon Gruber pages about Markdown are the first things you find with a Google search for ‘Markdown’, and they are still good for all of your quick reference needs. Markdown Basics and Syntax.
# headings (or === —-, but then you only get two levels)
paragraphs are simple text with blank lines above and below
Add two spaces at the end of a line
for a manual line break - but
watch out your editor
doesn’t automatically remove them.
> block quotes start with a greater-than sign
block quotes start with a greater-than sign
blocks of code are just indented four characters
Or you can use ‘code fences’
``` three back ticks, at the start of a line and the same to end. There isn't extra support for language syntax highlighting. ```
* lists are collections of '*'s - or you can use hyphens
- lists are collections of ‘*’s
- or starting a list with a hyphen
1. numbered lists 2. easiest to put your own numbers 1. or you can just use the same number, 1. which will also make reordering easier
- numbered lists
- easiest to put your own numbers
- or you can just use the same number,
- which will also make reordering easier
Simple markup is simple with **bold**, *italics*, ***or both!*** [Links](http://example.com "with Title tags") are also quite easy, images add an exclamation mark at the start, and the link is the URL to the picture. You can also mark `some code` inline with single back-ticks
Simple markup is simple with bold, italics, or both.
Links are also quite easy, images add an exclamation mark at the start, and the link is the URL to the picture.
You can also mark
some code inline with single back-ticks
You can do a lot with some simple markup, or adding some HTML where it might be required to help spice things up. Above all, be real with the contents of your profile. Tell the reader what you are looking for, and don’t waste their time with trying to sell to them. Instead, show them that you know what you are doing, and that you intend to help them.