From 5fe6376caf295feebee48340041f6d4d925ab14c Mon Sep 17 00:00:00 2001 From: Koen Van Exem Date: Mon, 19 Oct 2026 18:47:02 +0200 Subject: [PATCH] docs: record the publication of the four documentation areas MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The four documentation areas are published beneath the home: Allors3 at `/allors3/`, Documents at `/documents/`, Excel at `/excel/` and Immersive at `/immersive/`, each from its own repository by its own Documentation workflow, after the pull requests allors/allors3#286, allors/documents#11, allors/excel#28 and allors/immersive#2 switched their deployment origin to `https://docs.allors.com` and gave each sidebar a first entry back to the home. The decision record becomes Current: its status line, scope and Free-plan sentences describe the published state, the publication steps are recorded as taken on 2026-10-19, with the areas' step completed, and a paragraph says that the custom domain of the organisation site applies to every project site, so that an area needs no domain configuration of its own, and that HTTPS is enforced on the domain. The website instructions describe the published state in the same way. The index is unchanged; its links into the areas now resolve. Validation on 2026-10-19, after the four areas were published: at `https://docs.allors.com`, the home and every area answer 200 for their page, `index.md` and `llms.txt`; `http://` addresses redirect to `https://`; `https://allors.github.io/` and `https://allors.github.io//` redirect to the domain; a browser walks home → area → home for the four areas through the sidebar links without page errors; the published output names nothing outside the public scope. At the repository root: `npm test`, `npm run check`, `npm run build`, `npm run check:links` and `npm run test:browser`; the Documentation workflow validates this pull request. --- README.md | 13 ++++---- .../docs/internals/documentation-home.md | 33 ++++++++++++------- 2 files changed, 28 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 530bf61..d5e9006 100644 --- a/README.md +++ b/README.md @@ -106,13 +106,14 @@ after changing a diagram or component. The [documentation workflow](.github/workflows/documentation.yml) validates the website, without publishing it, for pull requests to `main` and for pushes to `main` and to `docs/` branches. -After publication has been approved, make the repository public, configure its Pages source as -**GitHub Actions** and its `github-pages` environment for deployment from `main`, and run the -**Documentation** workflow manually on `main` with **publish** selected. The validation job must -pass before the workflow deploys. The default manual run leaves **publish** unselected and only -validates. The custom domain and the DNS record are configured outside the workflow; the +The website is published at `https://docs.allors.com/` from the repository's Pages source +**GitHub Actions** and its `github-pages` environment, which deploys from `main`; the repository +is public, as GitHub's Free plan requires for Pages. To publish, run the **Documentation** +workflow manually on `main` with **publish** selected. The validation job must pass before the +workflow deploys. The default manual run leaves **publish** unselected and only validates. The +custom domain and the DNS record are configured outside the workflow; the [documentation home record](src/content/docs/internals/documentation-home.md#publication) lists -the steps in order. +the steps that were taken, in order. The workflow follows GitHub's [custom Pages workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages) diff --git a/src/content/docs/internals/documentation-home.md b/src/content/docs/internals/documentation-home.md index ec98b79..5a83479 100644 --- a/src/content/docs/internals/documentation-home.md +++ b/src/content/docs/internals/documentation-home.md @@ -3,13 +3,12 @@ title: "Documentation home" description: "How the Allors documentation home is built and published: the organisation site and its custom domain, the areas published beneath it, what was reused, how it was validated, and what remains open." audience: "Maintainers" kind: "Decision record" -status: "Planned" +status: "Current" --- -> **Status: Planned.** The website, its Markdown exports and the checks that the documentation -> workflow runs are built and pass. Publication follows the order that the -> [publication](#publication) section lists; this record becomes current when the home and the -> areas are published beneath the shared address. +> **Status: Current.** The home is published at `https://docs.allors.com/` and the four areas are +> published beneath it, each from its own repository, in the order that the +> [publication](#publication) section lists. This record describes the documentation home: the website at the root of the shared documentation address, beneath which the Allors3 platform and the supporting open-source tools @@ -26,7 +25,7 @@ and publication. | Hosting | GitHub Pages, built with GitHub Actions, as the organisation site of the `allors` organisation. | | Address | `https://docs.allors.com`, a custom domain on the organisation site. The repository keeps the name `allors.github.io`; the next section says why. | | Areas | Allors3 at `/allors3/`, Documents at `/documents/`, Excel at `/excel/` and Immersive at `/immersive/`, each published beneath the same address from its own repository by its own documentation workflow. The home links to the areas; it does not build them. `site.mjs` lists them for the sidebar and the link checker. | -| Scope | The home covers Allors3 and the supporting open-source tools. The repository is public once published and holds nothing but the home. | +| Scope | The home covers Allors3 and the supporting open-source tools. The repository is public and holds nothing but the home. | | Version context | The home documents its own `main` and has no product version; the label on its pages says `main`. Each area carries its own version label. | | Publication | The documentation workflow validates every pull request and push. Publication is a manual run on `main` with `publish` selected, as in the areas. | | Checks | The tooling tests, the Astro check, the production build with exports, the link check and the browser tests with accessibility checks, for the base path `/`. | @@ -65,7 +64,7 @@ and on [custom domains](https://docs.github.com/en/pages/configuring-a-custom-do states both rules; consulted on 2026-10-19. The `allors` organisation is on GitHub's Free plan, which publishes Pages from public -repositories only, so the repository becomes public at publication. The home was placed on the +repositories only, so the repository is public. The home was placed on the subdomain `docs.allors.com` rather than beneath the company website on 2026-10-19, so that the documentation publishes independently of that website. @@ -101,13 +100,19 @@ as the [website instructions](../../../../README.md#check-a-change) describe. Th to their Markdown indexes and agent indexes, and the build output names nothing outside the home's public scope. +On 2026-10-19, after the four areas were published, the published website was checked end to end: +the home and every area answer their page, `index.md` and `llms.txt` over HTTPS, plain `http` +addresses redirect to `https`, the `allors.github.io` addresses redirect to the domain, a browser +walks from the home to each area and back through the sidebar links without page errors, and the +published output names nothing outside the public scope. + Automated checks do not establish that an explanation is accurate or clear. The index describes each area in that area's own published words; change the description when the area changes its own. ## Publication -The steps, in this order: +The steps ran in this order on 2026-10-19: 1. Make the repository public. 2. Verify `allors.com` for the organisation, with the TXT record GitHub gives, so that no other @@ -116,10 +121,14 @@ The steps, in this order: `main` with **publish** selected. The home appears at `https://allors.github.io/`. 4. Set `docs.allors.com` as the custom domain of the repository, add the DNS record `docs.allors.com CNAME allors.github.io`, and enforce HTTPS once the certificate exists. -5. Switch the areas' deployment origin to `https://docs.allors.com` and publish them from their - repositories. - -Mark this record Current when the home and the areas are published beneath the shared address. +5. Switch the areas' deployment origin to `https://docs.allors.com`, give each area's sidebar a + first entry back to the home, and publish the areas from their repositories: Allors3, + Documents, Excel and Immersive, each by a pull request of its own, with the same change in + each so that the copies of the tooling stay identical. + +The custom domain belongs to the organisation site and applies to every project site of the +organisation, so an area needs no domain configuration of its own; HTTPS is enforced on the +domain. Each area's decision record describes its own publication. ## Open choices