Obsidian Authoring Workflow

By Amr

From an empty Obsidian note to a published page on GitHub Pages — the daily loop.

Estimated reading time: 2 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 Authoring Workflow

The round-trip

Obsidian (edit)  →  git commit  →  GitHub push  →  Pages build  →  live URL
       ↑                                                                │
       └──────────── git pull (Obsidian Git plugin) ────────────────────┘

Daily loop

1. Open the vault in Obsidian (root of the repo).
2. Create a note with Cmd/Ctrl + N. The Templates core plugin will offer note-template.md from pages/_notes/_templates/. Picking it stamps the canonical frontmatter (title, layout, permalink, …).
3. Write freely with [[wiki-links]], ![[embeds]], callouts, and #tags. Every one of those renders 1:1 on the site (see syntax reference).
4. Drop images into the editor — Obsidian saves them under assets/images/notes/ (configured in .obsidian/app.json), which is exactly where ![[image.png]] resolves on the site.
5. Commit & push.
   • With Obsidian Git plugin: Ctrl/Cmd + P → Source control: Commit all changes → Push.
   • From the terminal: standard git add / git commit / git push.
6. GitHub Pages rebuilds automatically. Within ~1 minute the new note is live at the permalink declared in its frontmatter.

Editing existing content

• Renames are safe. Obsidian’s Always update internal links setting (alwaysUpdateLinks: true in shared config) rewrites every [[link]] pointing at the renamed file. For URL-level redirects, add the old slug to the note’s aliases: array — jekyll-redirect-from will issue an HTTP redirect from the old URL.
• Moves between collections (pages/_notes/ ↔ pages/_posts/) work, but you’ll typically want to update layout: to match the destination collection’s defaults.

Local preview

The site renders the same Obsidian features locally:

docker-compose up
# → http://localhost:4000

Notes you edit in Obsidian are picked up by Jekyll’s incremental build within ~1 second. Refresh the browser to see your changes.

Validation before pushing

Run the integration’s smoke test to catch broken wiki-links, malformed frontmatter, or a regressed wiki-index schema:

./test/test_obsidian.sh

The full theme test suite (lint, build, deployment, styling, Obsidian) runs via:

./test/test_runner.sh --verbose

Cross-machine vault sync

Use Obsidian Git for the canonical sync — it pulls on open and prompts to commit on close. This keeps every machine using the same git history that GitHub Pages publishes from, so what you see in Obsidian is exactly what readers will see on the site.

[!tip] Avoid Obsidian Sync for this vault Obsidian’s paid Sync service operates outside git, so it can drift from what’s deployed. Stick with git push/git pull (manual or via the Obsidian Git plugin) so the vault and the live site never diverge.

See also

• [[Obsidian Vault Integration]]
• [[Getting Started with the Obsidian Vault]]
• [[Obsidian Syntax Reference]]
• [[Obsidian Graph View]]
• [[Obsidian Integration Troubleshooting]]
• [[Docker]]

Linked mentions 5

• 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.
• Obsidian Integration Troubleshooting docs
  Common issues with the Obsidian + Jekyll integration and how to fix them.