Guides › Text, code, and data

Markdown basics: headings, lists, links, and tables

Last updated 10 October 2026 · Written by Souren Das

Markdown is a way of writing formatted text with ordinary characters. You type a # for a heading and wrap a word in two asterisks to make it bold, and a program turns that into a formatted page. It is used for README files on GitHub, notes apps such as Obsidian and Notion, documentation sites, and many chat and forum tools. This guide covers the syntax you will use every day, shows what the preview in Markdown Editor understands, and points out where different Markdown engines disagree.

Why bother with Markdown

A Markdown file is plain text. It opens in any editor on any device, it works well with version control because changes are easy to compare line by line, and it does not lock you into one program. You can write a document once and turn it into HTML for a website or paste it into a tool that renders Markdown. For notes, project documentation, and changelogs, it is often quicker than a word processor once you know a dozen symbols.

The basics, with examples

Headings

Start a line with one to three hash signs and a space. # is the biggest heading, ## the next, ### the next.

# Project name
## Installation
### On Windows

The space after the hashes matters. #Installation without a space is plain text in most engines.

Paragraphs and line breaks

Leave a blank line between paragraphs. Lines next to each other without a blank line between them are joined into one paragraph. This surprises people at first, but it means you can wrap long lines in your editor without changing the output.

Bold, italic, and strikethrough

**bold**   *italic*   ***bold italic***   ~~struck out~~

Many engines also accept underscores for italics, like _this_. The preview in Markdown Editor only uses asterisks, so prefer asterisks if you want the same result everywhere.

Lists

Start each item with a dash and a space for bullets, or a number, full stop, and space for numbered lists. Task lists use - [ ] for an open item and - [x] for a done one.

- Milk
- Eggs

1. Unzip the file
2. Run the installer

- [x] Write draft
- [ ] Send for review

Links

[FileTools Kit](https://www.filetoolskit.com)

The text in square brackets is what the reader sees; the address in round brackets is where it goes. No space between the brackets.

Quotes and rules

Start a line with > and a space for a quote. Three dashes on a line on their own make a horizontal rule.

Code

Wrap a short piece of code in single backticks: `npm install`. For several lines, put three backticks on the line before and after. Inside a code block, symbols such as * and # are shown as they are, not treated as formatting.

```
git clone https://example.com/repo.git
cd repo
```

Tables

Separate cells with pipes, and put a row of dashes under the header row.

| Tool | Runs in |
| --- | --- |
| Merge PDF | Browser |
| Text Diff | Browser |

Cells do not have to line up in your source. Lining them up just makes the text easier to read.

Writing in Markdown Editor

Open Markdown Editor. It opens with sample text you can read and then replace.
Type in the editor pane. The preview updates as you type in Split View. Use Editor Only to focus on writing or Preview Only to read the result full width.
Select some text and use the toolbar to wrap it in syntax for headings, bold, italic, strikethrough, lists, task boxes, quotes, code blocks, and links. This is handy until the symbols become habit.
Watch the counters for words, characters, lines, and an estimated reading time at 200 words per minute.
When you are done, press Download .md to save the file, Copy Markdown to paste the source somewhere else, or Copy HTML to paste the formatted result into a site builder or email tool.

The text lives only in this tab. Refreshing or closing it clears your work, so download or copy before you leave.

Where the preview differs from GitHub

The preview here is a lightweight renderer for everyday Markdown, not a full CommonMark or GitHub engine. Knowing the differences saves confusion:

Bullets must start with a dash. GitHub also accepts * and +.
Italics use asterisks only.
Nested lists, footnotes, and images are not rendered.
Links must start with http:// or https://. Relative links are left as text.
Table header rows look the same as other rows.
Numbered lists keep the numbers you typed. Some engines renumber them.

If something renders oddly here but you need it on GitHub, check it in GitHub's own preview before you commit.

Common mistakes

No blank line before a list. Some engines treat the list as part of the previous paragraph. Always leave a blank line before and after lists, tables, and code blocks.
Missing space after # or -. The symbol is then shown as text.
Unclosed backticks or asterisks. One stray * can italicise the rest of a line. Check the preview.
Tabs versus spaces. Indentation rules differ between engines. Use spaces.
Special characters you want to show. To show a literal * or #, put it inside backticks.

Privacy

Markdown Editor runs entirely in your browser tab. The text is not sent to FileTools Kit and is not saved on a server or in your browser storage. That also means there is no recovery if you close the tab, so save your work.

FAQ

What file extension should I use?

.md is standard. Download .md uses it.

Can I open an existing .md file?

Open it in any text editor, copy the contents, and paste them into Markdown Editor.

Is Markdown the same everywhere?

The basics are. Extras such as tables, task lists, and footnotes depend on the engine. GitHub Flavored Markdown and CommonMark are the two most common specifications.

Can I write a README here?

Yes. Write it, press Download .md, rename the file README.md, and add it to your repository.

Written by Souren Das, FileTools Kit, Bengaluru. Last updated 10 October 2026. Spotted a mistake or a step that does not match the tool? Email support@filetoolskit.com and I will fix it. See how tools and guides are tested.