Obsidian Vaults

Obsidian reads plain Markdown, so a default export already opens in a vault. Three constructs resolve differently there than on GitHub — panels, heading anchors and images — and --obsidian switches all three at once.

acs2md space convert by-key DEVOPS --output-dir ~/vault --obsidian --inline-tags

Point a vault at ~/vault and the export behaves like notes written by hand.

What the preset sets

It is a preset, not a lock: an explicit flag always wins.

# Keep base64 images, but take the rest of the preset
acs2md space convert by-key DEVOPS --output-dir ~/vault --obsidian --image-sidecars=false
 
# Keep emoji blockquotes instead of callouts
acs2md space convert by-key DEVOPS --output-dir ~/vault --obsidian --panel-style=emoji

The preset also linearizes Confluence’s multi-column layout sections into sequential Markdown rather than an HTML table. Obsidian does not parse Markdown inside a raw HTML block, so a column holding headings or links would otherwise display its Markdown source. The columns stack instead of sitting side by side — that is the trade for having them render at all.

What renders

Everything below is correct in the exported vault. Rows with a flag need it; the rest need nothing.

Images

This is the one that looks like a conversion bug rather than a setting.

By default images are embedded as base64 data URIs. That is valid Markdown and renders correctly on GitHub and in VS Code. But a data URI puts the entire image on one line — a routine Confluence screenshot is well over 100 KB of text — and Obsidian’s Live Preview stops applying decorations to lines past a length threshold. The image widget is never built, so the note displays the raw source instead of the picture:

![image-20240930-142031.png](data:image/png;base64,iVBORw0KGgoAAAANSUhEUg…)

--obsidian, or --image-sidecars on its own, writes each image to attachments/<page-id>/ beside the page and links it relatively:

![image-20240930-142031.png](attachments/5814878215/image-20240930-142031.png)

Measured on one real page, converted both ways:

The export stays self-contained either way — the bytes are on disk, not behind a Confluence URL that needs credentials. What changes is line length. Across a space it also deduplicates: a screenshot reused on ten pages is stored once rather than ten times.

Hrefs are percent-encoded, so an attachment whose name contains spaces or parentheses still produces a working link.

Formatting marks are stripped by default

That default suits RAG and search-indexing pipelines, which is what it was chosen for. For a vault people read, it is usually wrong. Links and inline code are always preserved either way.

For a reading vault:

acs2md space convert by-key DEVOPS --output-dir ~/vault \
  --obsidian \
  --inline-tags \
  --exclude-marks=false

What Obsidian does not get

Honest gaps, none of which break rendering:

• Note-to-note wikilinks beyond inline cards. [[Note]] is produced for internal inline cards via --wikilinks; ordinary links become relative Markdown paths with --rewrite-links instead. Both navigate, and both populate the graph.
• Embeds. ![[file]] transclusion is not emitted.
• Native highlight. ==text== is not produced. Confluence background colour renders as <span style>, which Obsidian shows as HTML.

Troubleshooting

See also

• Convert Spaces — every flag space convert accepts
• Sync and Incremental — keeping a vault up to date without re-converting everything
• Extensions & Macros — which Confluence macros survive the conversion