Skip Navigation
Apr 11 2023

Dropping Astro Markdoc for the Super Smooth Astro-Markdown-Obsidian Setup

The Astro Markdoc integration will not work for me as long as it doesn't use the `.md` extension. The Astro experience with plain ol' Markdown and my Obsidian is so good I can't imagine sacrificing it for anything less capable.

A beautiful Obsidian content graph in the making.

I reverted to using Markdown instead of Markdoc today, not because of a lack of feature parity with the Markdown/MDX solution in Astro - which I handled fast enough for my needs, but because of the .mdoc file extension used by the integration.

As long as the Markdoc integration uses that extension instead of .md, I can’t use it much as I want to.

The .mdoc files are treated as second-rate citizens at best by nearly all Markdown editors I like to use in my writing workflow.

Obsidian opens them if I use a community plugin that makes Obsidian assign basic Markdown functionality to the files. They can be opened and edited but linking, tagging, and other stuff leave much to be desired. Even if it opens the files, it treats them as attachments 😞 and many of the cool features in Obsidian don’t work. Not for lack of trying on my end.

Apparently, MDOC extensions represent Visual Studio Code data. That makes sense since VS Code was the only editor to open .mdoc files without a ritual sacrifice. I found some other uses for the extension that are quite exotic for me, so I won’t go through those.

GitHub’s marking the files as Roff whatever that is.

GitHub classifying mdoc files as Roff files.

It can be fixed, I’m sure, but I’d have to fidget with things to do so.

I don’t mind a bit of fidgeting, but I would hate to move from one framework to another only to fidget differently 😬

Now, fellow coders will say - why not just use VS Code instead of Obsidian and be done with it? The answer to that is simple: I don’t want to. I have struggled with writing in the past few years (decade). With some of my ooompf back, I’d get distracted in VS Code because there’s always something fun to code. So, call my reluctance to use VS Code for writing a deeply personal need to separate concerns and avoid distractions.

Thanks to how I’ve coded and configured things, all I had to do to revert to a drama-free writing setup in Obsidian was change the extensions of the content files. Full Obsidian sweetness is restored, and all the components and quality-of-life additions — heading links, table of contents, code copying, and the custom Shiki theme — work as intended.

Nothing is lost but the ability to use Markdoc in production for a short while.

Luckily or not, it will be months before I have to leverage Markdoc in one of my projects. There’s time to see where the extension is going and if I can help get it there in any way.

Until then, I will enjoy the absolutely delicious experience of owning an Astro blog with Markdown files written in Obsidian.

This stuff is seriously smooth. Astronauts weren’t kidding when saying

Zero to website in whoa

I concur.