Engineering
If the Tool You Need Doesn’t Exist, Build It
Spelunking through Obsidian’s APIs to build a literary plugin.
Every summer of my teen years, our parents would drop my brother and me off at my grandparents’ house, perched on the side of a North Georgia mountain. My grandfather (we called him Pepere) liked to build things. He and Memere had designed and built the Georgia house themselves. (Pepere and Memere were the only bits of Quebecois vernacular Memere had managed to get to stick.)
More recently he’d built a water wheel. He’d diverted the old crick (“creek,” in our Mid-Atlantic mouths) to run down a hill on their property, over a low cliff, and into the small wheel’s bladed rim. The wheel turned a shaft that disappeared into a hunched shed. The shed’s door was locked. “An artist builds their own tools,” said Pepere when we asked, early that summer, about the wheel. This sufficed for an answer.
Pepere got us building, too. Their studio opened to the air on one side, so we’d haul out scrap wood and nails and paint and glue and end up with the strange inventions of youth. Pepere would emerge from the water wheel’s shed, lock the door behind him, and come upon us using shivs of wood to lever out bent nails, laughing: “An artist builds their own tools.”
Pepere and Memere also kept an old Windows machine in their studio, ostensibly to help sell paintings to galleries but in reality to submit itself to their grandsons’ ministrations. We traded evenings of fireflies for a few twilit summers coaxing HTML 1.0 and JavaScript alert()s from Notepad.exe. Twenty years later, I am again shuffling divs around, this time within an app called Obsidian, on a tool that I have built.
Obsidian is a “knowledge base,” a term of art in a small but enthusiastic community of people who desire to know, and know better. It’s perhaps best described as a notes app by way of personal wiki, a folder of Markdown files that can be interlinked, scripted, and variously displayed. I, like many in this community, had been forever in search of a tool that could take the many notes I jot down when they occur to me and corral them into meaning. I migrated my notes into Obsidian last year and stopped searching.
Out of the box, Obsidian has a lot going for it. It runs on Markdown files, so my notes are pretty well future-proofed. It handles internal linking and is themeable via CSS. I use it to keep a journal, to take notes for work, and to capture ideas for fiction I’d like to write. Up until recently, I’d have both Obsidian and Scrivener, my composition app, open while writing, switching between the two, copying notes from Obsidian into Scrivener as needed. Then I found that Obsidian had an API, and asked myself: Could I write directly in Obsidian?
Yes, I could. I built a tool I called Longform as a plugin inside Obsidian. It lets me create drafts of ordered scenes and, when ready, compile those scenes into a manuscript. Look, here I am writing this very article:
Obsidian plugins are open-source by necessity — it’s how they’re browsed and installed into the app. Building a tool for oneself in the privacy of your water wheel shed is subtly different from doing so out in the open where everyone can see your code. One of the first issues opened on the repo was titled “Nothing works?”. You’re forced to maintain a tool that satisfies your needs without boxing out every other living soul who might want to use it. This is a good thing: In expanding the capabilities to include others, I’ve discovered new uses for Longform, features I’d never considered and am now excited to make a part of how I write fiction.
This inclusion has been driven by a community that is very, very enthusiastic. These are people who see a personal wiki app and think, Yes, I am capable of spending a lifetime carefully constructing a Borgesian library slash knowledge graph that, if done right, will be a suitable substitute for my brain. Their notes are precious. An early rule I made for myself in developing my tool is that it should never risk altering or overwriting a note. As much as I revere rewriting, I never want to see a GitHub issue titled something like Lost Manuscript: How to Recover?. This kind of boundary also helps me keep feature requests from the community in check: People often suggest features that sound amazing but cede control of the text to the code, and I get to reply and say, Look, that does sound wonderful, but code is inherently fallible and the last thing I want to do is accidentally trash your opus. So: Narrow your scope and set technical restrictions!
In building Longform I also came to appreciate the foresight of Obsidian’s small (two-person!) team in how its plugin API is structured. It’s a near-perfect example of the separation of concerns. The API is exposed as a set of TypeScript declarations that is extracted from the closed-source app; these types show an app built in careful layers, encapsulations of file systems from iOS to Windows, multiple versions of CodeMirror, all reduced to a spotless surface API. Despite an alpha status and no real documentation to speak of, the types are so readable that there are already hundreds of plugins available in-app. And because Obsidian is an Electron app on desktop, spelunking through those APIs is as easy as opening the console.
Obsidian is fairly new, but I think it’ll be around for a long time. It certainly didn’t exist back during our Georgia summers, when the state of the art on Memere’s computer was Chip’s Challenge. I want desperately to remember the sound of stillness when we shut down that computer after night had fallen, the complaint of water in transit around the wheel.
I’ve never had a good memory. Perhaps this is why I’m drawn to systems, notes, interlinking. And I know it’s why I feel compelled to write fiction: I am inventing memories. Because when I take the key from its place on the nail high on the studio wall, and I pad softly down the stone walkway alert for black bears in the night, and I fit the key into the wheel shed’s door, it is empty. An axle turns nothing in the moonlight. I needed only the shed to tell this story, a containing structure, not what was inside. An artist makes their own tools.
Kevin Barrett (he/him) is a Partner and Director of Engineering at Postlight. Reach out at hello@postlight.com or follow him on Twitter @kevboh.
Work for Postlight! Love making exceptional digital products? We’re hiring engineers, PMs, designers, and strategists. Let’s grow together. See openings.
