Article notes¶

An article is a long-form Bob vault note marked with type: "[[article]]". bob-cli owns article numbering, link repair, and layout. The Obsidian bob-articles plugin sends the current buffer to bob and applies bob's returned line edits as one undoable transaction. Formatting changes layout and heading numbers; it never changes prose.

Marker, options, and refusals¶

---
parent: "[[sase_blog]]"
type: "[[article]]"
created: 2026-10-15T15:10:41-04:00
title: "Why I built SASE" # optional publication title; defaults to file name
section_numbers: true     # optional; true by default
---

Only type: "[[article]]" enables formatting. title feeds the repeated-title finding and the list/outline labels. section_numbers accepts lowercase true or false; any other value produces a bad-option finding on that line and leaves numbering on. The plugin's .bob-article class is runtime-only and is never written to frontmatter.

Formatting skips the whole note in these cases; it never formats only part of a note.

Task lines, anchors, and conflict markers inside frontmatter, fenced code, math, comments, and HTML comments are ignored. A prose mention of #task is not a task.

Section numbering: N1–N9¶

The token grammar follows the house style: top-level 1., then 1.1, then 1.1.1. One known risk remains: an unescaped heading such as ## 1.5 million users looks like an owned number and will be rewritten. Adoption previews every replaced token, mismatched number depth produces number-replaced, a single u undoes a plugin format, and git retains the history.

Formatting: F1–F11¶

When a fence never closes, bob leaves the opening line and everything after it untouched and reports unclosed-fence.

Findings¶

Findings are reports, never automatic fixes. Each has code, severity, a 1-based line, message, and hint; bob owns all display strings.

bob never reflows paragraphs, title-cases headings, applies smart typography, aligns table pipes, normalizes emphasis/list/thematic-break markers, moves footnotes, adds block IDs, builds a table of contents, reorders sections, or edits frontmatter except for F1 and the type line added by adopt.

Heading identity and links¶

A heading identity removes one bob-owned number, collapses whitespace, and compares case-insensitively. bob compares both the raw title and a plain form with emphasis, inline-code, and wikilink markup stripped. In-note links, inbound links, and article capture selectors share this identity rule.

For each fragment segment, bob resolves in this order:

1. Match the fragment against a heading's pre-format text. This preserves the target Obsidian resolved before a change, including when two headings share a title.
2. If there is no exact match, match the single heading with the same identity. For a nested path such as #A#B, resolve each later segment inside the previous section's subtree.
3. If none match, report broken-heading-link; if several identity matches remain, report ambiguous-heading-link. bob does not guess.

