Proposal: editor-only draft pages with public visibility filtering

[mrchypark]

Problem

Editors sometimes need to save work in the wiki repository before a page is ready for readers. LeafWiki currently has no unpublished page state, so partially written or embargoed content must be kept outside the normal editing workflow.

I would like to agree on the smallest acceptable draft-page contract before proposing an implementation.

Proposed minimum scope

• Draft state applies to leaf pages only and is persisted in frontmatter as draft: true.
• Only authenticated editors and administrators can read or edit drafts.
• Anonymous and non-editor readers cannot access a draft directly or discover it through the page tree, search, tags, properties, favorites, or link-derived views.
• Publishing and returning a page to draft are explicit state transitions, separate from ordinary content edits.
• Structural operations that could accidentally expose a draft, such as moving or converting it, remain unavailable while it is a draft.
• The editor UI shows the current state and provides explicit publish/draft actions using the existing localization system.

Non-goals for the first version

• Draft sections or inherited draft state for subtrees
• Approval workflows or review assignments
• Scheduled publishing
• Per-user private drafts
• Multiple workflow states beyond draft and published
• General index or concurrency redesign

Visibility contract

The initial implementation should be end-to-end for the agreed minimum scope. It should not merge in a state where draft content is hidden from the main tree but still exposed through another public discovery endpoint.

Questions

1. Is a leaf-page-only draft state acceptable for a first version?
2. Should drafts be limited to editors/admins, or should any authenticated user be able to read them?
3. Is draft: true in frontmatter the preferred persistence format?
4. Which structural operations should remain available while a page is a draft?
5. Are there additional public discovery surfaces that should be part of the initial privacy contract?

If this direction is acceptable, I can prepare a focused implementation against the current main branch.

[mrchypark]

Additional context from the working fork may help evaluate the scope of this proposal.

There are two reference implementations:

• Minimal leaf-page draft implementation (fork PR #2)
• Inherited draft subtree extension (fork PR #5)
• Current fork main, which contains both implementations and is synchronized with the current upstream main

The issue intentionally proposes the smaller PR #2 contract first. Here is how each excluded area relates to the working implementation:

Draft sections and inherited subtree visibility

This is implemented in fork PR #5, but excluded from the initial proposal because it changes the model from a page-local flag to effective visibility derived from every ancestor. The implementation preserves each node's direct draft flag, exposes an additive effectiveDraft value, prevents descendants from overriding a private ancestor, and keeps privacy intact when moving a subtree. It also expands the required filtering and regression surface across tree operations, search, tags, properties, links, assets, revisions, and save projections.

Structural operations on drafts

The minimal implementation blocks move, copy, convert, refactor, slug changes, and child creation for drafts. The hierarchical extension supports children and selected subtree operations with fail-closed behavior. For example, moving an inherited-draft subtree into a public location first promotes the moved root to a direct draft so the move cannot expose it accidentally. I left this out of the minimum proposal so the first contract can remain leaf-page-only.

Approval workflows and review assignments

These are not implemented in the fork. They require a separate workflow and authorization model rather than an extension of the current boolean visibility state.

Scheduled publishing

This is not implemented. It would add scheduler, clock, retry, and operational semantics that are independent of safely storing and hiding a draft.

Per-user private drafts

This is not implemented. The current model is repository-persisted and role-scoped: drafts are shared among editors/admins, not owned by individual users.

Additional workflow states

This is not implemented. The current persistence contract is deliberately limited to draft: true versus published, with explicit transitions between the two.

General index and concurrency redesign

The minimal implementation allows derived indexes to retain draft rows and enforces privacy at every public read/discovery boundary. The hierarchical extension adds stronger projection and concurrency handling where subtree visibility changes require it. The proposal excludes a general redesign, but the relevant safety pieces from PR #5 are available as reference if inherited drafts are accepted later.

My suggested sequence is to agree on the leaf-page privacy contract first, then evaluate inherited draft sections as a separate extension. I am happy to adapt the implementation based on the preferred boundary.

[perber]

Hi @mrchypark,

Thanks for the detailed explanation.

I agree that drafts would be a useful feature, but I would prefer not to include them in v0.13.0. That release already contains quite a few changes that still need to be tested properly, and I would like to get it released soon. :)

Regarding drafts, I think the following approach would work well for a first version:

A page with draft: true is readable and editable only by editors/admins.
For every other user, it should be indistinguishable from an unavailable page and excluded from all public discovery mechanisms.

Publishing and unpublishing should be explicit actions. While a page is a draft, anything that could accidentally make it public should be blocked.

This sounds like a good minimal scope to start with.

I would also like to spin up your existing PRs and test them locally to get a better impression of how the current implementation behaves and looks in practice.

[mrchypark]

Thinking further about the storage model, I agree that these are two distinct cases:

• a new page is itself unpublished; and
• an already-published page has a private working draft while the published version remains live.

I would prefer to treat the second case as part of the core draft feature rather than as a later extension.

My preferred approach would be a Git-tracked sidecar working copy outside the normal page tree, keyed by the page's stable ID. Starting a draft would copy the published content into that working copy; editor saves would affect only the sidecar; and public reads and discovery indexes would continue to use the canonical published Markdown. Publishing would apply the sidecar to the canonical page through the existing save/index path, while discarding would remove only the sidecar.

This would keep the published page untouched and make the working draft durable in Git. The draft namespace would need to be ignored by the page scanner/watcher, and the first version could keep structural operations out of scope and use a base-version check to prevent publishing over newer changes.

Another possible approach would be an internal DraftStore under .leafwiki, potentially reusing the existing revision blob and asset-manifest machinery. That seems simpler and more isolated from the page tree, although working drafts would not be included in the Git backup by default because .leafwiki/ is ignored there.

Would you prefer the Git-tracked sidecar approach, or do you think an internal .leafwiki DraftStore would fit LeafWiki's storage model better?

[perber]

Currently, I think a dedicated DraftStore would be a better fit for LeafWiki.

I am not really tied to Git as the primary source of truth. In fact, I am considering moving more towards the application itself being the source of truth, with Git serving mainly as a content backup and export mechanism.

A DraftStore would also leave more room for future features. For example, if LeafWiki ever supports real-time collaboration or more advanced editorial workflows, application-managed draft state would probably be a better foundation than storing drafts directly in the Git-tracked content tree.

That is not a promise or a direction I want to commit LeafWiki to today. LeafWiki should remain simple. I just want to avoid choosing a storage model now that unnecessarily closes off reasonable options for the future.

[mrchypark]

That makes sense to me. I agree that a dedicated, application-managed DraftStore is the better fit for LeafWiki's direction.

It keeps the published page as the canonical public state without making Git-tracked layout part of the draft contract, while leaving room for future editorial workflows without requiring them now. I will keep the first implementation deliberately small: one shared working draft per page, editor/admin access only, explicit publish and discard actions, and conflict protection when the published page has changed since the draft was created.

I will also keep structural operations, inherited draft sections, approval workflows, scheduling, and real-time collaboration out of this first version.