Potential Markdown Data Loss When You Will Move Away from Obsidian

This report is extending my general be-careful-with-Markdown article because users of Obsidian in particular do seem to ignore warnings about potential conversion loss for their future tool switch when Obsidian does not meet their requirements any more or is not available any longer - as so many closed source tools did before.

This is a report generated by Claude.ai Opus 4.6 on [2026-04-08 Wed] for the prompt:

Please do generate a report on Markdown issues that will or may arise when a person moves away data from Obsidian.
In general, Markdown has many different flavors and tools like Obsidian or Obsidian add-ons introduce new syntax elements that are not understood by other tools such as pandoc.
In this example, I would suggest to convert Obsidian files to HTML that we do have a concrete target syntax example which is a valid choice for that experiment. Suggest a different format if you do have good arguments for a different target format.
Do differ between standard Obsidian Markdown syntax elements (the focus) and popular addons (to get likely issues when not just sticking to the default elements).
Add syntax examples for each case with the Markdown source (Markdown blocks) and the HTML result (HTML blocks) so that it is visible in what respect syntax information got lost or not handled properly as you would like to expect for a perfect data conversion.
Also add a list of dynamic Obsidian features that are not available outside of Obsidian automatically when you are re-using the Markdown files elsewhere such as node visualizations and such.
Bonus is when you can also come up with a list of Obsidian Markdown elements that are not part of the CommonMark syntax element list.

So if you do use Obsidian and find something here which is not accurate or changed over time, I would ask you to leave a comment so that I might fix that error. I did not check all those findings myself and LLMs like Claude may hallucinate here or there.

The LLM output follows now:

Obsidian stores notes as plain Markdown files --- but "plain" is misleading. Obsidian uses what it calls Obsidian Flavored Markdown, a combination of CommonMark, GitHub Flavored Markdown (GFM), and a set of proprietary syntax extensions. On top of that, the Obsidian plugin ecosystem introduces further non-standard syntax that only renders inside Obsidian itself.

This report documents the specific syntax elements that cause problems when you try to move your Obsidian vault to another tool or convert files to HTML (or another format). Each section provides the Obsidian Markdown source, the expected ideal HTML output, and the actual output you would typically get from a standard converter like pandoc.

HTML is a good test target because:

• It is a well-defined, standards-based format with no ambiguity.
• Pandoc (the most common Markdown-to-anything converter) supports it natively.
• It makes information loss immediately visible — you can see what rendered and what didn't.
• Most other target formats (PDF, DOCX, EPUB) go through an HTML-like intermediate step anyway.

That said, if your goal is long-term archival rather than conversion testing, HTML with embedded CSS or EPUB are both strong choices. If you want to stay in the Markdown ecosystem but on a more standardized footing, converting to strict CommonMark (stripping Obsidian extensions) is another valid path --- though you will lose features.

These are features built into Obsidian core --- no plugins required.

Obsidian's signature feature. Wikilinks use double-bracket syntax to link notes by name, without requiring a file path or extension.

Markdown source:

