# Markdown

This page is for the person who writes the notes. It states which Markdown the
editor understands and how a note shows it.

## One note surface

A note has one surface, and the Markdown source is always the document.
Markers are hidden and the text is styled in place, and the source comes back
where your cursor is. A block construct shows its markers while you are on the
line that carries them. A fenced block shows its fences while you are anywhere
inside it. An inline construct shows its markers while your selection touches
the whole construct, so a cursor inside a bold word brings both `**` runs back.

A published link shows the same note through the same grammar, so the two
never disagree about what a note means.

## Formatting tools

The row of tools above the note formats the text for you, so you do not need to
know Markdown. Select text and then select a tool, or select a tool and then
type. The tools are Heading 1, Heading 2, Heading 3, Bold, Italic, Strike
through, Inline code, Link, Bullet list, Ordered list, Task list, Block quote,
Table, Move item up and Move item down. Select a tool again to remove its
format. Hold the pointer on a tool to see its key.

You can also type `/` at the start of a line, or after a space, to open a
menu of the blocks of the row: the three headings, the three lists, Block
quote and Table. Type more letters to narrow the menu, for example `/bul` or
`/h2`. Press the Up and Down arrows to move in the menu, and Enter or Tab to
choose. Escape closes the menu and keeps the slash. You can also select a
block with the pointer. The block takes the line, and the slash and the
letters after it go. A slash inside a word, an address, code or a formula
opens no menu.

Table writes a small table with two columns and one empty row. Type the name of
the first column. Press Tab to go to the next cell, and Shift and Tab to go
back. Press Enter to go to the cell below, and Shift and Enter to go up. Tab in
the last cell and Enter in the last row add a row. You can also select a cell
to write in it.

A small handle of six dots shows on the left edge of the row and on the top
edge of the column that you point at, or that holds the cursor. Select it to
open the menu of that row or that column. The row or the column that the menu
acts on shows as selected. The row menu inserts a row above or below, moves the row up or down,
and deletes the row. The column menu inserts a column to the left or to the
right, moves the column, sets its alignment, and deletes it. The header row and
the last column stay. Both menus have **Delete table**, which removes the whole
table. Press Ctrl + Z to get it back. The command palette offers the same
actions while the cursor is in a table.

To add a row at the end, select the **+** bar under the table. To add a column
at the end, point at the table and select the **+** bar at its right edge.

To move a row or a column, drag its handle. A line shows where it goes. Release
the handle to move it there. Press Escape to stop the drag and move nothing.
The header row does not move.

Copy a row or a range of cells, from a note or from a spreadsheet, and paste it
into a cell: it fills the cells from there to the right and down, and the table
grows if it needs more rows or columns. Backspace and Delete remove text, and
never a cell, a row or a column. Tools that change whole lines, such as Heading
and Bullet list, do nothing in a table and show disabled. To go below a table
at the end of the note, press the Down arrow in its last row.

## Moving a list item

You can change the order of the items of a list, a task list included. An item
moves with its later lines and with the items under it. It stays in its own
list and at its own level.

With a mouse, point at an item. A grip shows to the left of it. Drag the grip,
and a line shows where the item goes. Release the grip to move the item there.
Press Escape to stop the drag and move nothing.

On every device, put the cursor in the item and select **Move item up** or
**Move item down** in the row of tools. On a keyboard, press Alt and the Up
arrow or the Down arrow. On a Mac, press Option and the arrow. Outside a list,
these keys move the line of the cursor.

A numbered list keeps its first number and counts on from it after each move.
Press Ctrl + Z or Cmd + Z to put the item back.

## Tools on a narrow screen and with a keyboard

On a phone, the row stands above the note, as on a computer. While you type,
the word count goes away to give the text more room. The slash menu and the
other menus open above the keyboard. Swipe the row sideways to
reach the other tools, or select the arrow at the end of the row that shows
when more tools are there. Every tool is also in the command palette: open it
with Ctrl + P or Cmd + P and type the name of the tool.

With a keyboard, press Tab to reach the row and the arrow keys to move
between the tools. Press Enter to use a tool. The cursor then goes back to the
note.

## Paragraphs and line breaks

A new line shows as a new line, in the editor, in Read mode, and on a
published page. The text does not move when your cursor goes into a paragraph
or out of it. Press Enter twice to start a new paragraph.

In a list, Enter starts a new item. Press Shift and Enter to start a new line
in the same item. In a quote, Shift and Enter keep the quote marks.

Press Enter on an empty item to end the list. The editor removes the empty
item and puts a blank line after the list, so the text that you type next is
a new paragraph in every Markdown tool. On an empty item inside another item,
Enter moves the item out by one level. Enter on an empty line of a quote ends
the quote in the same way.

Type three backticks or three tildes, with a language if you want one, and
press Enter. The editor writes the closing fence and puts your cursor on the
empty line between the two fences. A `$$` line and Enter do the same for a
formula. This also works above text that you wrote before: the text and any
block below it stay as they were. When you edit the first line of a fence that
you did not just type, and the fence has a closing fence below it or holds
code, Enter only starts a new line inside the block.

On a list line or a quoted line, Home goes to the start of the text after the
bullet, the box, the number or the quote mark. On a numbered line or a quoted
line, press Home again to go to the start of the line. Shift and Home select
the text first, and a second press adds the marker to the selection.

Other Markdown tools can join two lines of one paragraph into one line. Put a
blank line between the two lines if they must stay apart in those tools too.

## What the editor understands

