Skip to content

Markdown and git — what is promised ​

Notesflow is block-core: a tree of identified blocks plus an append-only op log is canonical, Markdown is a projection, and git is an export target.

That decision creates an obligation. Most documents in the world are Markdown, and "we'll handle interop later" is exactly how interop gets lost — several well-known block editors intended good export and all shipped a snapshot instead. The gap is closed by constraints held from the first commit, not by effort applied afterwards.

The promises ​

  • Every block type has a Markdown story, decided when the type is defined. Adding one without deciding is a compile error, not an oversight to catch in review.
  • There is exactly one serialiser. Export, the clipboard and import all call the same code, and CI fails the build if a second one appears. Three implementations of "what does a quote look like" is three sets of edge cases.
  • T1 and T2 round-trip losslessly. T3 degrades to something a human can read, with the structured part in a sidecar comment. See fidelity tiers.
  • No identifier appears in any link target. Exported links are relative .md paths built from slugs — the single largest source of "my links broke" in comparable tools.
  • Properties are frontmatter-shaped: scalars and flat lists, nothing nested. That is what makes properties → YAML a total function rather than a best-effort one.

Each of those is enforced by a test or a build check rather than by intent.

What "seamless" will never mean ​

Stated up front, because an unstated limit is discovered at the worst possible moment.

Simultaneous editing of the same content in an external editor and in Notesflow. That is not on the roadmap and it is not a missing feature — it is a thing this design does not promise. Interop is reconcile-on-demand:

  • export writes files and marks what it wrote;
  • you edit them wherever you like;
  • merge-back reconciles them, as a three-way merge against that mark.

A mirror is deliberately one-way. Nothing in it reads the repository, so if you edit an exported file the next export overwrites it — documented behaviour rather than a bug. It mirrors; it does not synchronise.

T3 blocks always degrade on export. Named up front, that is an understood trade rather than a discovered defect.

Writing Markdown directly ​

Inside Notesflow, a page can also be written as Markdown rather than in the block editor. That changes how the page is edited, not what it is — it is still blocks, through the same one projection — and it uses Obsidian's syntax for references so the exported file means the same thing there. It is not a live bridge to a file on disk: the rungs below are still how files come in and go out.

The four rungs ​

What it doesCommand
L1Markdown and vaults come inImporting
L2The workspace goes out, once, as a git repositorypnpm export:git
L3The same, continuouslypnpm mirror:git
L4Externally edited files come backpnpm merge:git

Blocks and the op log are canonical. Markdown is a projection. Git is a target.