Using Markdown
Markdown is a way to style text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like # or *. For a quick cheat sheet, take a look at this PDF overview:
For a more in-depth guide, please read through everything below.
## Heading h2
### Heading h3
#### Heading h4
Notes:
- We don’t use
h1headings, as they already are displayed on every page as its title, and we should not apply more than oneh1per page.When you use a top level heading, you’re setting up a semantic relationship between that heading and the remainder of the content on a page, describing what it is about. If you then use a second
h1on the same page, you’re creating some potential confusion, because someone, or a search engine might see that as the ending of the semantic relationship between the content after the firsth1and the start of this newh1. - Always start with
h2(##), and respect the order h2 → h3 → h4. Never skip the hierarchy level, such as h2 → h4.The six heading elements, H1 through H6, denote section headings. Although the order and occurrence of headings is not constrained by the HTML DTD, documents should not skip levels (for example, from H1 to H3), as converting such documents to other representations is often problematic. [W3C]
- Always leave a blank space between the hash
#and the text next to it, otherwise it won’t render properly. - For keeping the text clear and the markdown consistent, jump a line between any heading and its subsequent paragraph.
Regular paragraphs are obtained by just writing text lines. If you hit enter between two lines, both lines will be joined into a single paragraph, which is called wrapping text. But, if you leave a blank line between them, they will split into two paragraphs.
It is a best practice to write each paragraph on a single line. Don’t put line breaks at the end of each sentence, and don’t break up lines at a certain character limit. It is very difficult to review and edit copy with artificial lines breaks.
We usually break the lines within paragraphs to facilitate reviews. Do not leave blank spaces
after the last word of the line broken within a paragraph, unless you want it to be intentionally
broken with a <br>.
A sequence of three or more dashes will produce a horizontal line, but let’s use always 4 as standard. Leave blank lines after and before it:
Text
<!-- blank line -->
----
<!-- blank line -->
Text
To display bold or italic text, wrap it in 2 stars (for bold) or underscores (for italic).
This is **bold** and this is _italic_.
Markdown doesn’t natively support underlined text. If necessary you can hardcode it with the
HTML tag ins (<ins>underlined text</ins>), however, it is inadvisable to do so.
There are a few different ways to display links with markdown markup, but to keep some standards, let’s try to use the following options only.
Important notes:
- Don’t take it as a restrictive rule, but avoid using meaningless text for links such as “this article” or “read here.” The link text should be meaningful even if taken out of context; this makes the links more useful and accessible for people using screen readers.
- Check for broken links: http://www.deadlinkchecker.com/
We’d rather use inline links, such as [Text to display](link), as they are easier to maintain. To make an inline link open in a new tab, you have to resort to raw HTML, which markdown will render just fine. Example:
<a href="https://www.gradientmetrics.com/" target="_blank">Website in new window</a>`
Use relative links when referring to links found on
handbook.gradientmetrics.com. For example, a link to our announcements should look like this /announcements/ and not this /announcements.
For links to any other website (e.g. https://www.gradientmetrics.com) you must use the entire link, including the https://.
If you’re adding an email address to a page be sure to format your link with mailto to avoid creating broken links. For example,
[example@gradientmetrics.com](mailto:example@gradientmetrics.com)
Both ordered and unordered lists are very straight-forward to produce. There are a few ways to produce the same results, but let’s stick with the following, again, to maintain some standards.
Always use 3 blank spaces to indent a nested list (to create sub items).
Tip: don’t leave blank lines between the items, unless you have a reason to do so.
Important: always leave a blank line between the paragraph or heading and the subsequent list! If you don’t, the list will not render. To be practical and avoid errors on the numbers, use “1” for all the items. The markdown engine will output them in the correct order.
Paragraph:
1. Item one
1. Sub item one
1. Sub item two
1. Sub item three
1. Item two
Unordered lists are very easy to create too:
Paragraph:
- Item 1
- Item 2
- Item 3
- Sub item 1
- Sub item 2
- Item 4
Let’s say, for some reason, you want to split a list in different parts. To do that, use the
markup ^ to indicate the end of a list and the beginning of the next:
- list one - item 1
- list one - item 2
- sub item 1
- sub item 2
- list one - item 3
^
- list two - item A
- list two - item B
^
- list three - item _i_
- list three - item _ii_
To insert images to your markdown file, use the markup . The path can either
be relative to the website, or a full URL for an external image. The supported formats are
.png, .jpg, .gif. You might be able to use some .svg files too, depending on its structure.
If you want to add a caption to your image, it’s easily achieved with:
*My caption*
For clickable images, simply wrap the image markup into a link markup:
[*My caption*][/]
See the Videos tab over at our Shortcodes section.