CommonMark, plus the GitHub set: tables, task list items, strikethrough,
autolinks, and footnotes. Headings, lists at any depth, ordered lists, block
quotes, inline code, fenced code with a language, indented code, links,
reference links, images, thematic breaks, hard breaks, escapes, and entities
all work as CommonMark describes.

Code in a fence shows in colour, in the note and on a published page alike,
when the fence names one of these languages: JavaScript (`js`), TypeScript
(`ts`), JSON, CSS, HTML, Python (`py`), shell (`sh`, `bash`, `zsh`), SQL, Go,
Rust, YAML, Java, C, C++, C# (`cs`), PHP, XML, Dockerfile, Kotlin, Swift,
Ruby, TOML and Diff. Inside such a fence, Enter indents the next line the way
the language does, and Ctrl + / or Cmd + / turns the line into a comment of
that language. Code in another language shows as plain text.

Each code block shows the name of its language at the top, and a **Copy**
button at the other end. Select **Copy**, or press Tab to reach it and then
Enter, and the code of the block goes to the clipboard without the fences.
The button says **Copied** for a moment. A published page shows the same name
and the same button.

A task box is a real checkbox. Select it to tick the line. A table shows as a
grid of cells, and the note stores it as a GitHub table. A long cell wraps
onto more lines, so each column takes the width that its text needs. A table
that cannot fit even when its cells wrap scrolls sideways inside its own
outline, and the rest of the note stays where it is.

## Footnotes

Write `[^1]` after a word to add a footnote, and write the note on a line of
its own, for example `[^1]: The source of the quote.` The label can be a
number or a word. To write more than one paragraph in a note, indent the next
paragraph by four spaces.

The editor shows the label as a small raised mark, and shows the note in
smaller, quieter text. Put the cursor on a footnote to see its Markdown. A
published page shows a number for each footnote and puts the notes at the
end of the page. A label that no note defines stays as you wrote it.

## Ordered lists

An ordered list shows numbers, a list inside it shows the letters a, b, c,
and the next list inside shows the numerals i, ii, iii. Below that level the
three styles start again. The note keeps plain numbers in the source, so the
file reads the same in any other Markdown tool. You see the number of the
source while your cursor is on its line.

The editor keeps each list in sequence as you write. Enter, a paste, a
deletion, Tab, and Shift and Tab all put the numbers of the list back in
order, and one undo removes the change and the new numbers together. A list
keeps the number it starts at. Tab puts an item inside the item above it, and
a list that starts this way counts from one.

## Alerts

A block quote whose first line is `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`,
`[!WARNING]` or `[!CAUTION]` is an alert. The marker leaves the text and the
quote shows the word and a colour instead.

## Math

- Inline math is `$x^2$` or `\(x^2\)` on one line, or `$$x^2$$`, which can
  go on to the next line of its paragraph. A run of three dollars closes on
  a run of three.
- One dollar starts a formula only when a character that is not a space
  follows it. The closing dollar has a character that is not a space before
  it and no digit after it. So `It costs $5 and $10 today` stays text, as it
  does in GitHub, Obsidian and Pandoc.
- To write a dollar sign that must not start a formula, write `\$`.
- Display math is a `$$` line of its own, the formula, then a closing `$$`
  line.

A formula the renderer cannot draw stays as readable source rather than
failing.

## Diagrams and images

A code fence marked `mermaid` is drawn as a diagram, in the note and on a
published page.

An image from this note shows the picture. An image from another site shows the
picture as well, and the address must start with `https`. Opening the note
asks that site for the picture, so the site learns that somebody opened it. The
request names no note and no address of yours.

To add an image, paste it, drag the file onto the editor, or use **Attach
image** in the note menu. The editor uploads it and writes the Markdown for
you. Only images are accepted, and an upload needs a connection.

Click an image to open it at full size over the darkened page. To close it,
click outside the image, press Escape, or use the close button. Use the zoom buttons, the `+`, `-`
and `0` keys, or the mouse wheel with Ctrl or Cmd held to zoom. When you zoom
in, drag the image to move it. An image from this note has **Copy image** and
**Download**. An image from another site has **Copy link** and **Open
original**. To change the Markdown of an image, click next to the image or
move the cursor onto it with the arrow keys.

## HTML in a note

A note keeps a safe set of HTML, the set that GitHub keeps. For example,
`<kbd>Ctrl</kbd>` shows a key, `H<sub>2</sub>O` and `x<sup>2</sup>` show a
subscript and a superscript, `<mark>` marks text, `<br>` breaks a line, and
`<details>` with a `<summary>` folds a block on a published page.

The note shows a key, a subscript, a superscript, a mark and other text
elements as they look. It shows a block element such as `<details>`, and
`<br>`, as its HTML: the tags are quiet, and the words between them read as
the text of the note.

Other HTML loses its tags and keeps its words. A script, a style, a text
area and a few other tags show as the text you typed, so a tag that you do
not close never hides the rest of the note. A script, a style, an event and a
link or a picture written as HTML have no effect. Write a link or a
picture in Markdown instead. A link to anything other than a web address, a
mail address, another note, or an attachment loses its destination and is
shown as plain text.

## Limits

Some notes are too much Markdown to show formatted:

- a very large note,
- a note nested very deeply,
- a paragraph with very many formatting marks, such as a long run of nested
  links or emphasis,
- tables with very many cells.

Such a note is shown as source with one sentence that says why. The editor
shows it as plain text. A save of the note stops and tells you what to
change. For example, divide the paragraph, or move some rows of a table to
another note. Nothing is truncated and no text is lost.