DocSync: Turning Living Markdown into Trusted Confluence Documentation

Inspiration

Engineering documentation often lives in two places at once. Developers keep the most accurate version close to the code in Markdown, while the wider organization expects polished, searchable pages in Confluence. Copying content between them is slow, and every manual update creates another opportunity for the two versions to drift apart.

We built DocSync after repeatedly facing that gap. Existing publishing workflows could move text, but they did not solve the harder problem: turning source-oriented notes into documentation that a new engineer could understand without changing technical meaning. The challenge became even greater for Korean engineering documents, where literal AI-generated prose often sounds mechanical and where identifiers, API paths, configuration keys, and protocol names must remain exact.

DocSync was inspired by a simple goal: Markdown should remain the source of truth, while Confluence should receive a readable, structured, and verifiably faithful representation of it.

What It Does

DocSync is a dependency-light CLI that manages Confluence Cloud pages and migrates Markdown into production-ready documentation. A project profile can map one file, many files, or an entire directory to an existing page or a newly created child page.

The tool supports two complementary workflows. Direct page commands handle operations such as reading, listing, creating, updating, and deleting Confluence pages. The migration workflow scans Markdown, renders Mermaid diagrams, asks a configured LLM to organize the material, validates the result, produces a reviewable plan, and only then applies the approved change.

For specification-style migrations, DocSync creates a consistent 14-chapter engineering document covering areas such as architecture, components, APIs, business flows, deployment, security, and decisions. Empty chapters stay empty instead of being padded with invented content. Technical identifiers and diagrams are preserved, while Korean prose is humanized for clarity and natural flow.

Safety is part of the user experience. An automated apply requires both an explicit flag and the SHA-256 hash of the reviewed plan:

$$ \text{ApplyAllowed} = \text{ExplicitApply} \land \bigl(\text{ProvidedHash} = \operatorname{SHA256}(\text{Plan})\bigr) $$

If mapped sources have not changed, DocSync skips the expensive planning, LLM, diff, and dry-run stages.

How We Built It

DocSync is written in Go 1.22 and builds as a single binary for Windows or Linux. We deliberately kept the runtime dependency-light so basic page management needs only the executable. Optional tools are invoked only when their capabilities are needed: Codex, Claude, or a local model for document transformation, and Mermaid CLI for diagrams.

The migration pipeline separates probabilistic generation from deterministic publishing:

1. DocSync scans the configured Markdown sources and records their state.
2. Mermaid fences are rendered before the LLM runs and replaced with stable semantic markers.
3. The LLM returns a structured semantic document rather than final Confluence HTML.
4. DocSync validates chapter order, hierarchy, links, protected tokens, formatting density, and diagram placement.
5. One tightly scoped repair pass may replace only sections that failed validation.
6. A deterministic renderer converts the validated model into Confluence Storage XHTML.
7. The plan stores both the semantic model and rendered output; dry-run and apply must reproduce the same result exactly.

This architecture makes the LLM useful without treating its output as trusted input. If a diagram is dropped, duplicated, stale, or moved to the wrong chapter, planning stops. If a repair changes content outside its allowed scope, it is rejected. If the source changes after planning, the plan is no longer valid.

The Windows release includes an installer that verifies packaged files and installs without administrator rights. On first use, the CLI stores API tokens with Windows DPAPI. Project profiles and run history live outside the installation directory, so they survive upgrades. Interactive commands serve individual users, while non-interactive commands return stable JSON for agents and automation.

Challenges We Faced

The hardest challenge was balancing readability with fidelity. A model can produce smoother prose by silently generalizing a rule, altering an identifier, inventing an example, or moving a diagram to a more convenient location. Those changes may look harmless but can make engineering documentation wrong. We addressed this by preserving visible tokens and structural elements with exact multiplicity checks, validating safe links, and allowing repairs to touch only named sections.

Confluence introduced a second set of challenges. Its Storage format is XHTML with platform-specific macros, attachment references, and versioned page updates. Markdown concepts do not always map cleanly to it. We built our own deterministic renderer so headings, tables, ordered lists, code, panels, links, and images remain predictable and properly escaped.

Natural Korean output was another challenge. Correct grammar alone was not enough; the result had to explain unfamiliar systems before introducing jargon, avoid repetitive template phrases, and preserve every technical symbol. We packaged a dedicated humanization skill and applied it during both initial generation and scoped repair.

Finally, a CLI that can update shared documentation must be safe in interactive terminals and automated pipelines. That led to plan hashes, source-state checks, explicit apply confirmation, structured JSON output, secret handling through standard input, and persistent run history.

What We Learned

The most important lesson was that AI-generated documentation needs a contract, not only a prompt. Prompts guide quality, but schemas, deterministic rendering, invariant checks, and fail-closed behavior create trust.

We also learned that documentation structure should follow reader intent. An API chapter needs operations, inputs, outputs, and errors; a business-flow chapter needs triggers, ordered steps, and failure paths. Repeating generic headings across every chapter produces consistency without comprehension.

Another lesson was to keep the source authoritative at every stage. The LLM may reorganize and explain documented facts, but it must not become a new source of truth. That principle shaped diagram handling, token preservation, examples, repair scope, and source-change detection.

What's Next

The next step is to broaden real-world adoption: more project templates, richer migration diagnostics, additional release targets, and deeper end-to-end testing against varied Confluence spaces and documentation styles. We also want to make review feedback more actionable by showing exactly which source rule caused each validation failure.

DocSync already turns a fragile copy-and-paste task into a repeatable publishing workflow. The long-term vision is larger: documentation that stays close to the code, reads naturally for people, and remains safe enough for automation.

Built With

• auto
• confluence
• document
• go
• jira
• markdown
• merge