Outline documents

An outline document is a text buffer read as blocks: paragraphs, bullets, numbered items and tasks, nested by indentation. It has its own editing rules (Enter continues a list, Tab nests, Ctrl-T cycles a task, Alt-↑/Alt-↓ move an item with its children) and gives every block a stable identity, so a host can keep its own data per block (a database row, a due date) while the text is edited, undone and redone.

The outline layer lives in src/outline and is on when state.doc.outline is set. Without it the document is plain text and nothing here applies.

$ caretline --outline crates/caretline-app/fixtures/trip.md

The buffer

The text is still one rope, and one text line is one row:

text                               marks          blank row   block
───────────────────────────────    ───────────    ─────────   ───────────────────────────
Booked the flat in Lisbon.         0 @ line 0                 0  paragraph, depth 0
It faces the river.                                              (continuation)
- [ ] Pay the deposit              1 @ line 2     yes          1  task ' ', depth 0
  - ask Ana about her desk         2 @ line 3                  2  bullet, depth 1
![boiler label](files/x.png)       3 @ line 4     yes          3  paragraph, atomic

• A block’s first line is indent marker content. indent is OutlineConfig::indent spaces (2) per depth. The marker is - (also * , + ) for a bullet, - [c] for a task (c from the task vocabulary), 12. or 12) for a numbered item, or nothing for a paragraph. A paragraph’s first line may start with a heading (# , ## , ### ), a quote (> ) or a code fence (three backticks).
• Every other line continues the block above it (a soft break). A continuation line holds plain content, without indentation.
• Paragraphs nest like items. A nested paragraph’s first line is its indentation and its content ( first subtask is a paragraph at depth 1); Enter in it starts paragraphs at the same depth, and its children move with it (move_block).
• Block starts are the first line, every line with a mark, and every line outside a fence that starts with a marker (after optional indentation). A start without a mark gets one in the same update, so typing - at the start of a continuation line makes that line a new item. From an opening fence line to its closing one, no marker starts a block.
• Identity is the mark on a block’s first line (MarkId). Marks follow their lines through every edit, undo and redo, and a cut and paste keeps them.
• The blank row before a block is an attribute of its mark (BlockAttrs::gap), never a text line. The view draws it as a virtual row: the caret never stops on it, ↑/↓ step over it, and a click on it lands at the block’s content start.

Everything about a block is derived from the text, the marks and the config, by outline::derive, and remembered until they change (state.blocks()):

Blank rows

Unset, a block’s blank row follows its kind and the block before it: a paragraph has one before and after it (a ## or ### heading only before), list items are tight, and the first block has none. gap: Some(true) or Some(false) overrides that.

A kind or depth change never moves another block. When the task cycle, Tab or Shift-Tab changes a block, every other block keeps the blank row it had. When typing, Backspace or Delete changes the kind or depth of the caret’s block, that block and the one after it keep theirs. Where the default would now differ, the old value is written to the block’s attributes, in the same undo step. Other edits (Enter, joins, moves, paste) let blocks take their defaults.

The caret

No selection end is ever inside a marker, and no caret is ever inside an atomic block. After every message the update loop moves an end that landed there:

• Backward motion by character or word goes to the end of the line before (so ← from a content start goes to the previous block’s end in one press).
• Everything else goes to the content start (Home, a click on a marker, ↑/↓).
• A caret on an atomic block (an image) selects the whole block: arriving takes one press from any side, and so does leaving. A selection made with Shift takes the block whole.

The rules

Each rule is one Transaction and one undo step. The mark column says what happens to ids.

Effects

Markdown in and out

outline::markdown reads and writes Markdown:

• parse_markdown(text, plain) reads pasted Markdown into NewBlocks (paragraph lines joined, list items and paragraphs nested by their first indent, - [ ] and bare [ ] tasks, headings, quotes and rules as one-line paragraphs, fences, tables and front matter as one paragraph with its line breaks).
• to_markdown(state, outline, from, to) writes a selection for the clipboard.
• load(md, path, viewport, config) opens a Markdown file as an outline document, and to_file(state) writes one back (save uses it). In a file, a blank line between blocks is a blank row, a continuation line is indented under its item, and a line break inside a paragraph is a soft break.

A file round-trips exactly when it is written the way to_file writes it. Three things don’t survive a file: an empty paragraph (a fresh line to type on) is left out, an empty continuation line reads back as a blank row (splitting the block), and two paragraphs with no blank row between them read back as one.

In Rust

use caretline::outline::markdown;
use caretline::{update, Effect, MarkId, Msg, OutlineConfig, Viewport};

let mut s = markdown::load("- [ ] Pay rent\n- Buy milk\n", None, Viewport { width: 40, height: 6 }, OutlineConfig::default());
let fx = update(&mut s, Msg::TaskCycle);                  // the caret is on "Pay rent"
assert!(fx.contains(&Effect::Completed { id: MarkId(0) }));
assert_eq!(markdown::to_file(&s), "- [x] Pay rent\n- Buy milk\n");

let blocks = s.blocks().unwrap();                          // derived, cached
assert_eq!(blocks.blocks[1].depth, 0);

Keys

The outline keymap is the plain one (see messages.md) with these on top:

Try it

caretline --outline FILE edits a Markdown file as an outline. The fixtures include trip.md and three saved outline states:

$ caretline --outline crates/caretline-app/fixtures/trip.md --keys '<down><down><down><c-t>' --snapshot 50x18
$ caretline --outline crates/caretline-app/fixtures/trip.md --keys '<down><down><down><down><end><cr>Call Ana<tab>' --snapshot 50x18
$ caretline --state crates/caretline-app/fixtures/outline-split.state.json --snapshot 40x10
$ caretline --outline crates/caretline-app/fixtures/trip.md --keys '<d-down>!<c-s>' --effects

Without a layout the view draws each block’s text as it is, markers included, with blank rows as virtual rows. --layout adds the outline layout (below), with plain hang glyphs:

$ caretline --layout crates/caretline-app/fixtures/trip.md --snapshot 50x16 --no-status-bar
  #   Lisbon trip

      Booked the flat in Lisbon.
      It faces the river.

  [ ] Pay the deposit
      •   ask Ana about her desk
  [ ] Book flights
  [x] Renew passport

      ![boiler label](files/boiler.png)

  1.  Pack
  2.  Leave

The outline layout

A view’s layout (an OutlineLayout) lays an outline document out line by line, with the column geometry as data:

For each line:

• A block’s first line skips its prefix (indentation and marker): the marker moves out of the text into the hang. Its content starts at x = marks + depth·indent + hang and wraps at max(min_column, column − depth·indent), never past the view’s right edge. In a view too narrow for that, deep blocks stop indenting where their content would get fewer than min_column columns.
• Continuation lines use the same column and width.
• Content wraps as prose: between words at whitespace only, a word moving to the next row whole unless it’s longer than a row (then it breaks at the row’s end). When there’s a cell right of the column, a word may fill the row exactly: the space after it stays on that row (past the column, unseen), and the next row starts with the next word, so a row never starts with a space. The caret after such a word sits in that cell. (A plain document keeps Helix’s wrapping.)
• A fence doesn’t wrap. A long line in it scrolls sideways on its own while the caret is on it; the other lines stay put.
• A gapped block has a blank row before it; extra_rows add rows after it. Neither is ever a caret stop: ↑/↓ step over them keeping the goal column, and a click on them lands at the block’s text.
• A folded block’s children take no rows (see Folds).

The goal column of ↑/↓ is a screen column, so moving between depths goes straight down. Motion, paging, scrolling, clicks and drawing use the same rows, through one Layout.

The engine draws only text: the marks column and the indentation are blank, and the hang’s cells have the role Hang (blank unless hang_glyphs). A host draws its own hang, marks and fields from the frame’s row info:

use caretline::outline::markdown;
use caretline::view::{hit, Hit, RowInfo};
use caretline::{view, OutlineConfig, OutlineLayout, Viewport};

let mut s = markdown::load("- [ ] Pay rent\n- Buy milk\n", None, Viewport { width: 40, height: 4 }, OutlineConfig::default());
s.view.layout = Some(OutlineLayout::default());
let f = view(&s);
assert!(matches!(f.rows[0], RowInfo::Text { first: true, x: 6, .. }));
assert_eq!(hit(&s.doc, &s.view, 3, 0), Hit::Hang { block: s.doc.marks.as_slice()[0].id });

Folds

fold, unfold and toggle_fold (by block id) hide or show a block’s children in one view: folds are the view’s (view.folds), so another view of the same document still shows them. They work with or without a layout. Only a block with children folds.

• Hidden lines take no rows. ↓ from the folded block goes to the next visible one, and → at its end goes past the children.
• A caret inside the children when they fold, or one that an edit through another view leaves there, moves to the folded block’s end.
• A fold drops when its block goes. Folds are part of the view’s JSON ("folds":[3]).

Cost

Each edit re-derives the blocks once (linear in lines; a few hundred microseconds for 5,000 blocks in a release build) and maps the marks after the first change. The layout lays out only the rows it needs, so the outline layout costs no more than plain drawing, and a second view of the document is only rebased (its selection mapped), never laid out. The scale tests type in a 5,000-block outline, with and without the layout and with a second view open, and check that a key, rendered, stays under 4 ms in a release build (it is about 1 ms). Deriving only the lines an edit touched is the next step when that matters.

This page on GitHub: docs/caretline/outline.md