On this page
1 New Section
1.1 Why I'm Building My Own Publishing Platform
I want to publish maritime research online.
There are approximately 4,000 tools that do this. Ghost is beautiful. Astro is fast. Hugo builds a site before you've finished blinking. WordPress has been doing this since before some of my cadets were born. Medium will even find you an audience, as long as you don't mind your readers hitting a paywall on someone else's terms.
So naturally, I'm building my own platform from scratch. This is not the rational choice. I'm going to do it anyway.
1.2 The Itch
My background is in maritime operations: the world of vessel management, offshore construction, regulatory compliance, and procedures that reference procedures that reference other procedures. I want to write about it. Not social media posts, but long-form, structured research with proper numbered sections, data tables, technical diagrams, cross-references, and the occasional equation.
And I want it on my own domain, under my own control, looking exactly how I want it to look.
"So use Ghost," you say. And you're right, I probably should. Ghost's editor is genuinely lovely. But Ghost thinks in blog posts and newsletters. My writing thinks in numbered sections and cross-referenced regulatory frameworks. These are not the same shape.
"Fine, use Astro with some Markdown files." Also reasonable. I've actually gone pretty far down this road. But here's what happens: you start with clean Markdown, then you need a callout box, so you add some custom syntax. Then you need a cross-reference to another document, so you invent a convention. Then you need a sortable data table, so you bolt on a component. Then you need the same background section to appear in three different articles without copy-pasting it, and suddenly you're maintaining a bespoke content system held together by filename conventions and good intentions.
I've been down that road. The destination is not great.
1.3 The Actual Problem
What I really want is deceptively simple:
A publishing tool that takes structured content seriously.
Not "structured" as in "has headings and bullet points." Structured as in:
- Every section is its own versioned unit that I can reuse across documents
- Cross-references between documents are real typed links, not strings I'll have to fix when I rename something
- The formatting I can use is deliberately constrained so that everything I publish looks consistent, whether I wrote it on a Monday morning with coffee or a Friday evening without
- The content is stored in a way that's useful beyond just rendering HTML. Searchable, queryable, ready for whatever I want to do with it next
- I can see how my documents relate to each other, what references what, where the same concept appears in different contexts
That last point matters more than it might seem. Maritime regulatory knowledge isn't a collection of independent articles. It's a graph. An IMO resolution informs a class society's rules, which constrain an operator's procedures, which reference equipment specifications, which trace back to the original regulation. If your publishing tool can't represent relationships, you're flattening something that isn't flat.
1.4 So What Am I Actually Building?
The project is called Manifest, named after the maritime document that lists everything a vessel carries. Which is more or less what this does: it assembles structured sections into published documents.
The core idea is an assembly pattern. Content is written as atomic, reusable sections. A published document is an assembly: a tree that says "put this section here, that section there, number them like this." The sections don't know what document they'll end up in. The assembly decides.
This is comically over-engineered for a personal blog. I'm aware. But the architecture costs me almost nothing extra to implement, and it means that when I inevitably want to do more complex things (compose multi-part research series, maintain living documents that evolve over time, reuse the same foundational explanations across different articles) the system already supports it. I'd rather build the right foundation now than migrate later.
For the technically curious, the stack:
- Markdoc for the content format. Stripe built it to power their docs, and it gives me schema-validated custom tags without turning Markdown into a programming language
- TipTap for the editor. A headless rich text editor built on ProseMirror that lets me define exactly which formatting options exist and nothing more
- PostgreSQL for storage. Content, relationships, and vector embeddings all in one place
- Next.js for the frontend, FastAPI for the backend
- Self-hosted on Hetzner because I want my data in the EU, under EU jurisdiction, out of reach of potentially overreaching foreign governments
Every dependency uses a permissive open-source license. This is deliberate, but that's a story for another post.
1.5 Building in Public
I'm going to build this in the open. Not the code, but the thinking. The architectural decisions, the trade-offs, the things that work, and (more interestingly) the things that don't.
Partly this is accountability. It's easy to endlessly tinker with architecture in private. It's harder to do that when you've told people you're building something.
Partly it's because the best technical writing I've read has always been people explaining what they're building and why. I've learned more from build logs than from documentation, and I'd like to contribute to that tradition.
And partly it's because I think there's a gap in the conversation about tools for publishing technical and regulatory content. The developer tooling world has incredible options for docs sites. The maritime industry has... Word documents emailed as PDF attachments. There might be a middle ground worth exploring.
1.6 What's Next
The first thing I need to do is design the data model. The PostgreSQL schema that everything else builds on. That's where the assembly pattern goes from a nice diagram to actual tables and relationships. I'll write about it when it's done.
After that: the editor schema (what formatting is allowed and what isn't), the rendering pipeline (how structured content becomes a beautiful web page), and eventually, publishing actual maritime research using the tool I built to publish it.
If that sounds interesting, or if you just want to watch someone over-engineer a blog in real time, the writing will be here at capitanroy.com.
It's day one. Let's start building.