documentation.eccenca.com

Shared repository of the eccenca Corporate Memory documentation.

If you consider to contribute to this project, please have a look on CONTRIBUTING.md

The site is built with Zensical, the successor to Material for MkDocs. Run task build to build into site/ and task check for the full check suite.

For previewing there are two tasks:

Use serve while writing prose. It rebuilds into site/ on every change, which overwrites what the post-build steps produced, so it loads glightbox and the ResizeObserver polyfill from a CDN instead of from the vendored copies - invisible on screen, and nothing downstream trusts a site/ left behind that way.

task public:preview is the one to run before publishing: it deploys into a throwaway copy of the published branch, serves that on port 8002 (override with PORT=…), and deletes the branch again when you stop it. Because it is public:deploy pointed at a scratch branch, what it serves is what publishing produces - versioned URLs, the version selector, the outdated-version banner and the root redirect included.

Two Material for MkDocs features are not yet implemented by Zensical and are therefore missing from the output. They are tracked in tools/check_zensical_output.py, which reports them as PEND on every build and prints a banner as soon as one starts working:

Everything else Zensical leaves out is reimplemented here and guarded as a required check - the build fails if any of it regresses:

Serving these from our own origin is what keeps visitor IP addresses away from third parties - but it also makes us their redistributor, so each copy carries its licence:

The files are byte-identical to their upstream builds except for a prepended /*! … */ licence banner, which is the notice MIT asks to travel with a copy; the full licence text sits next to each one where upstream ships it. Three of the URLs Zensical bakes into its bundle are deliberately not vendored - mermaid, Ace and Pyodide are unreachable for this corpus, and localize_bundle_assets.py fails the build if a page ever starts using one.

The fonts under tools/pdf/fonts/ are not served to visitors: task pdf embeds them in the PDF, and they are vendored so the build does not depend on what is installed on the machine running it. They are unmodified upstream files, and each font directory carries the full licence text. They keep their own licences - the Creative Commons licence below covers the documentation, not these fonts.

Tag listings and the links from each page's tag chips to them are native as of Zensical 0.0.58. The local stand-ins for both - a post-build renderer and a tags.html partial override - are gone; the Markdown sources still carry Material's own <!-- material/tags --> markers, which Zensical now expands itself.

check-zensical-output keeps guarding the result: it asserts that tag chips link somewhere at all and that every anchor they point at exists on /tags/. A slug mismatch between a chip and its listing would otherwise ship as hundreds of dead links rather than fail the build.

task check:navigation additionally fails if nav.yml no longer matches the docs/**/.pages files, which remain the source of truth for navigation (task update:navigation regenerates it).

task check:yamllint lints every YAML file in the repository, including the extensionless .pages navigation sources, against the committed .yamllint. That config is committed rather than left to a user-level one so a local run and a CI run apply the same rules - without it CI would fall back to yamllint's stricter upstream defaults.

See tasks/handoff.md for the full migration notes.

Copyright © 2025 eccenca GmbH

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.