Tips for Beginners. Markdown Syntax

5 min read

Note: This article will be helpful for freshers who are just at the beginning of the tech writing career.

Doxter supports markdown language and this is a really important feature. If you’re not markdown user yet so that’s the right time to begin.

Why do you need it?
Let’s begin from the point that markdown is kind of out-of-Hogwarts magic. It makes you able to format text on the run, just put some easy punctuation before and after the line you need to format and the job will be done. Sounds not so impressive but it’s a really great time-saver when you work with big text files. When you’re trained markdown user you can put syntax as fast as you put emoji at the end of the sentences and so have your text perfectly formatted. Speed is important as far as it improves your productivity and helps you to stay a competitive specialist.
Markdown does not expend filesize, again it’s a great plus if you work big documents or have to transfer the doc from one system to another.
And more. Markdown is a unified world system, so learn it just once and be capable to use it with plenty of different software.


Heading level

Heading is made with # sign. To compare with HTML # is relevant for <h1>, ## for <h2>, ### for <h3> and etc.

e.g.
## Heading level 2

Heading level 2




Italic

Put * (single asterisks) before and after the text you’d like to make Italic. As an option, you can use _ (single underscore) for the same purpose

e.g.
Way to emphasize your text with *Number 1* and way _Number 2_.

Way to emphasize your text with Number 1 and way Number 2.


Bold

Use double signs ** or __ before and after the text to make it bold.

e.g.
Let’s make things **bold**. Let’s make things __bold__.

Let’s make things bold


Italic & Bold

Use triple asterisks ***, or triple underscore ___, or double underline and single asterisks __*, or single underline and double asterisks _** before and after your text

e.g.
Way to show that the text is ***really important***
Way to show that the text is ___really important___
Way to show that the text is __*really important*__
Way to show that the text is **_really important_**

The final look will be the same: Way to show that the text is really important.


Strikethrough

To strikethrough words, use two tilde symbols (~~) before and after the words.

e.g.
~~No-no, don’t look at this text!~~ Here is the right one
No-no, don’t look at this text! Here is the right one


List

For markdown numbered (or ordered) list add a number before each line.

e.g.
1. First item
2. Second item
3. Third item
4. Fourth item

For unordered list add dashes (-) before each line.

e.g.
-First item
-Second item
-Third item
-Fourth item

For nested list indent one or more items. Work for both numbered (or ordered) and an unordered list.

e.g.
1. First item
2. Second item
   1. Indented item
   2. Indented item
3. Third item
4. Fourth item


  1. First item
  2. Second item
       1. Indented item
       2. Indented item
  3. Third item
  4. Fourth item


Task list

To create a task list, use a dash (-) and brackets ([ ]) in front of each line. Use construction - [x] to create a selected checkbox.

e.g.
- [x] Plan
- [ ] Do
- [ ] Check
- [ ] Act

Definition

To create a definition list, put the term on the first line, the next line begins from сolon (:) and then type definition.

e.g.
Term #1
: This is the definition of the first term.

Term #2
: Definition of the term.
: Alternative definition of the term.

Term #1
This is the definition of the first term.

Term #2
Definition of the term.
Alternative definition of the term.


Insert code

To present phrase as code use tick marks (`).

e.g.
`*This text is written with asterisks but no format is changed*`

*This text is written with asterisks but no format is changed*


Tables

Use three or more hyphens (---) for column’s header, and use pipes (|) to separate each column. Pipes on either end of the table are optional.

e.g.
| Column title 1 | Column title 2 |
| --- | --- |
| Text for fun | Text for business |
|Random text 1 | Random text 2 |

Column title 1 Column title 2
Text for fun Text for business
Random text 1 Random text 2



Links

To create simple link put URL between < > brackets

e.g.
<https://doxter.io >
<hello@doxter.io>

https://doxter.io/
hello@doxter.io

To create anchored link put the text of anchor in brackets [] and URL in parentheses ()

e.g.
Read some [tips for technical writers](https:/doxter.io/blog/technical-writing-tips/)

Read some tips for technical writers


Images

To insert image use an exclamation mark (!), alt text in brackets [ ], URL or image path in parentheses ( ). You can optionally add a title after the URL in the parentheses.

e.g.
![Scheme #1](/images/scheme.jpg)
![Another scheme](/images/scheme2.png “title attribute”)

title attribute

Horizontal Rules

Use three or more asterisks (***), dashes (—), or underscores (___) for creating a horizontal rule

e.g.
***
---
___
The result will be the same:





Quotes

For creating Quote use > (“greater than” sign) before each line

e.g.
>I see trees of green, red roses too
>I see them bloom for me and you
make a pause here
>And I think to myself what a wonderful world

The result is:

I see trees of green, red roses too
I see them bloom for me and you
make a pause here
And I think to myself what a wonderful world




Instead of a conclusion
There are helpful knowledge and knowledge you’ll never use. Markdown syntax belongs to the first category. In the article are given just basic of syntax, points every beginner at tech writing should know.
To get the advanced level tips visit John Gruber’s original spec.


Subscribe
Put correct email, please
Are you a technical writer? Grow your efficiency with monthly tips and how-tos.