A heading is a line that starts with one to six hash signs and a space. The number of hashes is the level, so # is the title and ### is a sub-sub-section.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Heading 1
=========

Heading 2
---------

Pressing Enter once does nothing visible: markdown joins the two lines into one paragraph. This is the single most common markdown surprise, and there are three ways around it.

first line  
second line

first line\
second line

Put a backslash in front of a markdown character to show it rather than act on it. It is the way out when your text contains the same symbols markdown uses.

\*not italic\*

\# not a heading

2 \* 3 \* 4

`*everything here is literal*`

Markdown has no comment syntax. An HTML comment is the usual way to leave a note in the file that does not appear in the rendered page.

<!-- This note is not rendered. -->

<!--
A longer note.
Still hidden.
-->

Front matter is metadata at the very top of a markdown file, fenced by three dashes above and below. Static site generators, Obsidian and most note tools read it; a plain renderer ignores it or, worse, prints it.

---
title: Opening .md files
date: 2026-08-27
tags:
  - markdown
  - tools
draft: false
---

# The document starts here

Wrap text in two asterisks to make it bold. Two underscores do the same thing, and both are equally correct, though asterisks are the safer habit.

**bold text**

__also bold__

***bold and italic***

**bold with _italic_ inside**

One asterisk either side gives italic text. A single underscore does the same, with one exception worth knowing about inside words.

*italic text*

_also italic_

**bold with *italic* inside**

Two tildes either side of the text draw a line through it. It is a GitHub-flavoured extension rather than original markdown, which is why a few older renderers ignore it.

~~struck through~~

~~**struck and bold**~~

There is no markdown syntax for underlining, and that is deliberate. On the web an underline means a link, so markdown left it out. When you genuinely need one, HTML is the answer.

<u>underlined text</u>

**bold for emphasis**

*italic for a title or a term*

A dash and a space makes a bullet. A number, a dot and a space makes a numbered list. Nesting works by indenting, and the amount of indentation is where it usually goes wrong.

- first
- second
- third

1. first
2. second
3. third

A task list is a bulleted list where each item starts with a pair of brackets. Empty brackets give an empty box, an x inside gives a ticked one.

- [ ] not done yet
- [x] done
- [X] also done

- [ ] parent task
  - [x] a step that is finished
  - [ ] a step that is not

One backtick either side gives inline code. Three backticks on their own line open and close a block, and a language name after the opening fence turns on highlighting.

Run `npm install` first.

```ts
export function render(source: string) {
  return marked.parse(source);
}
```

export function render(source: string) {
  return marked.parse(source);
}

Start a line with a greater-than sign and a space to quote it. Everything that follows on that line, and on the lines after it that also start with the sign, becomes one quote.

> Nothing here is uploaded.
> Check your network tab.

> First paragraph.
>
> Second paragraph.

Three or more dashes on a line of their own draw a horizontal rule. Asterisks and underscores do the same.

---

***

___

Mermaid turns a few lines of text into a flowchart, a sequence diagram or a Gantt chart. It is not markdown: it is a code block that some renderers have learned to draw. Which is the whole story, because the same file is a picture in one place and a wall of arrows in another.

```mermaid
flowchart LR
  A[Write the file] --> B{Renders?}
  B -- yes --> C[Ship it]
  B -- no --> D[Check the platform]
  D --> A
```

```mermaid
sequenceDiagram
  Browser->>Page: opens the file
  Page-->>Browser: renders it locally
  Note over Page: nothing is uploaded
```

A footnote is a marker in the text and a definition somewhere else in the file. The renderer collects the definitions, numbers them and puts them at the bottom with links back.

Markdown was designed in 2004.[^1]

[^1]: By John Gruber, with Aaron Swartz on the syntax.

Nothing is uploaded.[^privacy]

[^privacy]:
    The parser runs in the browser.

    Indent continuation lines by four spaces.

A link is the text in square brackets followed immediately by the URL in round brackets. No space between the two, which is the mistake that catches everyone once.

[NanoFile](https://nanofile.app)

[NanoFile](https://nanofile.app "Open .md files in your browser")

An image is written like a link with an exclamation mark in front of it. The square brackets hold the alt text, not a caption.

![A blue heron in flight](heron.jpg)

![A blue heron](heron.jpg "Photographed at dawn")

A table is rows of cells separated by pipes, with a line of dashes under the header row. Tables are a GitHub-flavoured extension, not original markdown, but support is close to universal now.

| Element | Support |
| --- | --- |
| Tables | GitHub-flavoured |
| Task lists | Yes |

| Left | Centre | Right |
| :--- | :----: | ----: |
| a | b | 1,00 |

Discord uses its own dialect of markdown. Most of it matches what you already know, with a handful of additions and a longer list of omissions.

**bold**
*italic*
__underline__
~~strikethrough~~
***bold italic***
`inline code`
> a quote
# Heading 1
## Heading 2
### Heading 3
- a bullet
1. a numbered item
[a link](https://example.com)

||spoiler text||

-# small text

```ts
const highlighted = true;
```

const highlighted = true;

Slack calls its formatting mrkdwn, and the name is a warning: bold is one asterisk, italic is one underscore, and several things you expect are missing.

*bold*
_italic_
~strikethrough~
`inline code`
> a quote
- a bullet
1. a numbered item
```
a code block
```

a code block