Publication, downloads, and maintenance

The publication is authored in Markdown under DOCS/. HTML pages, navigation, search, downloadable editions, and machine-readable indexes are generated from that source. A second independently maintained prose version is not required.

site.json supplies the title, author, publisher, edition, canonical domain, repository, and reading sections. The template uses text-based JCB architecture headings and retains the small VDM mark. System-following light/dark mode and an explicit user override are part of the reading interface.

Every article has an exact Markdown equivalent#

An article at DOCS/compiler/binding.md is published as an HTML page at /compiler/binding/ and an exact source alternate at /markdown/compiler/binding.md. The page's Markdown action and alternate metadata point to that source. The build preserves the Markdown bytes, including front matter, rather than reconstructing prose from HTML.

Article-to-article links in source use relative .md paths. The renderer resolves them to the correct HTML destinations while the source remains usable as a connected Markdown corpus. Heading anchors, descriptions, and reading order are checked during publication.

Complete editions and indexes#

The build produces:

The article-level Markdown alternate remains the exact source. The combined reading edition can add separators and rewritten cross-article addresses for usability; it is not substituted for the source hash of an individual article.

Build and inspect locally#

From a checkout of the publication repository:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt -r requirements-dev.txt
python -m unittest discover -s tests -v
python examples/demo.py
python scripts/vendor.py
python scripts/prepare_evidence.py
python scripts/build.py
python scripts/check_site.py
python -m playwright install chromium
python scripts/browser_check.py
python scripts/archive.py
python -m http.server 8000 --directory site

The vendor step acquires the pinned browser dependencies and records their hashes. Mathematical rendering uses the selected MathJax SVG output; diagrams use the pinned Mermaid bundle. The publication does not require a hosted third-party rendering service for each reader's equation or diagram.

Pull-request validation and production deployment#

The workflow archives the reviewed source before running the checks. It then tests the executable mechanisms and publication tooling, runs the demonstration, builds the site, checks article/Markdown consistency, and tests browser behavior. Review artifacts include the built site archive and validation evidence.

Pull requests do not deploy. Only a successful build of main reaches the GitHub Pages deployment job. The maintainer reviews and merges the branch; editorial work does not independently change the production domain or release the compiler.

Domain configuration#

The intended address is architecture.joomlacomponentbuilder.com. The repository generates its canonical addresses and a descriptive CNAME artifact from site.json. With a custom GitHub Actions Pages deployment, GitHub's repository Pages setting—not that generated file—controls the custom-domain association.

The maintainer should configure/verify the custom domain in GitHub Pages and create the subdomain's DNS CNAME pointing to joomengine.github.io, without a repository suffix. HTTPS activation and DNS validation are hosting operations separate from the source rewrite. Follow the official GitHub custom-domain instructions.

Do not leave an unclaimed DNS alias pointing at a disabled Pages site. Retaining an old address as a redirect requires control of that old host; the new publication cannot create an HTTP redirect on another domain merely by changing its canonical URL.

Edition history and maintenance#

The earlier manuscript remains in repository history at c833d39f606d2b237eeaecbd5c41a350dde823cb. This edition replaces its framing and article structure while retaining useful publishing infrastructure, attribution, and research references.

When implementation changes, update the affected source correspondence, worked trace, and mathematical assumptions together. When only a publication URL changes, update the canonical configuration, citation metadata, downloads, and generated indexes consistently. Stable article paths and explicit edition records make those changes inspectable.

The verification guide distinguishes publication integrity from source, artifact, and runtime verification. A successful site build establishes that the explanation is published correctly; it is not a substitute for testing the compiler's generated applications.