From Failed CMS to the Perfect Workflow: How I Manage My Blog & Study Board with Obsidian, Astro, and Git

When I set out to build the new version of my personal portfolio and Study Board, I had a clear goal in mind: I wanted a frictionless setup that allowed me to write technical articles and capture learning notes anytime—whether working at my desktop on Linux Mint or on the go with my iPad.

Over 20 years of software engineering have taught me that the simplest architectures are often the most resilient. Yet, finding the right balance between a blazingly fast static site built with Astro and a truly usable mobile content management setup proved to be a journey filled with invaluable lessons.

In this article, I share the traps I encountered, the serverless bugs I hit, and how I arrived at my ultimate architecture: zero third-party SaaS dependencies, zero CMS bloat, and 100% control over plain Markdown files.

---

1. Attempt #1: Decap CMS (And the Mobile Layout Trap)

My first choice was Decap CMS (formerly Netlify CMS). The initial premise sounded great: an embedded web dashboard at /admin writing Markdown directly to GitHub.

However, I quickly ran into a fundamental limitation: Decap CMS was designed in 2016 for desktop screens. Its rigid two-column React layout (SplitPane) breaks severely on mobile viewports. Trying to override the CSS with custom responsive rules was a battle against a desktop-first architecture.

---

2. Attempt #2: Keystatic (And the Serverless Cookie Bug)

Next, I turned to Keystatic, a modern tool in the Astro ecosystem with a polished UI. It worked flawlessly on localhost, but as soon as I deployed to Netlify, an architectural issue surfaced.

In Netlify’s serverless production environment, during the GitHub OAuth callback (/api/keystatic/github/oauth/callback), the session cookie handling triggered an HTTP 500 error (Authorization failed). The root cause was an incompatibility in handling OAuth state cookies within Netlify Serverless Functions on static Astro v5 builds.

The recommended workaround was using a third-party bridge (Keystatic Cloud). But that violated one of my core engineering principles: I wanted zero reliance on external SaaS platforms to manage my data.

---

3. The Epiphany: Why Use a Web CMS When We Have Git?

At that point, I asked myself the question every engineer should ask: why am I trying to run a content management app inside a web browser when I already have a Git repository full of Markdown files and an exceptional native app on my phone?

The answer was switching to Obsidian paired with Git Sync.

---

4. The Ultimate Architecture: Obsidian + Astro + Git

The core concept is remarkably simple:

1. Git Repo as the Single Source of Truth: All blog posts and Study Board items live in src/content/ as plain .md files with YAML frontmatter.
2. Obsidian as the Native Editor on PC & iPad: I open the repository directly inside Obsidian.
3. Pure Static Build with Astro: The Astro site remains a 100% static site generator (SSG) with zero CMS code or unnecessary React dependencies.

Workspace Isolation in Obsidian

To prevent the Obsidian sidebar from being clogged with Astro source code (components, pages, layouts, node_modules), I leveraged Obsidian’s built-in “Excluded files” feature.

On both my Linux Mint PC and iPad, my sidebar displays exclusively my content folders:

• 📁 studyboard
• 📁 blog
• 📁 projects
• 📁 _templates

---

5. Templating System and YAML Metadata

Inside Obsidian, I created a src/content/_templates/ folder containing starter templates for the Study Board, Blog, and Projects. The _ prefix ensures that Astro’s content loaders completely ignore the folder during site builds.

Using Obsidian’s native Properties feature, I manage YAML frontmatter (Status, Category, Tags, Emoji) with visual dropdowns, pre-filled dates, and colored pill badges.

---

6. Mobile Native Sync and CI/CD Pipeline

On my iPad, I installed the community plugin Git (by Vinzent03), authenticated with a GitHub Personal Access Token.

The daily workflow is seamless:

1. Write or update a note on iPad or PC (even offline).
2. Obsidian Git automatically commits and pushes to GitHub.
3. Netlify detects the push and rebuilds the static site in ~30 seconds.

On Linux Mint, I enabled the Git credential helper (git config --global credential.helper store), eliminating password prompts forever.

---

Conclusion

Building a fast website is not just about optimizing frontend code—it’s about crafting a friction-free Developer Experience.

Ditching traditional web CMSs allowed me to:

• Eliminate all third-party SaaS dependencies.
• Keep the Astro codebase lightweight and blazingly fast.
• Enjoy an offline-first, native, and delightful writing experience across all my devices.