Skip to content

docs: record the publication of the four documentation areas #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
koenvanexem merged 1 commit into from
Oct 19, 2026
Merged

docs: record the publication of the four documentation areas #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
33 changes: 21 additions & 12 deletions src/content/docs/internals/documentation-home.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 `/`. |
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand All @@ -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

Expand Down
Loading