Writing notes

Notes are Markdown files. If you already write Markdown, everything works the way you expect, plus the extras below.

The editor

Three view modes:

Mode	Use when
Read	You just want the rendered note.
Edit	You want the full width to write in.
Split	You want to see both.

Changing a note creates an unsaved draft. Click Save, write a commit message, and the change goes into the notebook’s history. Drafts survive switching tabs, and Kyra asks before closing a tab with unsaved work.

Task checkboxes are clickable in the preview — ticking one updates the draft, and you still save to commit it.

Formatting

Standard Markdown plus GitHub extensions: headings, emphasis, block quotes, lists, rules, tables, strikethrough, and task lists.

- [ ] Not done
- [x] Done

Code

Add the language for syntax highlighting:

```python
def main():
    pass
```

Without a language you still get a code block, just unhighlighted.

Callouts

:::tip
Use these for the things future-you should not miss.
:::

Available: note, info, tip, warning, danger, caution.

Maths

Inline with single dollars, display with double:

The residual is $r = y - \hat{y}$.

$$
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq
\left( \sum_{k=1}^n a_k^2 \right)
\left( \sum_{k=1}^n b_k^2 \right)
$$

Diagrams

Mermaid renders in the notebook and on published pages:

```mermaid
flowchart LR
  Idea --> Draft --> Review --> Publish
```

Flowcharts, sequence, class, ER, Gantt, pie, mindmap, and timeline all work. Ask Kyra to write one — “draw me a flowchart of the release process” — and it will produce valid syntax rather than something you have to debug.

Citations

Put a references.yaml at the notebook root:

smith2023: "Smith, J. (2023). Useful Paper. Journal of Examples."

Then cite it:

The approach is well known [@smith2023].

Known keys become numbered footnotes. Unknown keys stay as literal text so you can see what still needs filling in.

Linking notes together

This is where a notebook stops being a folder and starts being useful.

See [[research/interviews/sarah]].
See [[research/interviews/sarah|Sarah's interview notes]].

Two ways to create one quickly:

Type [[ and search.
Type @ at a word boundary and search.

Both search titles first, then content once you have typed enough.

Links are two-way. A note shows what links to it, so you find the thing that referenced this decision without having remembered that it did.

Stable references

Reference in the toolbar copies a link that survives the file being moved:

[[file:notebook-id:path/to/note.md]]
[[file:path/to/note.md|A readable label]]

Transcripts use the same shape:

[[transcript:session-id|The call where we agreed this]]

Structured fields

A note can open with YAML frontmatter:

---
type: person
name: Ada Lovelace
status: active
tags: [history, computing]
---

# Ada Lovelace

The portal shows a frontmatter panel under the file tree. If type matches a schema in .schemas/*.yaml, you get proper typed controls — checkboxes, dates, dropdowns, lists — instead of raw YAML. Unknown fields stay editable as text.

Worth it when you keep a set of similar notes: people, companies, experiments, interviews, recipes.

Dictating into a note

With voice in the browser enabled, Kyra can write at your cursor while you keep your hands off the keyboard — “new heading, Launch blockers”, “bullet”, “scratch that”. See typing instead.

Letting Kyra edit

“Add a section about the pricing decision to the launch note.” “In the retro note, change the owner of the second action to Sam.”

Kyra edits the part you named and leaves the rest alone. Broad restructuring of a whole notebook asks for approval first, because that is the change that is hard to eyeball afterwards.