Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
24 changes: 6 additions & 18 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -134,11 +134,11 @@ jobs:
with:
instance: ${{ matrix.language.module }}/asu

# Everything the build profile carries — the structured data, the canonical
# link, the language switcher, the search widget — is easy to lose silently:
# it was missing from the site for a while and nobody noticed. This assembles
# the five builds the way the deploy does and fails when a page comes out
# without them.
# What every page has to carry — the structured data, the canonical link, the
# row of links to the other languages, the notice at the end — is written in
# after the build, and it is easy to lose silently: it was missing from the
# site for a while and nobody noticed. This assembles the five builds the way
# the deploy does and fails when a page comes out without them.
assembled:
needs: build
runs-on: ubuntu-latest
Expand Down Expand Up @@ -183,7 +183,7 @@ jobs:
missing=0

for page in dir/overview.html dir/ru/overview.html dir/appendcolumns.html; do
for marker in 'rel="canonical"' 'asu-fab' 'asu-language-open' 'SoftwareSourceCode'; do
for marker in 'rel="canonical"' 'asu-languages' 'asu-ai-notice' 'SoftwareSourceCode'; do
if ! grep -qF "$marker" "$page"; then
echo "::error::${page} is missing ${marker}"
missing=1
Expand Down Expand Up @@ -234,18 +234,6 @@ jobs:
unzip -qq "artifacts/docs-${code}/${ARTIFACT}" -d "dir/${code}"
done

# Feeds the search widget injected by each project's search.html. Every
# language gets its own index, next to its own pages.
- name: Build the search indexes
run: |
set -euo pipefail

node scripts/docs/build-search-index.mjs dir

for code in ru uk de fr; do
node scripts/docs/build-search-index.mjs "dir/${code}"
done

# Writes the hreflang links into the served HTML, one sitemap covering
# every language, and robots.txt. It has to run after all five builds are
# in place, because that is when the alternates are known.
Expand Down
14 changes: 8 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -201,12 +201,14 @@ deploy and an archive that lives only there disappears with the next one.
`npm run docs:help-versions -- <site-directory> <version>` writes the file the
switcher reads.

Two scripts take an argument and run against a built site rather than the
sources: `npm run docs:search-index -- <site-directory>` writes that directory's
`search-index.json`, once per language, and `npm run docs:finalize-site -- <site-directory>`
writes the `hreflang` links into the served HTML, the sitemap covering every
language, and `robots.txt`. The second one has to run after all five builds sit
in one directory — that is when it can know which pages exist in which language.
`npm run docs:finalize-site -- <site-directory>` runs against a built site
rather than the sources. It writes into every page what the build profile does
not: the structured data, the canonical link, the `og:image` address, the row of
links to the other languages under the breadcrumbs, and the notice at the end
saying the documentation was written by AI. It also writes the `hreflang` links,
the sitemap covering every language and `robots.txt`, which is why it has to run
after all five builds sit in one directory — that is when it can know which
pages exist in which language.

The languages, and every label around the prose, are declared in
`scripts/docs/languages.mjs`. Adding a language is a change to that file and a
Expand Down
Loading
Loading