The site is built with Hugo and published with GitHub Pages. The homepage is
special, all its contents are in its layout (layouts/index.html).
Needs Hugo 0.167.0 or newer, the standard edition (with an older binary Hugo warns, and the output check fails the build), and Python 3 (standard library only).
_tools/hugo/build.sh # build into public/, then check the output
_tools/hugo/build.sh serve # hugo server with live reload
Nothing adapts the pages before Hugo reads them: the build is Hugo, and the check of its output.
The script changes to the repository root from its own location, so it works from any directory (hugo.toml and its
mount sources are relative to the root). HUGO=/path/to/hugo names the binary when it is not on the PATH; flags
after serve go to hugo server. The whole build takes seconds.
serve renders in memory, so public/ keeps the last build. An edit of a page, a file beside it (a snippet of the
file shortcode, an image), a data file, a template or src/ shows without a restart.
After Hugo, the build runs _tools/hugo/check-output.sh on public/, with the output of Hugo in a temporary file.
Hugo exits 0 and writes a smaller site when a mount source is missing, a data glob matches nothing or a layout is
missing, so the check fails the build when: public/pages/docs has another number of .html files than pages/docs
has .md files; one of the pages and files that every deployment needs is missing (the home page, 404, the docs, learn,
about, faq and deps pages, sitemap.xml, robots.txt, CNAME, the stylesheet and scripts, a font); a rule block of the
model 109 grammar has lost its id; the sitemap has fewer than 3000 entries; Hugo logged a warning or an error; or the
text {:, or a line that starts with {. or {# outside <pre>, is left in a generated page. That last check fails
the build of a generator that writes a form that Hugo does not read.
The tools have tests: python3 -m unittest discover -s _tools/hugo/tests (the workflow runs them before the build).
Markdown is converted by Hugo's Goldmark, a CommonMark parser. Its settings in hugo.toml: raw HTML is enabled, block
attributes work ({#id .class} on the line after a paragraph, {#id} after a fence's language), the typographer
writes smart quotes and dashes, a bare URL is not a link, and void elements are written <br />. Fenced code and
headings go through render hooks (layouts/_markup/): a fence renders as the wrapper that the stylesheet, src/main.js
and Prism select on (div.language-X.highlighter-rouge > div.highlight > pre.highlight > code), and Prism highlights
it in the browser. Page logic is in shortcodes: {{< file >}} includes a file relative to the page, {{< param >}} and
{{< site-version >}} print versions, {{< dist-version >}} and {{< platform-component >}} read the version data.
url: in the front matter is the page's address.
- Hand-written pages:
index.md,404.md,pages/*.md,pages/tutorials/**,pages/tuts/**. The files inpages/tutorials/**that are not Markdown (models, images, data) are copied as they are. - Generated documentation:
pages/docs/**is written by the docs generator of alan-tools and committed. Never edit it here. The generator writes the form that Hugo reads, and the build adapts nothing; its contract is below. _data/dist/<platform version>/versions.jsonare copies of the publishedversions.jsonfiles; the versions repo writes them on release (publish.sh), do not edit them by hand._data/versions.jsonis hand-managed: the platform version, itsalanscript, and the versions of the platform components (model, interface, project-build-environment). TheRELEASE.mdfiles beside theversions.jsonfiles are not data: the data mount inhugo.tomltakes only.json,.ymland.yamlfiles, Hugo would fail to load them.deps/(the dependency graph) is written by CI as well.- Layouts and styles:
layouts/(partials, shortcodes, render hooks, and the templates ofrobots.txtandsitemap.xml),src/,assets/. The documentation tables select their pages by front matter (origin,version) and are rendered once per type and version (partialCached). hugo.tomlmounts these directories where Hugo wants them: the Markdown underpages/,pages/docs/included, as content;index.mdas the home page placeholder and404.mdas the text of the 404 page;assets/,deps/,CNAMEandfavicon.icoas static files;_data/as data. Everything else underpages/(underpayload/) andsrc/are assets, whichlayouts/partials/static-payload.htmlpublishes at their paths in the repository: a static mount ofpages/would makehugo servermiss every edit of a page (seehugo.toml).robots.txtandsitemap.xmlare not static files but templates, andsrc/main.cssis built fromsrc/css/, so none of the three is in the repository as a file. The directories are laid out as the tools that write into them expect (CI writespages/docsanddeps/, the versions repo writes_data/dist/), which is whyhugo.tomlmounts them.- The stylesheet is plain CSS: no Sass, so the build needs only the standard Hugo binary. Its parts are the files in
src/css/, numbered in the order of the cascade:10-fonts.css(the font faces),15-tokens.css(the design tokens: colours, type scale, spacing, widths, radii, shadows, durations and stacking levels, as custom properties that the other parts use),20-theme.css(the base styles of the elements),30-main.css(the page layout),35-components.css(the shared components: buttons, cards, tags, callouts, figures, code blocks and the colours of highlighted code),40-home.css(the home page),50-header.cssand60-footer.css(the site header and footer),70-docs.css(the language tables, the archive and the document switcher),80-release-notes.css,90-hub.css(the Learn, Documentation, About and FAQ pages) and95-index.css(the page index).layouts/partials/stylesheet.htmlconcatenates them in the order of their names into/src/main.css, as they are, comments included: a minifier would rewrite values into equivalent forms, and the server compresses the file anyway. A new part gets a number that puts it at its place in that order. The fonts, Instrument Sans and IBM Plex Mono, are served fromassets/fonts/with their licenses;10-fonts.csssays where the files come from. - The order of the components in the version tables is configuration, not data: Hugo hands the data files over as maps
and a range over a map goes in sorted key order, so
[params.order]inhugo.tomllists the platform components and the system types in the order that the data files use, andlayouts/partials/ordered-keys.htmlfollows it. A key that a list does not name follows in sorted order.
A page under pages/docs is written in the form Hugo reads. What the build relies on:
- The front matter carries
url: "/pages/docs/<path without .md>.html"(the path keeps the spaces of directory names such asclient bindings) and, when the page has an index,toc: true. The layouts and the toolchains' deep links rest on both. - No kramdown attribute lines (
{: ... }) and no1. TOC/{:toc}marker. The id of a grammar rule is anidon the<div class="language-js highlighter-rouge">of its block; the id of an example is{#id}on the line after the paragraph that introduces it. - Inside a rule block, a
<that starts no tag the generator writes there (span,a,div,pre,code) is written<, so that grammar text such as<begin>shows as text. A blank line follows a block when text follows it, because Goldmark ends an HTML block at a blank line. - Prose is written for CommonMark: a fence that opens in a blockquote is prefixed with
>on every line, a link destination with a space is wrapped in<...>, the quotes of a quoted word are written as‘and’.
check-output.sh fails a build whose pages still contain {: or a line that starts with {. or {# outside <pre>.
Other systems link to the pages, so the addresses must not change. The toolchains ship
prefix: https://alan-platform.com/pages/docs/ in platform.json and the tools deep-link to
/pages/docs/<origin>/<version>/<language>/grammar.html#grammar-rule--<rule>; the forum and the ./alan script link
there too. Therefore the pages under pages/ keep .html (uglyURLs for that section; the home page stays at /),
disablePathToLower = true (directories such as client bindings and images_IDE keep their space and case), the
hand-written pages whose address differs from their file name set url: (/docs/, /learn/, /about/, /faq/,
/docs/archive), and the ids grammar-rule--X and example--X stay as they are.
.github/workflows/pages.yml has three jobs.
buildinstalls Hugo, runs_tools/hugo/build.sh(so the check of the output too) and uploadspublic/as the Pages artifact. It runs for a push tomaster, for a pull request tomasterand for a manual run (Actions, Pages, Run workflow, on any branch).deploypublishes the artifact with GitHub Pages and runs only for a push tomaster. The push of the documentation CI job publishes too. A pull request or a manual run stops after the build, with the artifactgithub-pages(a tar ofpublic/) attached to the run: download it from the run page to inspect it. A deployment that failed after a push is redeployed by re-running that run; a manual run does not deploy.notifyruns when a push failed, inbuildor indeploy. GitHub emails only the person whose action started a failed run, and the documentation pushes come from the GitLab CI user, so the job opens an issue titled "Site build failed: / " with the commit, its author and the run, assigned togjkunstand labelledsite-build. While an issue with that label is open, a new failure is a comment on it, not a second issue. Close the issue when the site builds again.
The Pages source of the repository is "GitHub Actions" (Settings, Pages,
https://github.com/alan-platform/alan-platform.github.io/settings/pages). Hugo is downloaded from its release and
checked against a SHA-256 pinned in the workflow; to update Hugo, change HUGO_VERSION and HUGO_SHA256 together (the
checksum is in the checksums.txt of the release).