docs / writing.md

Writing in markdown-kb

markdown-kb is a reading surface for notes kept as Markdown. The source stays exact. Preview is a view of that source.

Note

An edit is a draft in this browser. It stays on this machine. Reset, in the top bar, shows the repository copy again.

Measure

Prose sits in a column about sixty-six characters wide, with room between lines. On a narrow screen the line shortens instead of the type shrinking. Headings stay quiet. The outline on the right follows the page while there is room for it.

A useful line is long enough to hold a thought and short enough to find the next one.

Lists

What the preview renders:

  • Headings, emphasis, links, and images

  • Tables, task lists, and footnotes

  • Code, math, diagrams, and charts

  • Read the page before editing it

  • Press E to edit the page as blocks

Tables

PaneWhat it is for
FilesJump between pages
PreviewRead
EditingWrite in blocks
OutlineMove through the page

Callouts

Tip

Press ⌘K to jump to a page. Press E to edit the page as blocks, and ⌘/ to see its Markdown source. Preview is the view you start in.

Important

The Markdown file is the document. Preview is a view of it.

Warning

A local draft overrides the repository copy until you reset it.

Caution

A diagram or chart with a syntax error shows the message beside the block. The rest of the page still reads.

Code

export const reading = {
  measure: "66ch",
  lineHeight: 1.7,
  fontSize: 17,
};

Math

The reading measure stays near sixty-six characters.

42≤characters per line≤7542 \le \text{characters per line} \le 75

Diagrams

Charts

Charts are Vega-Lite specs in a chart fence. The numbers below are an example of the syntax.

A table from CSV

FilesJump between pages
PreviewRead
EditingWrite in blocks
OutlineMove through the page

See the Shortcuts for every key, or the Layout of the screen. The keyboard section is included below.

Drafts never leave the browser.1

Highlight marks a phrase you want to find again. Strikethrough marks something you replaced. Press ⌘ K from anywhere.

Why the source stays plain

A diff is easier to trust when the editor does not rewrite the file. Preview can be careful because the source is allowed to stay ordinary Markdown.

Footnotes

  1. Reset drops the draft and shows the file from the repository again. ↩