This article explores why Obsidian was chosen as the authoring tool for this blog and how its unique features integrate with the web publishing system.

This is part 2 of the Blog Architecture Deep Dive series. Start with Blog Architecture - Overview if you haven't read it yet.

What is Obsidian?

Obsidian is a note-taking and knowledge management application built around markdown files. Unlike traditional note apps that store content in databases, Obsidian works with plain text markdown files stored in a folder (called a "vault").

Key features that make Obsidian powerful:

• Wiki-style linking: Use <span class="obsidian-link disabled" data-link="double brackets" title="Link to: double brackets (not yet created)">double brackets</span> to create links between notes

• Graph view: Visualize connections between your notes

• Plugins: Extensible with a rich plugin ecosystem

• Local-first: All your data stays on your computer

• Markdown-based: Uses standard markdown with some extensions

Why Obsidian for Blogging?

1. Familiar Authoring Experience

If you already use Obsidian for notes, journals, or knowledge management, you can use the same tool for blogging. There's no need to:

• Learn a new interface

• Switch between applications

• Copy-paste content between tools

• Remember different workflows

You write in Obsidian, and the blog automatically publishes your content.

2. Wiki Links Create Natural Navigation

Obsidian's <span class="obsidian-link disabled" data-link="wiki links" title="Link to: wiki links (not yet created)">wiki links</span> are more than just links: they create a knowledge graph. When you link posts together in Obsidian, those links automatically become navigation on the website.

For example, if you write:

This blog uses <span class="obsidian-link disabled" data-link="Next.js" title="Link to: Next.js (not yet created)">Next.js</span> for static site generation.

See <a href="/blog/Coding%2FBlog_Architecture%2FBlog_Architecture_-_Overview" class="obsidian-link active" title="Blog Architecture - Overview">Blog Architecture - Overview</a> for more details.

The system automatically:

• Finds the linked posts

• Converts them to clickable web links

• Creates navigation relationships

• Builds a content tree from the link structure

This means your blog's navigation emerges naturally from how you organize your thoughts, not from a separate navigation menu you have to maintain.

3. No Content Lock-In

Your content is just markdown files in a folder. You own them completely. They're not:

• Locked into a database

• Tied to a specific platform

• Dependent on a service

You can:

• Move files anywhere

• Use them with other tools

• Keep them forever

• Version control them with Git

• Edit them with any text editor

This portability is crucial for long-term content management.

4. Rich Metadata with Frontmatter

Obsidian supports YAML frontmatter, which allows you to add metadata to posts:

---

title: My Blog Post

date: 2024-12-21

categories:

- Technology

- Web Development

series: Blog Architecture

seriesOrder: 2

published: published

---

  

# My Blog Post

  

Content here...

The blog system extracts this metadata and uses it for:

• Post titles and dates

• Category organization

• Series grouping

• Publishing control

• SEO metadata

5. Directory Structure as Organization

In Obsidian, you can organize files in folders. The blog preserves this structure in URLs:

• File: Coding/Blog Architecture.md

• URL: /blog/Coding/Blog_Architecture

This means your file organization becomes your URL structure, creating a natural hierarchy.

6. Categories and Tags

Obsidian supports tags and categories, which the blog uses for:

• Category organization

• Content filtering

• Content discovery

You can use Obsidian's tag system to organize your blog content just like you organize your notes. Publishing is controlled via frontmatter metadata (published: published), not tags.

How Obsidian Integration Works

File Discovery

The blog system scans your Obsidian vault (the folder where your markdown files are stored) and finds all .md files. It:

• Recursively traverses all subdirectories

• Handles symlinks safely (prevents infinite loops)

• Skips hidden files (like .obsidian config folders)

• Respects depth limits (prevents stack overflow)

Publishing Detection

Not all markdown files should be published. The system uses frontmatter metadata:

To publish a post:

• Set published: published in frontmatter

To exclude a post:

• Set published: draft in frontmatter, or omit the published field

This allows a simple workflow: write drafts normally, add published: published to frontmatter when ready to publish.

Link Resolution

One of the most complex parts is converting Obsidian's <span class="obsidian-link disabled" data-link="wiki links" title="Link to: wiki links (not yet created)">wiki links</span> to HTML links. The system handles:

• Simple links: <span class="obsidian-link disabled" data-link="Post Name" title="Link to: Post Name (not yet created)">Post Name</span> → <a href="/blog/Post_Name">Post Name</a>

• Display text: <span class="obsidian-link disabled" data-link="Post Name" title="Link to: Post Name (not yet created)">Custom Text</span> → <a href="/blog/Post_Name">Custom Text</a>

