Documentation sources
Back office → Sourcebook. Everything the engine owns lives in that one group: where a source comes from, what an import is waiting for, and the wiki's housekeeping.
Connecting a repository
A source is a repository plus the organization its pages belong to.
| Setting | Means |
|---|---|
| Name | What this documentation set is called; its vocabulary group takes it |
| Owner / repository | Where on GitHub |
| Path | A subdirectory, when the documentation is not at the root |
| Token | Read access. A private repository needs one; a public one does not |
| Language | Set it when the repository holds ONE language |
| Publication policy | Publish directly, or hold every change for review |
| Automatic sync | Whether a push triggers an import |
Give the token the least it needs
A read-only token scoped to the one repository. A token that can write is a token that can be used to write, and nothing about importing documentation requires it.
Preview before you sync
Every source has a preview. It runs the same planner the sync runs, so what it shows is what an import will do — there is no second code path that could tell you something else.
The preview names, per file, whether it would be added, changed, withdrawn or skipped, and it names what it would create in the taxonomy before it creates it.
A truncated listing refuses to apply
If the repository listing came back incomplete, the plan is marked inapplicable and nothing is written. An incomplete listing is indistinguishable from mass deletion, and importing it with withdrawal switched on would unpublish half a documentation set on the first API hiccup.
Reading the report
Every sync says what it did:
- pages added, changed, withdrawn, unchanged
- images fetched and images reused
- terms created — so an import cannot quietly invent eleven categories
- terms no longer used — reported, never deleted
- links that point at nothing imported
- blocks that were refused, and why
A warning is not a failure. It is the engine telling you something you would otherwise have found out from a reader.
Where imported assets are stored
Assets land in the repository's own tree, mirrored under a folder named after the documentation set:
Manuals/ ← the source's name
assets/
shot.png
i550/terminals.png
i700/terminals.png
Why the tree and not one folder
One flat folder is fine for twenty pictures and unusable for a real manual.
terminals.png from the i550 and terminals.png from the i700 would arrive
as terminals.png and terminals-1.png, and afterwards nobody could say
which machine either belonged to. The repository already answers where a file
belongs — so the store uses its answer.
Identical bytes are still stored once, at the path git showed first, and every page pointing at them links the same file. The tree says where a file lives; it is not a promise that a copy exists at every path naming it.
A source pointed at a subdirectory (docs/) does not rebuild that
subdirectory under its own root — you would otherwise walk
Manuals/docs/assets to find a picture.
A file that disappears
Its page is unpublished, and its content and revisions survive. A mistake at the source costs a re-sync rather than a rewrite.
Releasing a version
Tag main and push the tag:
git tag docs/3.4
git push origin docs/3.4
The next sync imports that version beside the current documentation, and a chooser appears for readers.
A released version is frozen — permanently
It is imported the first time it is seen and never again. That is the whole point: a technician with firmware 3.4 needs the manual as it was when 3.4 shipped. Tags are movable in git; the freeze is what makes the promise anyway. Move the tag and nothing here changes.
To correct a released version, release another one. A frozen manual that quietly changed is worse than one that is out of date, because the reader has no way to tell.
| Never tagged anything | No versions, no chooser, nothing changes |
Tagged docs/3.4 |
3.4 is offered beside current |
| Tag moved afterwards | Ignored — the imported version stands |
| A tag that cannot be read | Reported; the other versions still arrive |
Versions arrive on the ordinary automatic sync, so a tag pushed at five o'clock is readable at five past without anybody remembering a second button.
Proposing a change from the platform
An editor without git can change a page here. The site does not change: the correction becomes a branch and a pull request in your repository, reviewed like any other change, and published when it is merged.
The platform cannot write to `main`
Not "does not" — cannot. If it could, your repository and your site would be free to disagree: one edited here, one edited there, neither wrong, both different. Everything goes through the review your code already goes through.
What is edited
The Markdown, not the rendered page. Each page keeps its source file byte for byte, so a commit is exactly what a writer typed — including the blocks. Editing the rendered page and converting it back would be a guess, and it would lose a construct on the first save.
The write token
Separate from the reading one, and empty by default:
| The source has | It can |
|---|---|
| A read token only | Import. Nothing here can change the repository |
| A write token as well | Also propose changes as pull requests |
A leaked reader cannot open a pull request, and an installation that never
edits in the browser never needs the second token at all. Enter none in the
write-token field to take write access away again.
When the repository moved
If main changed since the page was imported, the change is refused and
reported, and the repository is untouched. Sync the source and make the
change again — somebody else's work is not overwritten because your copy is
older.
A second edit of the same page before the first is merged reuses the same branch and the same pull request. Two branches for one change is how a review queue becomes unreadable.
Review policy
Set a source to review and imported changes wait in Sourcebook → Documentation review instead of going live. Useful when the repository has contributors whose changes you want to see first.
Wiki housekeeping
Wiki changes shows what has been edited recently. Wanted pages shows links that point at pages nobody has written — the most useful to-do list a documentation set has, because every entry is somebody who went looking.