See [[My Other Note]] for details.
Link with alias: [[My Other Note|click here]]
Link to heading: [[My Other Note#Section Two]]
Link to block: [[My Other Note#^abc123]]	  

Expected ideal HTML:

<p>See <a href="My Other Note.html">My Other Note</a> for details.</p>
<p>Link with alias: <a href="My Other Note.html">click here</a></p>
<p>Link to heading: <a href="My Other Note.html#section-two">Section Two</a></p>
<p>Link to block: <a href="My Other Note.html#abc123">abc123</a></p>	  

Actual pandoc output (default settings):

<p>See [[My Other Note]] for details.</p>
<p>Link with alias: [[My Other Note|click here]]</p>
<p>Link to heading: [[My Other Note#Section Two]]</p>
<p>Link to block: [[My Other Note#^abc123]]</p>	  

What went wrong: Pandoc does not recognize wikilinks by default. The double brackets appear as literal text. Pandoc 3.0+ added wikilinks_title_after_pipe and wikilinks_title_before_pipe extensions, but they still do not handle image wikilinks, block references (^id), or vault-relative path resolution.

Obsidian can embed the content of another note, a section of a note, or media files inline.

Markdown source:

![[Meeting Notes]]
![[Meeting Notes#Decisions]]
![[Meeting Notes#^block-ref]]
![[photo.png]]
![[photo.png|300]]
![[document.pdf]]
![[recording.mp3]]	  

Expected ideal HTML:

<!-- Full note embed: inline the content of Meeting Notes -->
<div class="embed">
  <p>Content of Meeting Notes would appear here...</p>
</div>

<!-- Section embed: inline only the "Decisions" section -->
<div class="embed">
  <h2>Decisions</h2>
  <p>Decision content here...</p>
</div>

<!-- Block embed: inline a specific paragraph -->
<div class="embed">
  <p>The specific referenced paragraph...</p>
</div>

<!-- Image with width constraint -->
<img src="photo.png" alt="photo" />
<img src="photo.png" alt="photo" width="300" />

<!-- PDF and audio embeds -->
<embed src="document.pdf" type="application/pdf" />
<audio controls src="recording.mp3"></audio>	  

Actual pandoc output:

<p>![[Meeting Notes]]</p>
<p>![[Meeting Notes#Decisions]]</p>
<p>![[Meeting Notes#^block-ref]]</p>
<p>![[photo.png]]</p>
<p>![[photo.png|300]]</p>
<p>![[document.pdf]]</p>
<p>![[recording.mp3]]</p>	  

What went wrong: Pandoc treats all embeds syntax elements as literal text. Note transclusion is an inherently dynamic, Obsidian-specific feature --- no static converter resolves it. Image embeds with the wikilink syntax and the |width size hint are also not recognized. Even with pandoc's wikilink extensions enabled, image wikilinks remain unprocessed.

Obsidian allows you to assign an ID to any paragraph or list item, then link or embed that specific block from elsewhere.

Markdown source:

This is an important conclusion. ^my-conclusion

- Item A
- Item B
- Item C
^my-list

Link to the block: [[Note#^my-conclusion]]	  

Expected ideal HTML:

<p id="my-conclusion">This is an important conclusion.</p>

<ul>
  <li>Item A</li>
  <li>Item B</li>
  <li>Item C</li>
</ul>
<!-- list should get id="my-list" -->

<p>Link to the block: <a href="Note.html#my-conclusion">my-conclusion</a></p>	  

Actual pandoc output:

<p>This is an important conclusion. ^my-conclusion</p>

<ul>
<li>Item A</li>
<li>Item B</li>
<li>Item C</li>
</ul>
<p>^my-list</p>

<p>Link to the block: [[Note#^my-conclusion]]</p>	  

What went wrong: The ^block-id markers are rendered as literal text. They are not converted to HTML id attributes. The linking syntax also fails because wikilinks are not recognized.

Obsidian extends blockquote syntax with a type marker to create styled callout boxes.

Markdown source:

> [!warning] Be careful
> This action cannot be undone.

> [!tip]+ Expand me
> This is expanded by default.

> [!faq]- Collapsed section
> Hidden until the user clicks.

> [!note]
> A plain note callout without custom title.	  

Expected ideal HTML:

<div class="callout callout-warning">
  <div class="callout-title">Be careful</div>
  <div class="callout-content">
    <p>This action cannot be undone.</p>
  </div>
</div>

<details open class="callout callout-tip">
  <summary>Expand me</summary>
  <div class="callout-content">
    <p>This is expanded by default.</p>
  </div>
</details>

<details class="callout callout-faq">
  <summary>Collapsed section</summary>
  <div class="callout-content">
    <p>Hidden until the user clicks.</p>
  </div>
</details>

<div class="callout callout-note">
  <div class="callout-title">Note</div>
  <div class="callout-content">
    <p>A plain note callout without custom title.</p>
  </div>
</div>	  

Actual pandoc output:

<blockquote>
<p>[!warning] Be careful
This action cannot be undone.</p>
</blockquote>

<blockquote>
<p>[!tip]+ Expand me
This is expanded by default.</p>
</blockquote>

<blockquote>
<p>[!faq]- Collapsed section
Hidden until the user clicks.</p>
</blockquote>

<blockquote>
<p>[!note]
A plain note callout without custom title.</p>
</blockquote>	  

What went wrong: Pandoc renders these as ordinary blockquotes. The [!type] marker, the custom title, and the collapsible modifiers all appear as literal text inside the quote. The semantic meaning (warning vs. tip vs. note), the visual styling, and the interactive collapse/expand behavior are entirely lost.

Obsidian supports ==text== for highlighted (marked) text.

Markdown source:

This is ==highlighted text== in a sentence.	  

Expected ideal HTML:

<p>This is <mark>highlighted text</mark> in a sentence.</p>	  

Actual pandoc output (default Markdown reader):

<p>This is ==highlighted text== in a sentence.</p>	  

Workaround: Pandoc's markdown+mark extension does support this, but it must be explicitly enabled: pandoc -f markdown+mark. Without it, the ==== delimiters appear literally.

Obsidian uses %% to delimit comments that are invisible in reading/preview mode but present in the source.

Markdown source:

Visible text.

%% This is a private comment that should not appear in output. %%

More visible text.

Inline comment: some text %% hidden note %% continues here.	  

Expected ideal HTML:

<p>Visible text.</p>
<!-- Comment stripped or converted to HTML comment -->
<p>More visible text.</p>
<p>Inline comment: some text continues here.</p>	  

Actual pandoc output:

<p>Visible text.</p>
<p>%% This is a private comment that should not appear in output. %%</p>
<p>More visible text.</p>
<p>Inline comment: some text %% hidden note %% continues here.</p>	  

What went wrong: The %% comment syntax is completely Obsidian-specific. Pandoc and every other Markdown processor treats %% as literal text, exposing your private annotations in the output.

Obsidian uses YAML frontmatter for metadata (title, tags, aliases, dates, custom fields). This is also used by other tools, so support varies.

Markdown source:

---
title: Project Status
tags:
  - project
  - quarterly
aliases:
  - Q3 Status
  - Project Update
cssclasses:
  - wide-page
date: 2025-06-15
---

# Project Status
Content begins here.	  

Expected ideal HTML:

<!-- Frontmatter consumed as metadata, not displayed -->
<h1>Project Status</h1>
<p>Content begins here.</p>	  

Actual pandoc output:

<h1>Project Status</h1>
<p>Content begins here.</p>	  

Status: Pandoc handles standard YAML frontmatter well --- it strips it from output and can use fields like title and date. However, Obsidian-specific fields like aliases, cssclasses, and nested tag structures have no meaning outside Obsidian and are silently discarded. This is not a rendering failure, but it is metadata loss --- your aliases and custom properties vanish.

Obsidian supports inline tags with # and nested tags with /.

Markdown source:

This note is about #machine-learning and specifically #ml/transformers.

Nested tags like #project/alpha/phase-2 are common.	  

Expected ideal HTML:

<p>This note is about <a href="#" class="tag">#machine-learning</a> and
specifically <a href="#" class="tag">#ml/transformers</a>.</p>

<p>Nested tags like <a href="#" class="tag">#project/alpha/phase-2</a> are common.</p>	  

Actual pandoc output:

<p>This note is about #machine-learning and specifically #ml/transformers.</p>
<p>Nested tags like #project/alpha/phase-2 are common.</p>	  

What went wrong: Inline tags survive as plain text (which is acceptable for readability), but their semantic meaning as navigable, filterable tags is entirely lost. The hierarchical tag structure (ml/transformers as a child of ml) has no equivalent in HTML.

Obsidian supports inline and block LaTeX math via $...$ and $$...$$, using MathJax/KaTeX.

Markdown source:

Inline math: $E = mc^2$

Block math:

$$
\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$	  

Expected ideal HTML (with MathJax):

<p>Inline math: <span class="math inline">\(E = mc^2\)</span></p>
<p class="math display">\[\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}\]</p>	  

Actual pandoc output:

<p>Inline math: <span class="math inline"><em>E</em> = <em>m</em><em>c</em><sup>2</sup></span></p>	  

Status: Pandoc handles math reasonably well with --mathjax or --katex flags. Without those flags, it attempts to render math as plain HTML, which works for simple expressions but breaks for complex LaTeX. The key issue is that you must explicitly configure your converter for math support --- it is not automatic.

Obsidian renders Mermaid diagram code blocks natively.

Markdown source:

```mermaid
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
```	  

Expected ideal HTML:

<div class="mermaid">
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
</div>
<!-- Plus a <script> tag loading mermaid.js to render it client-side -->	  

Actual pandoc output:

<pre class="mermaid"><code>graph LR
    A[Start] --&gt; B{Decision}
    B --&gt;|Yes| C[Action]
    B --&gt;|No| D[End]</code></pre>	  

What went wrong: Pandoc outputs the Mermaid code as a regular code block. Without a post-processing step that adds the Mermaid JavaScript library and changes the tag structure, you get raw diagram source code instead of a rendered diagram.

Obsidian supports standard footnote syntax --- this is actually well-supported.

Markdown source:

This claim needs a source[^1].

[^1]: Smith, J. (2024). *Important Research*. Journal of Examples.	  

Expected ideal HTML:

<p>This claim needs a source<a href="#fn1" id="fnref1"><sup>1</sup></a>.</p>
<section class="footnotes">
  <ol>
    <li id="fn1"><p>Smith, J. (2024). <em>Important Research</em>.
    Journal of Examples.<a href="#fnref1">↩︎</a></p></li>
  </ol>
</section>	  

Actual pandoc output:

Pandoc handles footnotes correctly. This is one area where conversion works well.

Obsidian extends standard Markdown image syntax with a pipe-based size hint.

Markdown source:

![Alt text|300](image.png)
![Alt text|640x480](image.png)	  

Expected ideal HTML:

<img src="image.png" alt="Alt text" width="300" />
<img src="image.png" alt="Alt text" width="640" height="480" />	  

Actual pandoc output:

<figure>
<img src="image.png" alt="Alt text|300" />
<figcaption>Alt text|300</figcaption>
</figure>	  

What went wrong: Pandoc interprets |300 as part of the alt text. The image renders at its original size, and the alt text and caption include the raw size value.

These syntax elements are introduced by widely-used community plugins.

Dataview is the most popular Obsidian plugin. It treats your vault as a queryable database.

Markdown source:

```dataview
TABLE file.ctime AS "Created", file.tags AS "Tags"
FROM #project
SORT file.ctime DESC
```

```dataviewjs
dv.table(["Name", "Status"],
  dv.pages("#task")
    .map(p => [p.file.link, p.status])
)
```

Inline query: `= this.file.name`	  

Expected ideal HTML:

<!-- Ideally a rendered table of query results -->
<table>
  <tr><th>File</th><th>Created</th><th>Tags</th></tr>
  <tr><td>Note A</td><td>2025-01-15</td><td>#project</td></tr>
  <!-- etc. -->
</table>	  

Actual pandoc output:

<pre><code>TABLE file.ctime AS &quot;Created&quot;, file.tags AS &quot;Tags&quot;
FROM #project
SORT file.ctime DESC</code></pre>

<pre><code>dv.table([&quot;Name&quot;, &quot;Status&quot;],
  dv.pages(&quot;#task&quot;)
    .map(p =&gt; [p.file.link, p.status])
)</code></pre>

<p>Inline query: <code>= this.file.name</code></p>	  

What went wrong: Dataview queries are dynamic --- they execute at render time inside Obsidian and produce results from your vault's metadata. Outside Obsidian, they are just inert code blocks. There is no way to convert these statically without first running the queries inside Obsidian and serializing the results to Markdown (the Dataview Serializer plugin does this).

The Templater plugin adds a template language with <% ... %> delimiters.

Markdown source:

Created: <% tp.date.now("YYYY-MM-DD") %>
Author: <% tp.file.title %>
Previous: <% tp.date.now("YYYY-MM-DD", -1) %>

<%* if (tp.file.tags.includes("#meeting")) { %>
## Attendees
<%* } %>	  

Expected ideal HTML:

<p>Created: 2025-06-15</p>
<p>Author: My Note Title</p>
<p>Previous: 2025-06-14</p>

<h2>Attendees</h2>	  

Actual pandoc output:

<p>Created: &lt;% tp.date.now(&quot;YYYY-MM-DD&quot;) %&gt;</p>
<p>Author: &lt;% tp.file.title %&gt;</p>
<p>Previous: &lt;% tp.date.now(&quot;YYYY-MM-DD&quot;, -1) %&gt;</p>
<p>&lt;%* if (tp.file.tags.includes(&quot;#meeting&quot;)) { %&gt;</p>
<h2>Attendees</h2>
<p>&lt;%* } %&gt;</p>	  

What went wrong: Templater expressions are escaped as literal text. If you export a note /before/ Templater has processed it (e.g., a template file rather than a rendered note), the raw template syntax appears in the output. If Templater already ran and replaced the expressions with values, there is no issue --- the note contains plain Markdown.

The Tasks plugin extends standard checkbox syntax with dates, priorities, and recurrence.

Markdown source:

- [ ] Review PR #42 📅 2025-06-20 ⏫
- [x] Deploy hotfix ✅ 2025-06-14 📅 2025-06-15
- [ ] Weekly standup 🔁 every Monday 📅 2025-06-17
- [ ] Write documentation ⏳ 2025-06-18 ➕ 2025-06-10	  

Expected ideal HTML:

<ul class="task-list">
  <li><input type="checkbox" /> Review PR #42
    <span class="due-date">Due: 2025-06-20</span>
    <span class="priority high">High Priority</span></li>
  <li><input type="checkbox" checked /> Deploy hotfix
    <span class="done-date">Done: 2025-06-14</span>
    <span class="due-date">Due: 2025-06-15</span></li>
  <!-- etc. -->
</ul>	  

Actual pandoc output:

<ul class="task-list">
<li><input type="checkbox" disabled="" />Review PR #42 📅 2025-06-20 ⏫</li>
<li><input type="checkbox" checked="" disabled="" />Deploy hotfix ✅ 2025-06-14 📅 2025-06-15</li>
<li><input type="checkbox" disabled="" />Weekly standup 🔁 every Monday 📅 2025-06-17</li>
<li><input type="checkbox" disabled="" />Write documentation ⏳ 2025-06-18 ➕ 2025-06-10</li>
</ul>	  

What went wrong: The checkboxes render correctly (GFM task lists are well-supported), but the emoji-based date markers, priority symbols, and recurrence rules appear as literal emoji characters. Their semantic meaning --- due dates, scheduling, priority levels --- is lost. The tasks are no longer queryable or filterable.

The Kanban plugin stores board data as a specially structured Markdown file.

Markdown source:

---
kanban-plugin: basic
---

## To Do

- [ ] Design mockups
- [ ] Write user stories

## In Progress

- [ ] API development

## Done

- [x] Requirements gathering	  

Expected ideal HTML:

<!-- A multi-column kanban layout -->
<div class="kanban-board">
  <div class="kanban-column">
    <h2>To Do</h2>
    <div class="kanban-card">Design mockups</div>
    <div class="kanban-card">Write user stories</div>
  </div>
  <!-- etc. -->
</div>	  

Actual pandoc output:

<h2>To Do</h2>
<ul class="task-list">
<li><input type="checkbox" disabled="" />Design mockups</li>
<li><input type="checkbox" disabled="" />Write user stories</li>
</ul>
<h2>In Progress</h2>
<ul class="task-list">
<li><input type="checkbox" disabled="" />API development</li>
</ul>
<!-- etc. -->	  

What went wrong: The content is there, which is good --- the headings and task items survive. But the visual kanban layout (multi-column board with drag-and-drop) is entirely lost. What you get is a flat list under headings. The kanban-plugin: basic frontmatter key is silently discarded.

The Excalidraw plugin stores drawings as .excalidraw.md files --- these are Markdown files with embedded JSON.

Markdown source (simplified):

---
excalidraw-plugin: parsed
---

# Drawing

%%
## Drawing
```json
{
  "type": "excalidraw",
  "elements": [
    {"type": "rectangle", "x": 10, "y": 10, "width": 200, "height": 100}
  ]
}	  

Expected ideal HTML:

<!-- An SVG or image rendering of the drawing -->
<img src="drawing.svg" alt="Excalidraw drawing" />	  

Actual pandoc output:

The file structure confuses most processors. You get a mix of literal %% markers, raw JSON, and broken formatting. The drawing is completely unrenderable.

Mitigation: Excalidraw can auto-export drawings as PNG or SVG files. If this setting was enabled, you can reference the exported images instead.

The Advanced Slides plugin uses --- as slide separators and adds speaker notes and other directives.

Markdown source:

# Presentation Title

---

## Slide Two

Content here.

note: These are speaker notes not visible to the audience.

---

<!-- .slide: data-background="#ff0000" -->

## Red Slide

With a colored background.	  

Expected ideal HTML:

<!-- A reveal.js presentation with separate slides -->
<section><h1>Presentation Title</h1></section>
<section><h2>Slide Two</h2><p>Content here.</p>
  <aside class="notes">These are speaker notes not visible to the audience.</aside>
</section>
<section data-background="#ff0000"><h2>Red Slide</h2>
  <p>With a colored background.</p>
</section>	  

Actual pandoc output:

<h1>Presentation Title</h1>
<hr />
<h2>Slide Two</h2>
<p>Content here.</p>
<p>note: These are speaker notes not visible to the audience.</p>
<hr />
<!-- .slide: data-background="#ff0000" -->
<h2>Red Slide</h2>
<p>With a colored background.</p>	  

What went wrong: The --- separators become <hr> elements. Speaker notes appear as regular paragraphs. The HTML comment directive for slide backgrounds passes through unchanged but has no effect without reveal.js.

These features are not just syntax elements --- they are runtime behaviors of the Obsidian application that have no equivalent in static files.

The following is a summary of syntax elements that Obsidian supports but that are not part of the CommonMark specification. Some come from GFM, some from other extensions, and some are Obsidian-only.

If you are planning to move away from Obsidian, here are practical steps to minimize data loss:

1. Audit your syntax usage. Search your vault for [[, ![[, > [!, %%, ^, ==, and dataview to find Obsidian-specific syntax.

2. Convert wikilinks before exporting. The Obsidian Link Converter plugin can batch-convert [[wikilinks]] to standard [text](file.md) Markdown links.

3. Serialize dynamic content. If you use Dataview, install the Dataview Serializer plugin to bake query results into the Markdown files before export.

4. Export Excalidraw as images. Enable Excalidraw's auto-export to SVG or PNG so you have static versions of your drawings.

5. Strip or convert comments. Do a find-and-replace for %%...%% blocks — either delete them or convert to HTML comments (<!-- ... -->).

6. Use pandoc with extensions. The command pandoc -f markdown+wikilinks_title_after_pipe+mark --mathjax covers wikilinks (partially), highlights, and math.

7. Process callouts with a filter. Use a pandoc Lua filter or a preprocessing script to convert > [!type] blocks to styled HTML <div> elements.

8. Accept some loss. Block references, transclusion, the graph view, backlinks, and tag navigation are inherently Obsidian features. There is no lossless conversion for these — document them and move on.

Report generated April 2026. Pandoc behavior references version 3.x. Obsidian syntax references are based on Obsidian 1.x with its default feature set.