Obsidian Integration Troubleshooting

By Amr

Common issues with the Obsidian + Jekyll integration and how to fix them.

Estimated reading time: 3 minutes

• Share on Reddit
• Share on LinkedIn
• Share on Twitter

• ---

• Page Improvements

• Improve Page Polish content, structure, and presentation of this page
• Expand Page Add depth, examples, and missing sections to this page
• Update Page Refresh outdated content, versions, links, and screenshots
• Fix Page Issue Report a typo, broken link, layout glitch, or content bug
• SEO Optimize Improve discoverability, metadata, and structured data
• Accessibility Audit Audit this page for WCAG 2.1 AA compliance

• ---

• Site Improvements

• UI/UX Improvement Propose a design or UX refinement for the theme
• New Feature Propose a new site-wide feature or capability
• Component Enhancement Improve a Jekyll layout, include, or shared component
• Performance Optimization Improve load time, Core Web Vitals, and asset delivery

Edit on GitHub

Table of Contents

Obsidian Integration Troubleshooting

A wiki-link renders as broken (wiki-link-broken) on the site, but works in Obsidian

Cause: the target page has no title: in its frontmatter and the basename doesn’t match either, or the wiki-index hasn’t been regenerated since the target was added.

Fix:

1. Confirm the target file has title: set in YAML frontmatter.
2. Trigger a rebuild — assets/data/wiki-index.json is built per Jekyll run. On GitHub Pages this happens automatically on push; locally, stop and restart docker-compose up (or save any file to retrigger incremental builds).
3. Add an aliases: entry on the target if the link uses an alternate spelling.

Image embed shows a broken image icon

Cause: image isn’t where the resolver looks.

Fix:

• Default attachment path is assets/images/notes/ (set in .obsidian/app.json → attachmentFolderPath). If you customized that, set the matching path on the site via:

  <script>window.OBSIDIAN_ATTACHMENTS_PATH = '/your/path';</script>
  

  before the resolver script loads.

• For an absolute path, prefix the embed target with /: ![[/assets/images/special/diagram.png]].

Callout renders as a plain <blockquote>

Cause: the first non-blank line of the blockquote isn’t [!type]. Obsidian is permissive about whitespace; the resolver requires the marker on the first line of the quote (which is what kramdown’s first <p> contains after parsing).

Fix: make sure there’s no blank line between the [!type] head and the body:

> [!warning] Title       ← good
> body line

>                         ← bad: blank first line
> [!warning] Title
> body line

[[link]] syntax appears literally inside a code block

Expected behavior. Both the Ruby converter and the JS resolver explicitly skip code spans (`…`) and fenced code blocks ( ```). To force a wiki-link, move it out of the code context.

Tags don’t link to anything

Cause: the inline #tag matches the regex but the tag aggregator page (pages/tags.md) hasn’t picked it up because tags are read from frontmatter, not body.

Fix: also add the tag to the tags: array in frontmatter so it shows on /tags/:

tags: [obsidian, your-inline-tag]

Backlinks panel is missing on a note

Causes & fixes:

• Layout other than note? Add backlinks: true to frontmatter.
• Explicitly disabled? Remove backlinks: false.
• No incoming links exist yet — the panel is hidden when empty rather than showing an empty section.

Custom plugin (_plugins/obsidian_links.rb) doesn’t run on my fork’s GitHub Pages build

This is expected for sites built with the github-pages gem. That gem forces safe: true and overrides plugins_dir, so no custom Ruby plugin executes. The client-side resolver covers the same surface area.

If you want server-side rewrites (slightly better SEO, no flash before hydration), drop github-pages from Gemfile, switch to vanilla Jekyll, and add a custom GitHub Actions workflow that runs bundle exec jekyll build and deploys with actions/deploy-pages or peaceiris/actions-gh-pages. The plugin will pick up _plugins/ in that setup automatically.

Obsidian shows files I don’t want to see (_layouts/, assets/vendor/, …)

The shared .obsidian/app.json already excludes the most common build/config dirs via userIgnoreFilters. Add more entries there if you want them shared with collaborators, or use Obsidian Settings → Files & Links → Excluded files for personal-only filters.

Obsidian’s vault config is conflicting with another contributor’s

The repo commits a curated subset of .obsidian/. Per-user state (workspace*.json, cache, plugins/*/data.json, graph.json) is gitignored. If you see merge conflicts inside .obsidian/ for one of those files, it slipped through — drop it from git with:

git rm --cached .obsidian/workspace.json
echo ".obsidian/workspace.json" >> .gitignore

Then commit. The pattern is already in .gitignore; this is just for files that were committed before the gitignore took effect.

Still stuck?

Open an issue at github.com/bamr87/zer0-mistakes/issues with:

• The exact Markdown source that misbehaves.
• The rendered HTML (View Source on the live page).
• The output of ./test/test_obsidian.sh.

See also

• [[Obsidian Vault Integration]]
• [[Obsidian Syntax Reference]]
• [[Obsidian Authoring Workflow]]
• [[Obsidian Graph View]]
• [[Getting Started with the Obsidian Vault]]

Linked mentions 6

• Obsidian Authoring Workflow docs
  From an empty Obsidian note to a published page on GitHub Pages — the daily loop.
• Getting Started with the Obsidian Vault docs
  Open the Zer0-Mistakes repo as an Obsidian vault, install recommended plugins, and learn the frontmatter conventions.
• Obsidian Graph View docs
  Interactive force-directed map of every wiki-link in the site, mirroring Obsidian's local graph.
• Obsidian Vault Integration docs
  Edit Zer0-Mistakes content as an Obsidian vault and have it render identically on GitHub Pages.
• Obsidian Syntax Reference docs
  Every Obsidian-flavoured Markdown feature supported by the Zer0-Mistakes theme and how it renders on GitHub Pages.
• Troubleshooting docs
  Common setup and build issues when running Zer0-Mistakes.