We Took Documentation Out of the Modal

You are writing the onboarding page for a payment service. Six headings, two code blocks, a table of the queues it consumes, and a paragraph you keep rewriting because it is the paragraph the next engineer will actually read.

In Archyl, until this week, you wrote all of that inside a dialog. The page behind it went dark. The document tree, where the sibling pages live and where you would check what you called the last one, went dark with it. The editor filled the dialog, the dialog was not the screen, and reading a page and writing a page happened in two different places.

It worked. It also did not feel really professional, which is the sentence I kept coming back to until I sat down and rebuilt it.

The documentation workspace no longer has a modal in it. Here is what replaced it.

The editor opens where the document is

Hit Edit on a page, or press E while reading it, and the editor takes over the content column in place. The tree stays where it was, at full brightness, still clickable. Nothing overlays anything.

The document looks like a document while you write it. The title is a plain field at heading size, no label and no box around it. Tags sit underneath: type and press Enter or comma to add one, backspace on an empty field to take the last one back. The folder path runs along the top of the action bar, so you always know where the page you are writing will land.

The bar also carries the state. An amber dot and Unsaved changes while the draft differs from what is stored, then Save with its ⌘↵ hint. That shortcut works from anywhere in the editor, including from inside the Markdown body, so you never have to travel back to the button. There is a full-screen toggle next to the mode switch when you want the paragraph and nothing else, and Escape brings you back. Along the bottom edge, a word count and a reading time.

Write, Split, Preview

The editor has three modes, and they are the only toolbar decision you have to make:

• Write is Markdown only, the full width of the column.
• Split puts the source and the rendered page side by side.
• Preview is the rendered page alone.

Split is the default. Whichever one you pick, Archyl stores it in your browser and reopens every document that way, so the person who writes in raw Markdown and the person who wants to see the headings render never have to argue about it or reset it on every page.

Folders are a row in the tree

Creating a folder used to be its own dialog: a box, a text field, a Create button, and no clue where the folder was about to appear.

Now clicking the folder icon in the tree header opens an editable row exactly where the folder will live, at the right indentation, with the folder icon already drawn. Type the name, press Enter, and it exists. Escape cancels. Ask for a subfolder from a folder's own menu and the parent expands and the row appears inside it.

Renaming works the same way, in the row. Moving pages and folders is still drag and drop.

You cannot click away from unsaved work

Every move inside the documentation workspace runs through one guard: selecting a different page in the tree, starting a new page, opening another one for editing, cancelling out of the editor. If the draft has unsaved changes, the action is held and you get a confirmation first, with Keep editing as the way out and Discard changes as the deliberate one. Once you confirm, the action you originally asked for runs.

The browser is covered too. Closing the tab with an unsaved draft raises the browser's own warning.

This is the least visible change in the release and the one I would defend hardest. A tree of clickable pages next to an editor is a good layout only if clicking cannot cost you a paragraph.

The table of contents follows the panel, not the window

When the column is wide enough, the page's headings sit in a sticky rail to the right of the text, with the current section marked as you scroll. When it is too narrow for a rail, they collapse into a Contents popover in the toolbar instead.

The switch between those two is driven by the width of the panel, not the width of the browser window. That distinction is the whole point: the docs column shares its space with the tree, so a 27-inch monitor with the tree open is a wide window around a narrow reading column. A window-based breakpoint would put a rail there and squeeze the prose. Tailwind 4 container queries make the panel measure itself.

Clicking a heading scrolls the article, and only the article. The rail scrolls its own list to keep the active entry in view without moving the document under you.

What came off the pile

Four components were deleted outright in this release: the document modal, the create-folder modal, the old table-of-contents sidebar, and a card-list documentation page nothing rendered any more.

The Markdown editor is still @uiw/react-md-editor, but its styling now comes from the same design tokens as the rest of Archyl. Light and dark are one set of rules instead of a per-theme override block sitting on top of the library's own.

Attachments are unchanged and work exactly as before: drop a file on the editor, paste a screenshot, or use Attach. Images embed inline, everything else lands in the attachments panel, and the paperclip count in the page header jumps you to it. The full story is in Drag, Drop, Done: Files Come to Archyl Docs.

Why bother redesigning a text box

Archyl's job is to keep the architecture model true to the code, and discovery does that part on its own. The prose around the model gets no such help. The ADR explaining why the queue is there, the onboarding page, the runbook: those stay true only because somebody keeps writing them, and people write less when the writing surface fights them.

A modal was a small tax charged every single time. It is gone.

Sign in, open Docs on any project, and press E on a page. There is nothing to switch on and no migration step: your pages, folders and attachments are where you left them. The feature guide is at Documentation & ADRs.