Images, tables, formulas and diagrams

Images

Getting one in — pick any of three:

• Drag it from Finder onto the page; it lands where you let go. Several at once is fine, one per line.
• Paste it with ⌘V after a screenshot.
• Insert it with ⌃⌘I, or “Image” in the “/” menu.

Once it's in — hover over the image and a handle appears at its lower right; drag it to change the width. The width is written into the document (the number in ![caption|420](img/photo.jpg)), so it is the same width on another machine. There is also a “View” button on the image, which opens it larger in a new tab.

On disk — the image is copied into an img/ folder beside the document, keeping its name (a nameless screenshot gets a name with a timestamp in it). Nothing is uploaded, re-hosted or renamed, so hand someone the whole folder and the images are still there.

Links and wiki links

An ordinary link: select some text, press ⌘K, and fill in the URL.

Pointing at another document in your library: write two square brackets, [[Document name]]. The name is the file's name, without .md. To show different words: [[Document name|the words shown]]; to jump to a section of it: [[Document name#Section heading]].

The value of writing it this way is in the other direction: the document you pointed at can see who mentioned it. Open the mentions panel (⌃⌘2) and that is the list, down to the line number. More on the library page.

Embedded images take the same form: ![[photo.png]], or with a width, ![[photo.png|300]].

Tables

Getting one in: ⌥⌘T, or “Table” in the “/” menu. You can also copy a block of cells from Excel, Numbers or a web page and paste it straight in as a laid-out Markdown table.

Editing: a table here is a real table. Type in the cells — no dialog, and not a read-only picture.

• ⇥ for the next cell, ⇧⇥ for the previous, ↵ for the same column one row down.
• Hover along the edge of the table and handles for the rows and columns appear: insert, move and delete are all there.
• Right-click has the full menu; the common ones also have keys: ⌘↩ inserts a row below, ⌥⌘→ a column to the right, ⇧⌘⌫ deletes the row, ⌥⌘⌫ the column.
• Column alignment: ⌥⌘L left, ⌥⌘E centre, ⌥⌘R right.

Code blocks

⌥⌘C starts a code block, as does “Code block” in the “/” menu — or just type three backticks. The language name sits at the top left of the block, and clicking it changes the language; the list that opens can be searched (type py for Python). Pick the right one and the colours line up.

For a fragment inside a sentence, use inline code, ⇧⌘`, which is a pair of backticks in the file.

Maths

Folding Mirror renders LaTeX with KaTeX. Inline formulas go between single dollar signs; display formulas go between a pair of $$ (⌥⌘B starts one).

One habit is worth knowing in advance: while the caret is still inside the pair, the formula stays as source and only renders once you move out. That way editing a formula isn't a fight with the renderer — otherwise it would reflow on every keystroke and nobody could work.

Mermaid diagrams

For flowcharts, sequence diagrams, Gantt charts and mind maps — the kind drawn from a syntax — there are two routes, each with its own use.

In the document (a fence)

Start a code block whose language is mermaid, and the diagram is drawn there:

Good for a small diagram that belongs to this passage alone. Editing the text is editing the diagram, and it travels with the document.

As a file (.mmd)

The insert diagram button in the toolbar (the branching shape) creates a .mmd file beside the document, embeds it at the caret, and opens a tab: source on the left, preview on the right, changing together as you type.

Good for a diagram cited by two documents, or one big enough to need a whole screen to tune. Double-clicking the .mmd in the sidebar opens it too.

Sketch canvases

The insert drawing button in the toolbar (the scribble) uses Excalidraw — hand-drawn boxes, arrows and quick labels. Clicking it creates an .excalidraw file beside the document and shows a preview of the drawing in the page.

• The drawing carries an “Edit” button; click it for the full canvas, and the preview updates as soon as you come back.
• The handle at the lower right changes its width in the document, same as an image.
• Right-click in the sidebar also offers “New drawing”, which makes it a standalone piece belonging to no document.

Where all of it is kept

None of it hides in a database. Take a document at essays/november.md:

Which is to say: a document and its pictures are a handful of files in one folder. Copy the folder to a USB stick, drop it in a cloud drive, put it in Git — it is complete either way.