Versioning and i18n

mike is a Python utility, written for MkDocs, that deploys several versions of a site to a Git branch (normally gh-pages). Its idea is that a version, once built, is never built again: older versions stay as generated files on the branch, so they cannot be broken by changes in the generator. Every mike deploy creates a new Git commit on the branch that replaces the folder of that version and leaves the other versions untouched. The layout it recommends is a folder per <major>.<minor> version plus optional aliases such as latest or dev. A versions.json file lists the versions, their titles and their aliases, and the theme reads it to draw the version selector.

The figure shows the result on the publishing branch: one folder per version, an alias that points to one of them, a root page that redirects to the default alias, and the list of versions that the selector reads in the browser.

The upstream mike calls MkDocs. Zensical documents a fork of mike, hosted in the repository of the Material for MkDocs author, that keeps the commands and the configuration of mike working for Zensical sites. The documentation is explicit about its purpose: the integration is transitional, the fork is maintained until Zensical has native versioning, and native versioning is meant to support more deployment targets and more versioning strategies. The fork is based on mike 2.2.0 and receives compatibility fixes but no new features, so it is a bridge for projects that already publish versions with mike and not a base to build new tooling on.

The fork is not on PyPI under the name mike: the documentation installs it directly from GitHub, which means that git must be available. The command provides the same mike command as the original package.

Source: Zensical docs: Versioning with mike

This installation was not executed here: it downloads and installs code from a Git repository outside PyPI, which was not approved in the environment used to check this page. Because of that, the mike deploy, mike set-default and mike list commands below are described from the documentation of Zensical, of Material for MkDocs and of upstream mike, and were not run against Zensical.

The Zensical page asks you to keep the existing mkdocs.yml and to enable the selector as in Material for MkDocs, with the extra.version key. The settings of the default version, the visible aliases and the outdated-version warning keep working. The Material for MkDocs guide lists them:

Source: Material for MkDocs: Setting up versioning

site_url must be set explicitly because every version is deployed as a sub-folder of it (for example https://example.org/pocket-units/0.2/), and the selector uses it to keep the reader on the same page when the version changes. That switch happens in JavaScript, so it cannot know ahead of time whether the same page exists in the other version.

The same values can be written in zensical.toml as a table. Both forms were built with Zensical 0.0.72 and in both cases the build finished with "No issues found" and the page configuration embedded in the generated HTML contained the same data:

Source: Zensical docs: Versioning with mike

The selector itself is not part of the generated HTML: it is built in the browser from versions.json, so a plain zensical build shows no selector. The documentation of Zensical describes only the mkdocs.yml form for the fork, so which configuration file the mike command itself reads in a project that has only zensical.toml is not specified there; for a first migration keep the mkdocs.yml next to zensical.toml as the page recommends.

The list of supported MkDocs plugins includes mike since Zensical 0.0.30, and documents these settings. They are the settings of the upstream plugin, except that css_dir and javascript_dir are ignored because Zensical supplies the selector assets itself.

Source: Zensical docs: MkDocs plugins

The commands are those of upstream mike. A typical release publishes a version together with the alias that readers use, moves the alias when it already points elsewhere, and pushes the branch:

Source: Material for MkDocs: Setting up versioning

The documentation of Zensical advises to keep the current MkDocs deployment in place while testing the same setup with Zensical, and to switch the build environment and the deployment workflow only after the generated versions, aliases and redirects have been checked. The migration path as a whole is in Migrating from Material for MkDocs. For the publishing workflows that do not use versions, see Validation and publishing.

Because the roadmap lists folder-based versions, a manual alternative is possible today: build each release into its own folder with site_dir and site_url, and publish the folders together. Zensical does not provide a selector for that arrangement, so the links between versions have to be written by hand. The comparable features of the other tools are described in Antora versioning and Docusaurus versioning, where versions are part of the tool.

The interface of the theme (search placeholder, navigation labels, "back to top", date labels and so on) is localised. The documentation says that, with the help of contributors, the templates exist in more than 60 languages, and the language is chosen with one key:

Source: Zensical docs: Language

In mkdocs.yml the same setting is theme.language: de. The build with Zensical 0.0.72 set the lang attribute to de on the html element, translated the visible texts (the search label became "Suche") and did not change the content of the Markdown pages, which stay in whatever language they were written in.

A project has exactly one language. The documentation explains that HTML allows a single language per document, which is why Zensical supports a canonical language for the whole project and not a language per page. The default is en. The language codes of the supported list use the ISO 639-1 form (de, fr, ja) and, in a few cases, a region or script (pt-BR, zh-TW, zh-Hant, ku-IQ). Most entries are marked complete. At the time of the check, Burmese (my), Georgian (ka), Sinhalese (si), Tagalog (tl) and Kurdish Soranî (ku-IQ) had missing translations (between 3 and 27 strings).

An unknown code stops the build with a template error instead of falling back silently. With the language set to xx the build failed with:

The search language is derived from theme.language as well, and the search interface itself is currently available in English only. Both points are described in Search.

The reading direction is deduced from the language: Arabic, for example, gives right-to-left and English left-to-right. It can be forced with theme.direction, whose values are ltr and rtl:

Source: Zensical docs: Language

The result was checked on the body element of the generated page. A build with the language ar and no direction produced a body with dir set to rtl; a build with language en and direction rtl kept lang at en and also produced dir set to rtl; a build with English or German and no direction produced dir set to ltr.

To change some of the texts of a language, the documentation uses a template override. Create a partial in the partials/languages folder of the overrides directory (set with custom_dir, see Theming and customization) that imports the translations of the language and of English, defines the changed keys, and selects the partial with the language custom. English is always the fallback, because it is the default language of the theme.

Source: Zensical docs: Language

This pair of files built with Zensical 0.0.72 without errors; the generated page had lang set to de and German interface texts, taken from the imported language. The overridden keys concern the dates of the page source and are only used when that feature is enabled.

Zensical translates the interface and not the content. For a documentation site in several languages the documented mechanism is a language selector in the header, filled from extra.alternate. Each entry points to a site that was built for that language, possibly on another domain or built by another tool.

Source: Zensical docs: Language

Every entry needs three properties. name is the label shown in the selector and must not be empty. link must be an absolute link: with a domain it is used as written, without one the domain of site_url is prepended. lang is an ISO 639-1 code used for the hreflang attribute, which helps search engines to find the other languages. The build with Zensical 0.0.72 wrote these elements for the example above:

and a md-select list in the header with the two names, "English" and "Deutsch", as links with hreflang. In that output the links were left as the relative-looking paths /en/ and /de/, so the generated markup does not show the domain of site_url being prepended; check the final URLs in a deployed site.

Because there is one language per project, the practical layout is two (or more) Zensical projects, one per language, each with its own zensical.toml, docs folder and theme.language, built into the sub-folders that the link values point to. The selector connects them, and hreflang tells search engines that the sites are translations of each other. Nothing in Zensical keeps the pages in sync: moving or adding a page in one language does not warn when the other language lacks it.

Docusaurus, in contrast, has locales, translation files and per-locale builds in the tool itself; see Docusaurus internationalization.

The roadmap of Zensical is directional and gives no delivery dates. Under "Internationalization" it lists the work for projects that need flexibility in how they organise, translate and publish content:

Under "Versioning" the same roadmap lists Git-based versions, folder-based versions, selective publishing and focused rebuilds that avoid rebuilding unchanged content. None of these items is available in 0.0.72, so the plugin list of the compatibility documentation, the mike fork and the language selector are what a project can use today. Until the native features exist, the documentation of Pocket Units in several languages and versions is a set of separate builds tied together by links.