Your profile on Markdown

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

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:

  1. hello
  2. hello
  3. 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]( "title tag")
<a href="" title="title tag">example</a>

A plain link is also recognised but wrapping it in <> can help, especially if a editor you use syntax-highlights the original Markdown text.

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

With a little HTML, you can add the icon into the text to click.

<a href=""><i class="fa fa-github"></i> Monitoring Artist Github</a>

Monitoring Artist Github

The website is currently using Font Awesome v4.5 and you can see all the possible icons you could use at 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](**: 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](, 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="">
    <img src="" width="480">

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.

profile for Alister Bulman on Stack Exchange, a network of free, community-driven Q&A sites

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’

What you will not be able to do is add JavaScript tags to make actions in-page. Also disallowed are iframes, which might also allow security issues.

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.

Block elements

# 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
  1. numbered lists
  2. easiest to put your own numbers
  3. or you can just use the same number,
  4. which will also make reordering easier

Inline elements

Simple markup is simple with **bold**, *italics*, ***or both!***
[Links]( "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.

What does a developer do?

The developers you place are writing Javascript, Python, Java, C#, PHP, Ruby, and so more. What’s the difference, and how do you find the good ones?

You don't need to become a developer to find great developers - but knowing more about what the really good developers your clients are seeking, helps you to find the candidates - developers, designers, hackers, ops, and everyone else that make the 21st century work online.

These emails won't teach you to be a developer, but you'll get a hint of the day to day work of those you are looking for.

Header image by Dustin Curtis via his Github repo for the 'Markdown mark'