Translation Layer

This is where the project lives or dies

Every other component in cyberbaser is solvable with off-the-shelf parts. The translation layer is the hot spot. If we can’t guarantee round-trip fidelity for the Tier 1 features below, the “three contribution paths” vision collapses to “one path plus some lossy alternatives.”

What it does

A pipeline of remark (markdown AST) and rehype (HTML AST) plugins composed on top of Astro’s content loading. Takes an Obsidian-flavored markdown file as input, produces (a) rendered HTML for the web wiki and (b) enough preserved structure that a Web CMS edit round-trips cleanly back to the source file.

┌──────────────────────┐
│  Vault markdown      │   > [!note]+ Example
│  (Obsidian-flavored) │   > This is [[A Page|the target]].
└──────────┬───────────┘   > ![[diagram.png]]
           │
           ▼
┌──────────────────────┐
│  remark plugins      │   Parse → AST
│  - obsidian-callout  │   Transform:
│  - wiki-link         │     callouts → Aside nodes
│  - embed handler     │     wikilinks → resolved hrefs
│  - frontmatter       │     embeds → image nodes
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  rehype plugins      │   AST → HTML
│  - mermaid           │     fenced mermaid → inline SVG
│  - external-links    │     external <a> → target=_blank
└──────────┬───────────┘
           │
           ▼
    Rendered page

The tiered feature list

This is the contract. A feature’s tier determines its level of support and the amount of engineering it justifies.

Tier 1 — Full Support (round-trip required)

Tier 1Full support · round-trip required

These features must survive edits from any contribution path. If the Web CMS edits a page and the roundtripped file doesn’t equal the original (modulo intentional changes), the tier fails.

Feature	Source syntax	Plugin	Status
Wikilinks	Page, alias	remark-wiki-link	Scoped
Callouts	> [!note], > [!warning], > [!tip]+	remark-obsidian-callout	Scoped
Image embeds	![[image.png]]	Custom remark plugin	Pending
Note embeds	![[Other Note]], ![[Other#Section]]	Custom remark plugin	Pending
Code blocks	Fenced, language-tagged	Astro/Starlight built-in	OK
Math	$inline$ and $$block$$	remark-math + rehype-katex	Pending
Mermaid diagrams	Fenced mermaid blocks	rehype-mermaid	OK
Tables	Standard markdown tables	Built-in	OK

Tier 2 — Partial Support (best-effort, never lossy)

Tier 2Partial · best-effort

These features render something but may lose fidelity. Important constraint: a Tier 2 feature should never silently corrupt a round-trip. If we can’t preserve it fully, we render a best-effort fallback and leave the source markdown alone.

• Simple Dataview queries — LIST FROM #tag, basic TABLE. Rendered as a resolved list at build time; the query text is preserved as a comment for round-trip.
• Block references — Note#^blockid. Resolved to the target block’s content with an anchor; block ID preserved.
• Aliases (frontmatter aliases:) — rendered as redirect pages; original frontmatter untouched.
• Frontmatter metadata — exposed as page properties / status badges; original keys preserved.

Tier 3 — Not Supported (workaround documented)

Tier 3Not supported · document the workaround

These features cyberbaser will not translate. For each, we need a documented contributor-facing workaround — otherwise contributors will hit a silent failure mode.

• Complex Dataview JS — use Tier 2 simple queries or pre-compute a static table.
• Canvas files (.canvas) — export to SVG/PNG and embed via standard markdown image.
• Templater / DataviewJS plugins — render output to static markdown before commit.
• Graph view — inherently interactive; replaced by starlight-site-graph on the web.

Round-trip correctness — the test corpus

The single most important artifact

A test corpus where each Tier 1 / 2 feature has:

1. A fixture vault page written by hand
2. Expected web output (HTML snapshot)
3. A “Web CMS edit → vault diff” round-trip snapshot proving A → B → A === A

Until this exists, “round-trip editability” is an aspiration instead of a tested property. Building this corpus is on the critical path for Phase 1.

Open research questions

These live in Open Questions but collecting them here because they all touch the translation layer:

1. Is astro-loader-obsidian sufficient for Tier 1? Does it handle wikilinks, callouts, and embeds, or does it need augmentation? Unknown.
2. How does the Web CMS render Tier 2/3 features it can’t preview? Raw markdown? Rich editor with degraded modes? Hide behind a “view raw” toggle?
3. How do we enforce round-trip correctness at CI time? Property-based tests? Snapshot diffing? Is there a testing framework that models markdown round-trips well?
4. Where should backlinks data be computed? Inside the content loader as part of the AST, or as a post-build rehype pass over the full page set?
5. What’s the incremental build story? A 1000-page vault with a one-page edit shouldn’t trigger a full rebuild. Astro 5+ has improved incremental support but this needs benchmarking on a realistic vault.