How to write posts with markdown

José Obregón · Tech Lead 2021-07-25 · 10 min read

This article explain how to create posts with markdown for the Siblings Software's blog.

What is Markdown?

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. Created by John Gruber in 2004, Markdown is currently one of the world’s most popular markup languages. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid HTML.

Why use Markdown?

10 reasons to use markdown:

  1. It's easy to lern. It take just a few minutes understand how to write a markdown document.
  2. It's intentionally simple. You can write a markdown document (like a blog) in few minutes using any plain text editor.
  3. Lets you focus on important things, reduces distractions and increases productivity.
  4. You can write HTML code in a .md document too. It will be rendered as you typed it.
  5. It's portable. Files containing Markdown-formatted text can be opened using virtually any application. You can use any text editor to write markdown.
  6. It's platform independent. You can create Markdown-formatted text on any device running any operating system.
  7. It's lightweight. This is because it's just plain text and you don't have to write too much code to create the elements.
  8. It can be used for everything. People use it to create websites, documents, notes, books, presentations, email messages, technical documentation and blog posts.
  9. Markdown is future proof. Even if the application you’re using stops working at some point in the future, you’ll still be able to read your Markdown-formatted text using a text editing application. This is an important consideration when it comes to books, university theses, and other milestone documents that need to be preserved indefinitely.
  10. Markdown is everywhere. Websites like Reddit and GitHub support Markdown, and lots of desktop and web-based applications support it as well. It's very used in blogs.

Headings

Use # to define headings.

Main title

The main title is the first and biggest title in the document. It's centered in the page and use a uppercase style. The main title of this post is: "How to write posts with markdown".

Use one # to define the main title.

Use just one main title per article.

Example:

# This is a main title

HTML tag: h1

Other titles

Others titles are smaller in size and importance. Be careful and use a correct hierarchy.

Use just two or more # to define the heading.

Example:

## This could be a subtitle

HTML tag: h2, h3, h4, h5, h6

Do not use more than 4 levels of headings. It is confusing for readers.

h2 and h3 headings will have anchor links automatically. The anchor links are always in lowercase and use "-" instead of white spaces.

For example, the anchor link for ## Anchor links will be anchor-links.

Anchor links are useful to jump to a specific place on a page. It's located in the end of the url and start with a #.

For exaple:

https://www.siblingssofware.com/en/blog/how-to-write-posts-with-markdown#anchor-links

Paragraphs

Paragraphs are the most common elements. Each text in a markdown without any mark will be converted to a paragraph.

Example:

This is a paragraph

HTML tag: p

Emojis

Yes, you can use emojis! 💪

Bold, italic, emphasis, highlight

Use * or _ for bold.

Use ** or __ to emphasized.

Use <i></i> to italicized.

Use <mark></mark> to highlight.

Use ~~ to strike.

Example:

This is a *bold* word
This is a **emphasized** word
This is a <i>italicized</i> word
This is a <mark>highlight</mark> word
This is a ~~strike~~ word

You can mix any of these rules!

Example:

This is a ~~<mark><i>***bolded, emphasized, italicized, highlight and striked***</i></mark>~~ text

This is a bolded, emphasized, italicized, highlight and striked text

For SEO reasons, use bold styles for "important text" not just to stylize the text.

HTML tags: strong, em, i, mark, del

Blockquote

Use > to define a Blockquote.

This is mainly used to show cites.

Example:

> This is a **blockquote**

This is a blockquote

HTML tag: blockquote

Small text

Use <small></small> to define small text.

Use it for text that is not relevant for the current article.

Example:

<small>Small text</small>

Small text

HTML tag: small

Use []() to define a link.

Example:

