The Long-Form Room

Part 1 of 7: Documents in the Wild

I have a rule about the message box at the top of the feed: if I catch myself fighting it, the thought has outgrown it. A message is meant to be one clean idea with a timestamp on it. The second I want a heading, or a second heading, or a little table to keep two columns straight, I am no longer writing a post. I am writing a document, and I should go somewhere built for that.

That somewhere is the Documents editor. This is the long-form room in a product that started life as a feed, and the whole series is about living in it. Fair warning up front, because I would rather say it in the first post than bury it: Documents are a Subscriber feature. Creating one, foldering it, dropping an image in, and sharing it are all things the paid tier unlocks. The generous half of that story comes later (the people you share with read and edit for free). For now, know that opening this room costs something, and I think it earns it.

What a document actually is

Strip the editor away and a document is four things. A title. A body of Markdown text, stored as a plain string. A path that ends in .md, so the thing is a real file and not a mystery blob. And a single isPublic flag that decides whether anyone but you can read it.

That is the whole object. The difference from a message is not complexity for its own sake. It is that a document's body is Markdown that renders. Your ## becomes a real heading. Your - item becomes a bullet. Your table becomes a table. The feed deliberately does not do this (a post is plain text with links and mentions auto-linked, and that is the right call for a post). A document is where structure is the point.

Three ways to look at the same words

The editor gives you three modes, and you will use all of them. Edit is just the Markdown source, full width, when you want to type and not be distracted. Preview is the rendered result, full width, when you want to read it like your reader will. And Live, which is the default on a desktop, puts the source on the left and the rendered preview on the right and keeps them in lockstep as you type.

The document editor in Live mode: a formatting toolbar across the top, Markdown source on the left, and the rendered newsletter draft on the right, with the folder tree in the sidebar

Live mode. You type Markdown on the left and watch it become the thing on the right.

I write almost everything in Live. It is the fastest way to catch the moment a heading is in the wrong place or a list should have been a table, because you see the consequence immediately instead of flipping back and forth. When I want to actually read the piece as a whole, I tap Preview and the source gets out of the way.

There is no Save button, and that is deliberate

Look for a Save button and you will not find one. Your edits autosave as you go. That sounds like a small thing until you have lost an afternoon of writing to a browser crash, at which point it stops sounding small. Under the hood there is a single save in flight at a time and a version check on every write, which is the boring plumbing that keeps two tabs (or two people, but that is Part 6) from clobbering each other. You do not have to think about any of it. You type, it is kept.

That is the pitch for the room itself. A title, real Markdown, three ways to see it, and nothing to remember to press. Everything else in this series is what you do once you are standing in it.

Next up, the fastest way to never face a blank one: the templates that come in the box, and the ones you build yourself.

Adron