A familiar story: the code lives in git, and the documentation — “somewhere over there.” In Confluence, in Notion, in a wiki — somewhere you have to deliberately visit and remember that it exists at all. Fix the code — commit and PR. Fix the docs — different tool, different tab, different mood. Guess which half of the work is always “later.”
We solved this fork simply: we removed it. In Meldoc, documentation is plain
.meldoc.md files in your repository. Same git, same PR, same review.
A file like any other
.meldoc.md is ordinary markdown with YAML frontmatter. Two fields are
required: title and alias (kebab-case, unique within the project).
parentAlias sets the place in the hierarchy, workflow — draft or published
status. The CLI is friendly to the lazy: didn’t specify an alias — it derives
one from the filename; didn’t specify a title — it takes the H1 from the body
on first push. Your own custom frontmatter keys won’t be clobbered by sync: the
server owns only its fields, the rest stays as is.
Sync in both directions, no surprises
The basic cycle is like git, only for docs: meldoc pull grabs what’s fresh,
you edit the files, meldoc scan shows what changed, meldoc push sends it.
Diffs and link extraction are computed locally; the server receives files that
are already prepared.
[[alias]] links are extracted from the text on push and travel to the server
with the content — the connection graph updates in sync, links don’t get lost.
How that graph works — I wrote about it in
Graphs in Meldoc. Images from the docs travel
automatically and get deduplicated.
If a file was changed both locally and on the server, the CLI detects the conflict itself. The default is a three-way merge, but you can pick ours, theirs or ask. The habit is the same as with git: pull before editing, push after — and conflicts become rare.
Docs in the PR — divergence is visible, not accumulating
The recommended setup: the docs live in the same repository as the code and get
committed together with it. Branch → edits to .meldoc.md → PR → review →
merge. The documentation passes through the same eyes as the code.
I’ll be honest: Meldoc doesn’t check your code and doesn’t magically highlight stale paragraphs. But when the docs live in the PR next to the change, the divergence is visible and gets fixed in review — instead of accumulating invisibly in a tool nobody visits. It’s a different mechanic of honesty: not “the docs can’t go stale,” but “going stale stops being invisible.”
CI closes the last manual step
After the merge you can push by hand — or not at all: meldoc ci in the
pipeline finds the changed .meldoc.md files from the git diff by itself,
pushes them, and deletes from the server whatever was deleted from the
repository. Before sending — structural validation: duplicate aliases, required
fields, parents. An error — and the pipeline stops before anything flies out.
Conflicts in CI are resolved automatically, without blocking. Ready-made
examples exist for GitHub Actions, GitLab CI, Bitbucket, Jenkins and Docker.
Onboarding a new person takes minutes: clone the repo, meldoc init, log in,
meldoc pull. Everyone has their own token.
Why have a server at all, then
The CLI is autonomous: files, offline, no subscription. You write, commit, push — as usual, without “yet another app” and without depending on a SaaS. The server adds what files lack: search, graph visualization and access for AI agents — more in MCP in Meldoc.
That’s the difference from GitBook, Notion or Confluence: there, syncing the docs is a separate visit to a separate tool. Here it’s part of the PR process you already have. The docs update with the same motion of the hand as the code. Which means — they update.