Obsidian Vaults

Obsidian reads plain Markdown, so a default conversion 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.


acp2md page convert by-id 393325 --obsidian --inline-tags -o ~/vault/page.md

Drop the result into a vault and it behaves like a note written by hand.

What the preset sets

The preset sets	Equivalent flag	Without the preset
Panels as native callouts, expands as foldable callouts	`--panel-style=obsidian`	GitHub alerts, which do render in Obsidian, but with GitHub’s four types instead of Obsidian’s colour-accurate set — and expands stay HTML `<details>`
Heading anchors as percent-encoded heading text	(follows the panel style)	Slug anchors (`#my-heading`), which Obsidian does not resolve — the table of contents and cross-page section links silently go nowhere
Images as sidecar files	`--image-sidecars`	base64 data URIs, which Live Preview stops rendering — see Images

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


# Keep base64 images, but take the rest of the preset
acp2md page convert by-id 393325 --obsidian --image-sidecars=false -o page.md
 
# Keep emoji blockquotes instead of callouts
acp2md page convert by-id 393325 --obsidian --panel-style=emoji -o page.md

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 note. Rows with a flag need it; the rest need nothing.

Feature	Flag	Notes
Headings, bold, italic, strikethrough	see formatting marks	stripped by default — read that section
Lists and task lists	—	`- [ ]` / `- [x]`
Tables with column alignment	—	`:---:` / `---:`
Code blocks with language	—	fence sized to enclose embedded backticks
Mermaid diagrams	—	pass-through, rendered natively
Math	—	$…$ and `$$…$$` through MathJax
Blockquotes, rules, footnotes	—	`[^id]` definitions flushed to the end
Callouts	`--obsidian`	`[!success]` green, `[!danger]` red, expands foldable
Heading links and table of contents	`--obsidian`	anchors Obsidian resolves
Images	`--obsidian`	sidecar files — see Images
Properties	`--include-metadata`	title, tags, author, dates, source URL, space, status, version
Inline tags	`--inline-tags`	labels as `#tag` on a trailing line, on top of the `tags` property
Wikilinks	`--wikilinks`	internal inline cards as `[[Page Title]]`; needs `--ext-resolve-inline-card-titles`, which is on by default
Mentions	`--link-mentions`	`@name` linked to the Confluence people profile
Collapsed sections	—	`<details><summary>`; Obsidian renders inline HTML
Sub/superscript, underline, small	—	`<sub>` / `<sup>` / `<u>` / `<small>`
Comments	—	`<!-- … -->` is hidden, the same as Obsidian’s `%% … %%`

Graph view needs links between notes, which means more than one note. Converting a whole space with acs2md --rewrite-links turns internal Confluence URLs into relative paths, so the page tree becomes a linked note graph.

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 note and links it relatively:


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

Measured on one real page, converted both ways:

	base64	sidecars
Markdown size	1,440,451 B	12,100 B
Longest line	244,311 chars	379 chars

The output stays self-contained either way — the bytes are on disk, not behind a Confluence URL that needs credentials. What changes is line length.

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

Formatting marks are stripped by default

--exclude-marks defaults to true. A default conversion removes bold, italic, strikethrough, underline, sub/superscript, text and background colour, alignment, indentation and annotations. On one real page that produced zero bold runs where the source had 32.

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:


acp2md page convert by-id 393325 \
  --obsidian \
  --inline-tags \
  --exclude-marks=false \
  -o ~/vault/page.md

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 stay as Markdown links.
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

Symptom	Cause	Fix
Images show as `![alt](data:image/png;base64,…)` text	base64 lines are too long for Live Preview	`--image-sidecars`, or `--obsidian`
Table of contents links do not navigate	slug anchors, which Obsidian does not resolve	`--obsidian`
Panels render but the colours look wrong	GitHub’s four alert types	`--obsidian`
A multi-column layout shows raw `####` and `[text](url)`	HTML block, whose contents Obsidian does not parse as Markdown	`--obsidian` linearizes them
Everything is plain — no bold or italic	`--exclude-marks` defaults to `true`	`--exclude-marks=false`
The note is tens of megabytes	base64 images	`--image-sidecars`