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
- reading columns placed — see below
A warning is not a failure. It is the engine telling you something you would otherwise have found out from a reader.
The two columns a reader needs
Documentation with no navigation is a pile of pages, so the first sync places two blocks for you:
| Block | Column | What it shows |
|---|---|---|
| Documentation tree | Left (sidebar_first) |
The page tree of the version being read |
| On this page | Right (sidebar_second) |
The headings of the open page, as anchors |
Both stay in view while the page scrolls — on a long page a column that scrolls away is navigation you have to scroll back up to reach. The setting is Stay in view while scrolling on each block, and it applies from tablet width up; on a phone a pinned column would eat the screen the page is trying to use.
Whether a page has a table of contents is still the content type's Table of contents setting. The content type owns whether, the block owns where. A page with fewer than two headings shows nothing at all, rather than an empty heading sitting in a column.
Placed once, then yours
This fills an empty seat. Move either block, restyle it or switch it off and the next sync leaves it exactly as you left it — a helper that re-asserted its own idea of the layout every night would be one you have to fight. Delete both and the next sync puts them back, which is how you start over.
Documentation you imported earlier
The columns are placed by a sync. Documentation that was already imported before this existed therefore has none until the next one runs — which may be never, if the repository has not changed. Place them directly instead:
python manage.py docs_reading_columns # every organization
python manage.py docs_reading_columns --organization=erp # just one
Safe to re-run: it reports already placed and changes nothing.
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.
The address a version gets
A version appears in the address with its dots turned into dashes:
/docs/fabrikaerp/… the current documentation
/docs/1-0/fabrikaerp/… version 1.0
Why dashes
Address segments are cleaned character by character and a dot does not
survive. Left alone, 1.0 and 10 would both become /docs/10/… — two
versions at one address, a collision nobody meets until the tenth release
exists.
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.
Who reads a wiki page
Every wiki page carries an Audience choice, and the public web serves the page only to that audience:
| Audience | Who reads it on the web |
|---|---|
| Public | everyone — the page behaves like any published page |
| Customers | signed-in portal customers of the firm (and its employees) |
| Employees | signed-in members of the organization only |
A reader outside the audience gets the same "not found" a missing page gives — nothing reveals that the page exists. The sitemap and the site search follow the same rule: they advertise only what the asker may read.
Two deliberate defaults keep the wiki safe:
- A page that never chose is an Employees page. The default is enforced when the page is SERVED, not only when it is saved — so a page created by any tool that has never heard of the field stays internal rather than leaking.
- Publication stays a separate gate. An unpublished page is invisible to every web reader, whatever its audience.
WHY there is no per-person access list: the platform knows exactly three kinds of reader — anonymous, a customer (a portal account, never an organization member), and an employee. The audience maps onto those kinds; anything finer belongs to a different tool than a wiki.
A [[reference]] in a page's body always renders as its author wrote it
— the name was the author's own text. Following it enforces the target
page's own audience.