[This is a link](https://google.com)

This is a link

HTML tag: a

All text with link format will be automatically converted to a link.

Example:

www.example.com, https://example.com, and contact@example.com.

www.example.com, https://example.com, and contact@example.com.

HTML tag: a

If you're adding an email address be sure to format your link with mailto: to avoid creating broken links.

For example:

[info@siblingssoftware.com](mailto:example@gitlab.com)

info@siblingssoftware.com

HTML tag: a

If you're adding an phone number be sure to format your link with tel: to avoid creating broken links.

For example: [+1 347 774 1275](tel:+13477741275)

+1 347 774 1275

HTML tag: a

Images

All images must to have an alt text and a url. The caption is optional.

The next code define a image:

![Alt text](https://siblingssoftware.com/social.png)*My caption*

Siblings SoftwareSiblings Software logo

HTML tag: img

Videos

Yes, you can embed videos in the page too 😎

To embed a video use the next code:

<figure class="video_container">
  <iframe class="video_container_iframe" src="https://www.youtube.com/embed/enMumwvLAug" frameborder="0" allowfullscreen="true"></iframe>
</figure>

HTML tag: figure, iframe

Footnote

Use [^1] to define a footnotes. You can use it in any place in the article. All footnotes will be located at the bottom of the article.

Example:

This is a simple numered footnote reference. [^1]
This is a longer multiple blocks footnote reference. [^2]
This is a inline note. ^[You can type them inline, which may be easier, since you don’t have to pick an identifier and move down to type the note.]

[^1]: Here is the simple numered footnote.

[^2]: Here’s one with multiple blocks.

    Subsequent paragraphs are indented to show that they
belong to the previous footnote.

    The whole paragraph can be indented, or just the first
    line.  In this way, multi-paragraph footnotes work like
    multi-paragraph list items.

This is a simple numered footnote reference. 1

This is a longer multiple blocks footnote reference. 2

This is a inline note. 3

HTML tag: div, ol, li, p, a, sup

Horizontal rule

Use ___ or --- or *** to define a horizontal rule (horizontal line).

This element is used like a thematic break between paragraphs or separate sections in an article.

Example:

---

HTML tag: hr

Ordered list

Use numbers to define items in an ordered list.

Example:

1. Clean my room
2. Fix phone
3. Send emails
  1. Clean my room
  2. Fix phone
  3. Send emails

HTML tag: ol, li

Unordered list

Use * or - to define items in an unordered list.

Example:

* Bread
* Cheese
* Milk
  • Bread
  • Cheese
  • Milk

Todo list

Use [x] inside the list items to define a checkbox. Can use it with unordered lists or ordered lists.

Example:

- [x] Create a blog
- [x] Style posts
- [ ] Improve blogging process
  • Create a blog
  • Style posts
  • Improve blogging process

HTML tag: ul, ol, li, input

Nested Lists

You can nest list and even mix the three types of list.

It's useful when you want to use a list inside a list item.

Example:

1. Numbers
    * Number 1
        * Num 2
        * Num 3
    * Number 4
2. Tasks
    * [x] Task 1
    * [ ] Task 2
  1. Numbers
    • Number 1
    • Number 1
  2. Tasks
    • Task 1
    • Task 2

HTML tag: ul, ol, li, input

Table

The next code define a table:

| Id     | Task        | Owner       | Status      |
| :----: | ----------  | ----------- | -----------:|
| 1      | Create blog | José        | Done        |
| 2      | Create post | Denisse     | In progress |
| 3      | Review post | Javier      | To do       |
Id Task Owner Status
1 Create blog José Done
2 Create post Denisse In progress
3 Review post Javier To do

It is possible to use markdown inside the cells.

HTML tag: table, thead, th, tbody, tr, td

Inline code

Use `` (backtick) to define a inline code. This element is used to highlight code in text. All the text between backtick has a monospace font.

Example:

This is a simple line code in JavaScript: `console.log('Hello world!')`

This is a simple line code in JavaScript: console.log('Hello world!')

HTML tag: code

Code block

Use ``` (three backticks) to define a block code. This element is used to highlight a block of code separately of the text. All the text in a block code has a monospace font.

Example:

    ```
    // This is a simple line code in JavaScript
    console.log('Hello world!')
    ```
    // This is a simple line code in JavaScript
    console.log('Hello world!')

HTML tag: pre, code

Preformatted text

Use <pre></pre> to define a preformatted text.

This mainly when you want to show the text with the same format as it's in the markdown file, like white spaces, tabs, new lines, etc. The text inside is not converted to HTML.

Example:

<pre>
This is a
    preformatted        text
</pre>
This is a
    preformatted        text

HTML tag: pre

HTML

It is possible to use HTML directly in a markdown document.

For example, to show words in italic, o mark the text we use HTML: <i> <mark>. But we can use any HTML tag with any HTML property in a .md document.

Do not use to much HTML. HTML code in a markdown document make it less portable and difficult to read and modify.

Use HTML style property only when it's strictly necessary.

Buttons

Use <button></button> to define a button.

Buttons are used in cases where you want to "call to action" or execute an event. This is the most complex element.

You can specify a onclick event and call a javascript function.

Example:

<button onclick="alert('Hi there!')">Say hello</button>

HTML tag: button

Paragraphs

We can define a paragraph with the tag <p> as follow:

<p class="center bold grey bigger">
    I am a beautiful text
</p>

I am a beautiful text

As you noted, it is possible to specify classes to stylize the paragraph.

class css class css
bold font-weight: 700 blue color: #0000EE
light font-weight: 300 yellow color: #FFFF00
normal font-size: 1.2em green color: #008000
big font-size: 1.4em orange color: #cc8d18
bigger font-size: 1.8em center text-align: center
biggest font-size: 2.2em left text-align: left
small font-size: 1em right text-align: right
smaller font-size: 0.8em justify text-align: justify
smallest font-size: 0.6em uppercase text-transform: uppercase
white color: #ffffff lowercase text-transform: lowercase
black color: #000000 capitalize text-transform: capitalize
red color: #000000 italic font-style: italic

Block and inline elements

There is two types of elements in a markdown documents: inline or block.

Block elements

Block elements always starts on a new line and have a top and a bottom margin.

Block elements: headings, paragraphs, images, videos, tables, lists, blockquote, Preformatted text, small text, horizontal rule, code block and buttons.

Inline elements

Inline elements does not starts on a new line and only takes up as much width as necessary.

Inline elements: links, inline code, bold, em, i, mark and del.

Keywords

At the end of any post is very good idea to specify some keywords.

You can specify the keywords as follow:

Keywords: **markdown**, **post**

Keywords: markdown, post


  1. Here is the simple numered footnote.

  2. Here’s a footnote with multiple blocks.

    Subsequent paragraphs are indented to show that they belong to the previous footnote.

    The whole paragraph can be indented, or just the first line. In this way, multi-paragraph footnotes work like multi-paragraph list items.

  3. You can type them inline, which may be easier, since you don’t have to pick an identifier and move down to type the note.