Obsidian for internal docs
I've grown cautious of my proclivity to prematurely review a tool. The most important quality of any tool meant to be used regularly is the ease with which you habituate. A glowing review of a knife with an unworn handle is worth very little, and I say that as prelude to this review of our use of Obsidian to manage Buttondown's internal docs.
For context: we've been trying to find a good solution for what perhaps naively seems like an incredibly tractable problem for most of the year. Here is the problem as I would describe it: our internal docs, just like our external docs, are entirely backed by Markdown and live in the monorepo. We want an easy way to surface and publish these, gated behind a feature set that I would consider relatively small—notably backlinks, search, and Mermaid—without having to roll and maintain our own internal docs framework, let alone our own internal gating or intranet mechanism. (We do use Tailscale, so we could theoretically plug into that, but you get my point.)
I'm not sure how I hit on the idea of using Obsidian and Obsidian Publish for this—it was perhaps a bolt from the blue—but for starters, it fits all those requirements described above. Lest that sound like damning with faint praise: as far as I know, there is no other relatively common solution that does.
There are two main pain points thus far:
- Obsidian Publish is slow. I lead with this because I think it's the single biggest constraint, especially when getting things set up and well-themed. There is a one-hour caching delay between publishing and going live. It's entirely reasonable for the majority of use cases, but extremely painful when you're trying to iterate quickly.
- There appears to be no formal method of automating the publishing. What I would love is a simple GitHub Action that auto-deploys, much like everything else. I again say that knowing our use case is fairly esoteric relative to Obsidian Publish's target market.
That's really all I have to say about Obsidian Publish. The theme we landed on is a fork of Minimal; it's not beautiful, but functional, and I actually appreciate the lack of fiddling I can do because it keeps me focused on the more meaningful work.
All of this belies what is, to most readers, probably the more interesting element of this setup: the local Markdown monorepo itself. That decision predates my poking around at Obsidian, but I still have never really talked about it, and this seems as good a time as any to do so. Here are some scattered facts:
- Lee Robinson's blog post about Cursor largely rings true, even for internal docs. I appreciate that many organizations cannot expect every would-be editor or writer of internal docs to be able to write Markdown or interact with Git. But one of the luxuries of having a smaller and more technical team is the ability to ignore that constraint.
- The single most useful thing we get out of this is the ability to search within internal docs and the codebase simultaneously and with speed, both from an editing standpoint and a research standpoint. This is such a killer feature that everything else pales in comparison. Docs die not due to intentional malice or incompetence, but due to drift.
- It also gives us the ability to write integration tests about our docs themselves—not the site, but the content. For example: every single API change needs to have a dedicated page with the breaking changes, or else we fail CI.
- Git gives you a lot of nice CMS-shaped things, such as versioning, though I'd be lying if I said we use this particularly heavily.
- Having internal docs ambiently exist for LLMs to discover and parse is really, really nice. Most other options, such as Notion or Confluence, have solved this problem through the shim of MCPs. But even though it's no longer novel, I feel like backlinking is still a somewhat underrated mechanism.
All in all: I am happy with this solution. Publish itself might go away; internal docs as Just Markdown will not.