Using Obsidian to Manage Your Blogs and Documentation

By James Aspinwall

I write all my blogs and project documentation in Markdown. No HTML rendering, no CMS, no database — just .md files in two directories inside my project repository. Obsidian turns these flat files into a searchable, linked, visual workspace without changing anything about how they’re stored or versioned.

Here’s how I set it up.

The Setup

My project has two directories that contain all the Markdown content I care about:

mcp/
├── asset/
│   ├── blogs/        # Published articles
│   └── docs/         # Project documentation

Obsidian works by opening a folder as a “vault.” Everything inside that folder becomes navigable, searchable, and linkable. The key decision is what to point it at.

Option 1: Open asset/ as the Vault

This is the cleanest approach. Open Obsidian, choose “Open folder as vault,” and select the asset/ directory. Obsidian now sees two top-level folders — blogs/ and docs/ — and indexes every .md file in both.

This keeps the vault focused on content. No source code, no config files, no noise. Just your writing.

Option 2: Open the Project Root as the Vault

If you want Obsidian to also see your README.md, CLAUDE.md, or other Markdown files scattered around the project, point it at the project root. Use Obsidian’s “Excluded files” setting (Settings > Files & Links > Excluded files) to hide directories you don’t need:

lib/
config/
deps/
_build/
priv/
test/
.git/

This gives you full project visibility but requires more filtering. Option 1 is better for focused writing; Option 2 is better if you cross-reference documentation with project-level files.

Configuration Worth Changing

Once the vault is open, adjust a few defaults.

Settings > Files & Links:

• Set “Default location for new notes” to blogs/ (or docs/ depending on what you write more)
• Turn on “Automatically update internal links” — when you rename a file, all [[links]] pointing to it update automatically
• Set “New link format” to “Relative path to file” — this keeps links portable and compatible with GitHub rendering

Settings > Editor:

• Enable “Strict line breaks” if you want single newlines to render as line breaks (matches how most Markdown renderers behave)
• Turn off “Smart indent lists” if it fights with your writing style

Settings > Core Plugins:

• Enable “Templates” and point the template folder to a _templates/ directory inside your vault — useful for blog post scaffolding
• Enable “Tags” for filtering content by topic
• Enable “Backlinks” to see which docs reference the current file

Creating a Blog Post Template

Create asset/_templates/blog-post.md:

# {{title}}

*By James Aspinwall*

---

Now when you create a new blog post, use Ctrl/Cmd+T to insert the template. Fill in the title, start writing. The file saves directly into your blogs/ directory as a plain .md file — the same format your server already knows how to serve.

Linking Between Documents

Obsidian’s killer feature for a documentation-heavy project is [[wiki-links]]. Type [[ and start typing a filename — Obsidian autocompletes across your entire vault.

Link a blog post to a relevant architecture doc:

For implementation details, see [[APPLICATION]]

Link documentation to related articles:

This module is discussed in [[why-elixir-otp-for-mcp-servers]]

These links are bidirectional. Open any doc and the “Backlinks” panel shows every other file that references it. Over time, this builds a navigable knowledge graph across your blogs and docs without any manual index maintenance.

Compatibility note: [[wiki-links]] are an Obsidian convention. GitHub and most Markdown renderers won’t resolve them. If you need links that work everywhere, use standard Markdown links instead: [APPLICATION](../docs/APPLICATION.md). Obsidian handles both formats.

The Graph View

Open the graph view (Ctrl/Cmd+G) to see your entire content library as a visual network. Blog posts cluster around the docs they reference. Orphaned files — docs that nothing links to, blog posts with no cross-references — stand out immediately.

This is genuinely useful for finding gaps. If you’ve written ten blog posts about AI agents but none of them link to your authentication docs, that’s either a missing connection or a missing article.

Search Across Everything

Obsidian’s search (Ctrl/Cmd+Shift+F) is fast and supports operators:

• path:blogs/ — search only blog posts
• path:docs/ — search only documentation
• tag:#mcp — find all files tagged with a topic
• section:## Usage — find files with a specific heading

For a growing library of technical content, this replaces the need for any external search or cataloging tool.

Tags for Organization

Add tags to your Markdown frontmatter or inline in the text:

---
tags: [mcp, elixir, architecture]
---

Or simply write #mcp anywhere in the body. Obsidian indexes both styles. Use the Tags pane to browse all content by topic across blogs and docs simultaneously.

A practical tagging scheme:

• #published / #draft for blog status
• #mcp / #elixir / #otp for technology
• #internal for docs not meant for public consumption

Daily Workflow

The daily routine is simple:

1. Open Obsidian. Your vault is already pointed at asset/.
2. Write or edit a blog post. It saves as a .md file in blogs/.
3. Write or update project docs. They save as .md files in docs/.
4. Link related content with [[double brackets]] as you go.
5. Commit and push from your terminal. Git sees the changed .md files like any other code change.

Obsidian never modifies your files in unexpected ways. It doesn’t add proprietary metadata, convert your formatting, or move things around. The .md files it creates are the same files your server serves, your CI indexes, and your collaborators read on GitHub.

What Obsidian Replaces

Before Obsidian, managing Markdown content meant:

• Using a code editor that treats .md files like source code (no linking, no graph, no backlinks)
• Maintaining a manual index or table of contents that drifts out of date
• Searching with grep across directories
• No visual overview of how content relates

After Obsidian: the files stay exactly where they are, stored exactly how they were, versioned by the same git workflow. You just see them better.

The .obsidian Directory

Obsidian creates a .obsidian/ folder inside your vault for its configuration (themes, plugins, workspace layout). Add it to your .gitignore — it’s editor-specific state, not project content:

asset/.obsidian/

Your Markdown files remain clean, portable, and owned by you. Obsidian is just the lens.