Why Zellij exists
Documentation tools make documentation. Site builders make sites. A product needs both, and keeping them in two systems is how they drift apart.
The problem is the seam, not either half
MkDocs will give you a good manual. A site builder will give you a good landing page. Run both and you have two content repositories, two deploy pipelines, two sets of brand decisions, and a navigation bar that exists twice and agrees about half the time.
Zellij's premise is that these are the same site. The same folder holds the landing page and the manual, the same theme styles both, one build produces them, and the top navigation is declared once.
What it assumes
These are the opinions. Everything else is configuration.
Content is plain text
YAML and Markdown, in a folder, in version control. Reviewable in a pull request by someone who does not write code.
A fixed vocabulary beats freedom
Nineteen sections, not arbitrary layout. Constraint is what keeps every page looking like it belongs to the same site.
An engine, not a generator
Nothing is scaffolded into your repository, so there is nothing to re-merge when the engine improves.
Broken content fails the build
A dead nav link, a missing section file, an unknown icon name — all build errors. Visitors are not the validation layer.
Accessibility is not a mode
Reduced motion is honoured everywhere, focus is visible, dialogs use the platform's own, and contrast is checked per theme.
Fast by construction
Static generation, build-time syntax highlighting, a search index that loads on first use and not before.
How a site usually goes wrong
Each of these is a decision Zellij makes for you.
Week 1
The landing page is beautiful
Someone good spent a fortnight on it. It is hand-written and unique.
Month 3
A second page appears
It reuses two thirds of the first page, copied. The two now differ in spacing and nobody knows which is right.
Month 6
The docs move to another tool
Different navigation, different fonts, a different idea of a link.
Year 2
Nobody edits either
Changing copy means touching code, so marketing files a ticket and the page stays wrong.