The scanner covers [[#…]], [[note#…]], [[path/note#…]] when the target names the same note, embeds such as ![[note#…]], and Markdown links such as [x](#…) and [x](note.md#…). It changes only the leading number token in a fragment, preserves aliases and percent encoding, and removes owned tokens when numbering is off. Block links (#^id) are left alone. Links inside frontmatter, code, math, comments, and HTML blocks are not scanned.

Word invariant and idempotency¶

Before any write, bob compares the ordered non-whitespace tokens in the source and formatted output. It ignores heading markup, closing hashes, and one owned section number on section-heading lines; it drops Setext underline lines and removes owned number tokens from heading-link fragments. If the sequences differ, bob refuses the write with words-changed and identifies the first differing token in context. bob formats the result a second time; if that pass changes it, bob reports not-idempotent and writes nothing.

Write safety and vault scanning¶

format and adopt -w check each changed article's SHA-256 preimage before writing. A note changed after planning gets status error, reason code preimage-changed, and a message saying it was not written. Other changed articles in the batch still write; the command exits 2 if any note was skipped or errored. Human output and JSON use the post-write status, so a skipped write never appears as successful.

The article writes use an atomic temporary-file replacement. For inbound repair, bob writes changed article notes first (folding cross-article repairs into those writes), then scans and atomically writes other linking notes after checking each linker's preimage. A drifted inbound note is skipped with a reason; the article write stands. The drifted article's inbound rewrites are skipped. Non-UTF-8 Markdown files are treated as non-articles and non-linkers; other I/O errors fail the run. Excluded directories are not scanned.

Inbound repair runs on write when a heading changes. format -a also scans for stale links from earlier runs. The scan prefilters notes by case-insensitive article-stem substring, then resolves links against the vault. --dry-run shows inbound diffs; --stdin returns rewrites in the plan without writing.

CLI¶

A bare bob articles runs the read-only list command.

NOTE accepts an exact vault-relative Markdown path or a unique note stem. Ambiguous names list candidates; missing names list close stem matches where available. -b, --bob-dir PATH selects the vault, otherwise bob uses BOB_DIR or ~/bob.

format options: -a, --all; -b, --bob-dir PATH; -c, --check (write nothing, exit 1 if formatting is needed); -d, --dry-run (show a unified diff, write nothing); -f, --format human|json; -s, --stdin (read one named note from stdin, print its plan, and write nothing). --stdin cannot be combined with --all or --dry-run. adopt options are -b, -f, -s, and -w, --write; preview is the default. An already-adopted article is a successful no-op. Adoption preview includes a diff, Numbers replaced, findings, and a write hint.

Exit codes:

Human format output is silent when no work is needed. Changed notes get a summary line; warnings and info findings use distinct prefixes. --check prints which notes need formatting. The list header uses ~ for the home directory, and singular/plural wording follows the counts. Nightly runs the report-only format -a -c check after task archive; it marks the step passed unless bob exits 2 or higher.

JSON: ArticlePlan v1¶

format -f json and adopt -f json print the complete response, including when a note is skipped or errors:

{
  "schema_version": 1,
  "notes": [{
    "path": "sase_blog_contents.md",
    "status": "changed",
    "reason": null,
    "sha256": "<input text SHA-256>",
    "edits": [{ "line": 18, "delete": 1, "insert": ["# 1. The Abstractions", ""] }],
    "changes": {
      "numbered": 10, "renumbered": 0, "unnumbered": 0,
      "promoted": 2, "setext": 0, "links": 0, "layout": 9
    },
    "replaced": [{ "line": 30, "token": "3.", "number": "1.2" }],
    "notice": "Article formatted · 10 sections numbered",
    "findings": [],
    "outline": { "title": "sase_blog_contents", "numbering": true, "words": 253,
      "preamble": {}, "sections": [] },
    "inbound": []
  }],
  "summary": { "articles": 1, "changed": 1, "unchanged": 0, "skipped": 0, "errors": 0 }
}

Statuses are changed, unchanged, skipped, and error. reason is null or has a code and message. changes.numbered counts headings with no written token that get a number; renumbered counts written tokens that change. formatted is intentionally omitted: clients apply edits. The contract only grows; clients must reject an unknown schema_version and must not compute numbers or display strings themselves.

list -f json uses the same response and removes each note's edits. outline -f json prints the outline object. In an outline, line/end_line refer to input lines, output_line refers to formatted text, title is de-numbered, written is the source token or null, number is bob's result or null when numbering is off, stale means the source differs, and stub means the section body is empty or contains only TODO/TBD markers. replaced lists every owned number removed or replaced. In format --stdin, inbound entries contain {path, line, sha256, before, after} for the linking note.

Plugin behavior¶

The plugin never parses article grammar or computes numbers. On save, when leaving a note, or through Bob: Format article, it sends the buffer to bob and applies the returned edits in one CodeMirror transaction. It checks the buffer and inbound line preimages before writes and suppresses reformatting after an undo until fresh input. The Bob: Convert note to article… command shows bob's adoption preview and refusal. Reading and Live Preview decorate written numbers from bob's outline; stale-number tooltips avoid promising an on-save change while the undo guard blocks saves.

The plugin applies the .bob-article reading look, line numbers, and responsive hanging section numbers from bob's outline. Refreshing an outline rerenders open Reading views once. It shows at most one quiet missing/old-bob or timeout notice per session, and save-path refusals at most once per note per session.