Draft in private, publish on purpose
Published · v1.0 · Published 1 August 2026
Narrated with OpenAI.
I wanted somewhere simple to turn the ideas in my head into writing. I did not want to build a publishing product before I had learned to publish. My focus is building products, so I chose a documentation site: Markdown files, a small amount of configuration and a browser preview that shows the work where it will eventually live. I use Codex and Claude to research, draft and review the writing. Material for MkDocs gives me the lightweight surface around it.
The tool is not the important part. The harder question is editorial: how do I keep a draft useful while I am working on it, then publish it only when I mean to? The workflow I am building is deliberately simple. Folders hold the editorial state. Moving a file records the decision to publish.
The branch is not the boundary
A permanent draft branch sounds tidy. Draft work lives there. Finished work moves to main. Production deploys from main. But writing rarely moves in one clean direction.
Site design changes while an article is in flight. Two drafts may share a source note. A published article may need a correction before another draft is ready. Long-lived branches turn those ordinary changes into merge work. Eventually, the branch becomes a second version of the site.
The useful boundary is not Git history. It is editorial state.
This repository already names and enforces that boundary. Work in progress lives in drafts/. Approved writing lives in published/. Moving a file between those directories is the deliberate publishing decision, recorded in a normal commit.
One repository, two views
The same source tree should produce two different views.
| View | Includes | Who it is for |
|---|---|---|
| Preview | Site pages, published articles and selected drafts | Me while writing and reviewing |
| Production | Site pages and published articles only | Everyone visiting adamharris.ai |
The folders define an article's editorial state. drafts/ holds work in progress. published/ holds approved writing. Moving a file is the editorial decision.
The local preview script decides which drafts I see. It copies selected drafts into a review site, adds a visible draft notice and marks them noindex. The production build accepts published/ only and fails if draft content or review-only controls reach its output.
Build contract
Both views use the same theme, navigation and components, so a draft review looks like the page a reader will eventually see. The production-only build makes the editorial boundary mechanical and testable.
Publishing is a file move
Rendering is not publishing. Pushing a branch is not publishing. An article becomes public when its editorial gates are complete and its source moves from drafts/ to published/.
Workflow How an article moves from draft to publication
flowchart TB
topic["Topic or research note"] --> draft["drafts/<br/>Article in progress"]
draft --> preview["Preview build<br/>Private review"]
preview --> gate{"Editorial gates complete?"}
gate -->|"No: revise"| draft
gate -->|"Yes: move the file"| published["published/<br/>Approved article"]
published --> commit["Publish commit<br/>Merge to main"]
commit --> build["Production build"]
build --> live["adamharris.ai<br/>Live article"]
classDef private fill:#f7f4ed,stroke:#8b928f,color:#18211f;
classDef decision fill:#f7f4ed,stroke:#e85029,color:#18211f,stroke-width:1.5px;
classDef public fill:#f7f4ed,stroke:#18211f,color:#18211f,stroke-width:1.5px;
class topic,draft,preview private;
class gate decision;
class published,commit,build,live public;Branches describe work in progress. Moving the file from drafts/ to published/ is the publishing decision.
For this site, those gates are concrete. I write the opening. The article gets an adversarial pass in a fresh session. Private supporting material stays outside the public repository. The final source moves into published/, and the publish commit records the decision.
With the production guard in place, merging that commit to main can trigger deployment. The deployment is mechanical because the editorial decision has already happened.
Publication is not permanence
The first public version is a point in time, not a promise never to improve the work. A correction, stronger source or clearer explanation can update the same article. The original publication date stays visible. The revision gets a new date and a short explanation of what changed.
That is different from quietly replacing the argument. If the central thesis changes, the honest move is a new article that links back to the original. Readers can then see both the path of the thinking and the reason it changed.
Git retains the exact source history. The page only needs to show when the article was first published, when it changed and a short explanation of any material revision.
Branches still have a job
Short-lived branches still help when a change needs isolation. A substantial site redesign can use site/<change>. An article that needs a separate review cycle can use article/<slug>.
Those branches describe work in progress, not permanent editorial states. They merge or close. A delivery branch may exist for site changes, but it does not decide whether an article is draft or published. The folders remain the editorial boundary.
The privacy line
Keeping a draft out of the generated site does not make its source private. If the Git repository is public, every committed file in drafts/ is public too.
That leaves a simple choice. Keep the repository private, or keep drafts in a separate private content repository. For a personal writing workspace containing unfinished arguments and supporting notes, private by default is the simpler rule.
The public site can still be fully public. Its source workspace does not need to be.
When a workflow becomes reusable
This started as a way to solve my own problem. If the workflow keeps working, and I can see where it holds up and where it fails, parts of it may be useful to other people. I do not want to publish a pile of prompts and files without the reasoning that makes them useful. The method should come with the problem it solves, the assumptions it makes and the limits I discovered by using it.
That is what I mean by a Field Kit. The article carries the experience and reasoning. The kit teaches the method. A template can provide the starting structure, skills can help Codex or Claude follow the workflow, and tools such as the listening extension can handle the parts that need working software. Not every kit needs all of those pieces. Each part should earn its place by surviving the work first.
The working loop
I research and draft with Codex and Claude, review the work in the same browser and design where it will eventually be read, and keep it private while the argument is still forming. When I am ready to stand behind it, I move the file from drafts/ to published/.
Drafting can stay exploratory. Publication is the point at which I decide the work is ready to own in public.