• Path-based: <span class="obsidian-link disabled" data-link="folder/file" title="Link to: folder/file (not yet created)">folder/file</span> → matches by directory structure

• Fuzzy matching: Handles variations in spacing and capitalization

The link resolver uses a three-tier matching strategy:

1. Path-based matching - For links with / (directory structure)

2. Filename matching - Matches against file basenames

3. Fuzzy matching - Normalizes and matches with variations

Metadata Extraction

The system extracts rich metadata from Obsidian files:

• Title: From frontmatter, first H1, or filename

• Date: From frontmatter or file creation time

• Categories: From frontmatter, category field, or tags

• Series: From series: and seriesOrder: fields

• Excerpt: Automatically generated from content

• Images: From frontmatter or Obsidian image syntax ![image](/blog-content/image.png)

Obsidian-Specific Features

Image Handling

Obsidian uses ![image](/blog-content/image.png) syntax for images. The blog converts this to standard markdown ![alt](/blog-content/image.png) and handles:

• URL encoding for filenames with spaces

• Alt text from the image link

• Path resolution from the vault structure

Frontmatter Processing

The blog respects Obsidian's frontmatter conventions:

• YAML format between --- delimiters

• Multiple metadata fields

• Arrays and nested structures

• Custom fields (like url: for custom URLs)

Directory Structure Preservation

Your Obsidian folder structure becomes your URL structure:

Obsidian Vault/

Coding/

Blog Architecture.md

This Blog.md

Science/

Physics.md

Becomes:

/blog/Coding/Blog_Architecture

/blog/Coding/This_Blog

/blog/Science/Physics

This creates a natural hierarchy that reflects how you organize your content.

Development Workflow

Writing in Obsidian

1. Create a new markdown file in your Obsidian vault

2. Write your content using markdown and <span class="obsidian-link disabled" data-link="wiki links" title="Link to: wiki links (not yet created)">wiki links</span>

3. Add frontmatter for metadata

4. Set published: published in frontmatter when ready

Live Preview

In development mode, the blog reads directly from your Obsidian vault. This means:

• Changes appear immediately (no rebuild needed)

• Fast iteration: edit in Obsidian, see changes in browser

• No copy step required

Production Build

For production, the build process:

1. Copies all content from the vault to blog-content/

2. Processes all files

3. Generates static pages

4. Deploys to hosting

This ensures production uses a snapshot of your content, not live files.

Benefits of This Approach

For Authors

• Familiar tools: Write in the app you already use

• No learning curve: No new interface to learn

• Powerful linking: Wiki links create natural connections

• Local-first: Your content stays on your computer

• Version control: Markdown files work with Git

For Readers

• Fast loading: All pages are pre-generated static files

• Natural navigation: Links create organic exploration paths

• SEO-friendly: Static HTML is great for search engines

• Reliable: No database means fewer failure points

For Maintenance

• Simple: No CMS to maintain, no database to backup

• Portable: Content is just files, easy to move

• Version controlled: Track changes with Git

• Future-proof: Markdown will be readable forever

Trade-offs and Considerations

Obsidian-Specific Syntax

The blog needs to handle Obsidian-specific features like <span class="obsidian-link disabled" data-link="wiki links" title="Link to: wiki links (not yet created)">wiki links</span> and ![images](/blog-content/images). This adds complexity to the processing pipeline, but the benefits outweigh the costs.

File Organization

Your file organization becomes your URL structure. This is powerful but means you need to think about folder structure when organizing content.

Link Resolution

Converting Obsidian links to web links requires careful matching logic. The system handles many edge cases, but some manual fixes might be needed for unusual link formats.

Conclusion

Obsidian provides a unique authoring experience that integrates seamlessly with static site generation. By using Obsidian as the content source, the blog gains:

• Familiar authoring tools

• Natural navigation from wiki links

• Content portability

• Rich metadata support

• Local-first workflow

The integration between Obsidian and Next.js creates a blog that feels native to both worlds: powerful authoring in Obsidian, modern web experience on the site.

Next Steps

Continue to Blog Architecture - From Markdown to Web to learn how Obsidian markdown files are processed and converted into web pages.

Related Content

• Blog Architecture - Overview - High-level introduction to the blog architecture

• This Blog - Original detailed technical overview

• Blog Design - Overview of all blog design articles

• Navigating Blog Content - How users navigate the blog

---

This article is part of the Blog Architecture Deep Dive series. Previous: Blog Architecture - Overview. Next: Blog Architecture - From Markdown to Web.