Markdown is a way of writing formatted text using only ordinary characters. Asterisks around a word make it italic, a hash sign at the start of a line creates a heading, a dash opens a list. The file stays plain text: it opens in any editor, can be compared line by line and can be kept for decades without depending on any program. Then, when needed, you convert it to HTML, PDF or a word-processor document.
In my work I use it for notes, documentation, article drafts and meeting minutes. The main advantage is not aesthetic: it lets you focus on the structure of the text rather than on its appearance.
Why it is worth learning
- Readable even unconverted. A Markdown file opened in a plain text editor still makes sense: the syntax mimics conventions that were already used in plain-text email.
- Portable. There is no proprietary format to open with the right software. A
.mdfile written today will be readable in twenty years. - Widespread. It is supported by development platforms, note-taking apps, static site generators, wikis and many messaging systems.
- Suited to version control. Being text, Git shows exactly which lines changed between two versions.
Headings
Headings are created with one or more hash signs followed by a space. The number of hashes sets the level.
# Document title
## Chapter
### Section
Two practical rules: always leave the space after the hash (some parsers do not recognise ##Heading) and do not skip levels, for example jumping from ## to ####. The heading hierarchy also matters to screen reader users and to programs that generate an automatic table of contents.
Paragraphs and line breaks
A paragraph is a block of lines separated by a blank line. This is the point that confuses beginners most: a single line break, in most parsers, does not create a new line in the output; the two lines are joined. To start a new paragraph you need a blank line.
If you really need a line break without a new paragraph (an address, a poem), you can end the line with two spaces or with a backslash, depending on the parser. Use it sparingly.
Emphasis
*italic*or_italic_produces italic;**bold**produces bold;***both***produces bold italic.
An underscore inside a word (as in file_name_final) is generally ignored by modern parsers, but to be safe pick the asterisk as your convention and always use it.
Lists
Bulleted lists start with -, * or +; numbered lists with a number followed by a full stop.
- First point
- Second point
- Sub-point indented by two spaces
1. Prepare the files
2. Check the names
3. Archive
A useful detail: in numbered lists, what matters most is the first number. You can write 1. on every line and the parser will still number them 1, 2, 3. That way, if you insert a step in the middle, you do not have to renumber everything by hand.
Links and images
A link is written with the text in square brackets and the address in round brackets: [visible text](address). Images use the same form preceded by an exclamation mark: .
The text in the image's square brackets is not decorative: it becomes the alternative text. Write a real description of what the image shows, not «image1».
Quotes and code
A quote is made by putting > at the start of the line. Inline code goes between backticks, as in `git status`. For code blocks you use three backticks before and after, optionally with the language name to enable syntax highlighting:
```python
print("hello")
```
Inside code blocks Markdown formatting is not interpreted: asterisks and hashes stay as they are. It is the right place for commands, configurations and output that must be copied exactly.
Horizontal rules and special characters
Three dashes alone on a line (---) create a separator line. Careful: if you put them directly under a line of text, some parsers turn that line into a heading. Leave a blank line before.
If you want to write an asterisk or a hash without it being interpreted, put a backslash in front: \* shows a plain asterisk.
Common mistakes
| Mistake | Effect | Fix |
|---|---|---|
#Heading without a space |
Normal text with a hash sign | # Heading |
| No blank line before a list | The list merges with the paragraph | Add a blank line |
| Inconsistent indentation in sub-lists | Wrong levels or a broken list | Always use the same number of spaces |
| Unclosed asterisks | Italics running through the rest of the text | Check the pairs |
Which tools to use
To start, any text editor will do. Editors such as VS Code show a side-by-side preview; note apps such as Obsidian or Joplin save directly in Markdown; for converting to other formats there is Pandoc. My advice is to pick a single tool and write with it for a few weeks: the syntax sticks quickly, and after a while it becomes faster than using formatting menus.
In short
- Markdown is plain text with a few conventions: readable, portable and Git-friendly.
- Paragraphs separated by a blank line, headings with
#and a space, no skipped levels. - Lists, links, images and code have a short syntax that is easy to remember.
- Image alternative text should be written carefully, not left generic.
- The most frequent problems come from missing spaces and forgotten blank lines.
