[lyrixx]

This PR publishes the documentation as a site, on GitHub Pages, built by Zensical.

Commits

1. Indent the lists of UPGRADE-2.0.md and CHANGELOG.md like doc/. GitHub nests the blocks of a list item at the column of its text, Python-Markdown, which Zensical uses, at 4 spaces per level: the site rendered the nested lists and code blocks of these files out of their items. Whitespace only: GitHub renders both files the same, checked by comparing the output of cmark-gfm before and after.
2. Publish the documentation on GitHub Pages.
   • doc/, README.md, UPGRADE-2.0.md and CHANGELOG.md become the pages of the site, with the theme of Zensical: a light and a dark mode, following the system or chosen, a search, a copy button on code blocks, a table of contents that follows the scrolling. The fonts are the ones of the system: no request to Google Fonts.
   • Zensical reads the pages from a single directory, which can't be the root of the repository, and runs no hooks yet. tools/zensical/pages.py, about 70 lines of Python without dependency, copies them to var/docs first, and rewrites the links between the files of the root and doc/. They stay relative paths of the repository: GitHub shows the same files as before.
   • The Documentation workflow builds the site in strict mode, where a broken link or anchor fails, on the pull requests that change it, and deploys it from main. Dependabot updates the Python dependencies of tools/zensical/requirements.txt.
   • zensical.toml stays out of the archive Composer installs.

To preview the site, with the packages of tools/zensical/requirements.txt:

python3 tools/zensical/pages.py && zensical serve

Why Zensical

It is the successor of Material for MkDocs, by its team: Material is in maintenance mode, and MkDocs 1.x is no longer maintained, while MkDocs 2.0, in pre-release, drops plugins. Zensical is at 0.0.70, released often: requirements.txt pins it, and Dependabot proposes the updates.

Before merging

• Settings → Pages → Source: "GitHub Actions". The deploy job fails until then.

Known limits

• The link to the repository, in the header, shows the latest release and the stars, which the browser of the reader asks the API of GitHub for.
• zensical serve shows the copies of pages.py: a change to the pages needs it again.
• The copy button copies the $ of the shell examples too.
• With startinline, a <?php at the start of an example is colored as text.

On a phone, in the dark mode