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.
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.
10 reasons to use markdown:
- It's easy to lern. It take just a few minutes understand how to write a markdown document.
- It's intentionally simple. You can write a markdown document (like a blog) in few minutes using any plain text editor.
- Lets you focus on important things, reduces distractions and increases productivity.
- You can write HTML code in a .md document too. It will be rendered as you typed it.
- It's portable. Files containing Markdown-formatted text can be opened using virtually any application. You can use any text editor to write markdown.
- It's platform independent. You can create Markdown-formatted text on any device running any operating system.
- 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.
- It can be used for everything. People use it to create websites, documents, notes, books, presentations, email messages, technical documentation and blog posts.
- 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.
- 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.
# to define headings.
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".
# to define the main title.
Use just one main title per article.
# This is a main title
HTML tag: h1
Others titles are smaller in size and importance. Be careful and use a correct hierarchy.
Use just two or more
# to define the heading.
## 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 are useful to jump to a specific place on a page. It's located in the end of the url and start with a
Paragraphs are the most common elements. Each text in a markdown without any mark will be converted to a paragraph.
This is a paragraph
HTML tag: p
Yes, you can use emojis! 💪
_ for bold.
__ to emphasized.
<i></i> to italicized.
<mark></mark> to highlight.
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!
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
> to define a Blockquote.
This is mainly used to show cites.
> This is a **blockquote**
This is a blockquote
HTML tag: blockquote
<small></small> to define small text.
Use it for text that is not relevant for the current article.
HTML tag: small
() to define a link.
[This is a link](https://google.com)
HTML tag: a
All text with link format will be automatically converted to a link.
www.example.com, https://example.com, and firstname.lastname@example.org.
HTML tag: a
If you're adding an email address be sure to format your link with
mailto: to avoid creating broken links.
HTML tag: a
If you're adding an phone number be sure to format your link with
tel: to avoid creating broken links.
[+1 347 774 1275](tel:+13477741275)
HTML tag: a
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 Software logo
HTML tag: img
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
[^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.
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
*** to define a horizontal rule (horizontal line).
This element is used like a thematic break between paragraphs or separate sections in an article.
HTML tag: hr
Use numbers to define items in an ordered list.
1. Clean my room 2. Fix phone 3. Send emails
- Clean my room
- Fix phone
- Send emails
HTML tag: ol, li
- to define items in an unordered list.
* Bread * Cheese * Milk
[x] inside the list items to define a checkbox. Can use it with unordered lists or ordered lists.
- [x] Create a blog - [x] Style posts - [ ] Improve blogging process
- Create a blog
- Style posts
- Improve blogging process
HTML tag: ul, ol, li, input
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.
1. Numbers * Number 1 * Num 2 * Num 3 * Number 4 2. Tasks * [x] Task 1 * [ ] Task 2
- Number 1
- Number 1
- Task 1
- Task 2
HTML tag: ul, ol, li, input
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 |
|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
`` (backtick) to define a inline code. This element is used to highlight code in text. All the text between backtick has a monospace font.
HTML tag: code
``` (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.
HTML tag: pre, code
<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.
<pre> This is a preformatted text </pre>
This is a preformatted text
HTML tag: pre
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:
<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.
<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.
<button onclick="alert('Hi there!')">Say hello</button>
HTML tag: button
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.
|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|
There is two types of elements in a markdown documents: inline or block.
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 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.
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
Here is the simple numered footnote.↩
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.↩
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.↩