Support and compatibility¶

This page is for anyone deciding whether prodockit fits a project or checking whether their platform and tool versions are covered. It describes the public support and compatibility boundary; implementation-specific constraints remain in Contributor internals.

Maturity and stability¶

prodockit is currently classified as Alpha and uses pre-1.0 versions. Its document features and publishing tools are functional and tested, but there is not yet a formal, versioned public API stability contract. A pre-1.0 upgrade can therefore include a breaking change when the change is needed to make the public configuration consistent. Such changes are identified in the release notes.

The future stability contract is tracked in issue #7.

Required versions¶

Installing prodockit installs these Python dependencies automatically:

The current test matrix covers Python 3.10, 3.11, 3.12, 3.13, and Python 3.14. The documentation build currently pins Zensical 0.0.64 and pymdown-extensions 12.0.1 so changes to either renderer arrive as reviewed version changes rather than silently altering published output.

Table 54.1 gives the supported dependency ranges and explains why each boundary matters.

The dependency boundaries in Table 54.1 are tested rather than inferred. PyMdown Blocks is particularly important when evaluating the authoring model. The numbered-steps and directory-tree extensions are specialised Blocks API implementations, so their slash fences, nesting rules, and option layout follow PyMdown's block syntax. They are not separate parsers that only resemble it.

Pandoc, WeasyPrint, Node tools, fonts, and other optional publishing requirements depend on the output being built. See Requirements and dependencies for that complete tool-by-tool boundary.

Platforms and test depth¶

The platform testing described here covers Linux, macOS, and Windows. Bootstrap has now completed manual end-to-end testing on Ubuntu Linux, Windows, and macOS against the University of Surrey's GitLab (gitlab.surrey.ac.uk), GitHub.com, and GitLab.com.

Two complete document workflows were exercised:

1. Start a new document: prepare the machine with bootstrap, create a new document repository on the selected host, and reach a working local build.
2. Adopt an existing document: take an existing online repository, install it locally on the prepared machine, and reach a working local build.

This is practical integration testing across the three operating systems, three hosts, and both common starting points. It verifies that the stages work together in real environments, beyond unit tests or inspection of generated commands. It is not an automated cross-platform full-suite regression matrix, however:

Table 54.2 distinguishes routine platform coverage from the deeper tests run for platform-specific installers.

Windows ARM64 supports the non-PDF Prodockit workflow, including citation-enabled website builds. Its project-local Pandoc uses the reviewed official Windows x64 executable through Windows 11's app emulation while the cache retains its ARM64 identity. Local PDF generation remains unsupported; generate the downloadable PDFs on a supported GitLab runner.

The Python Mermaid renderer is supported on Linux x64 and ARM64, Windows x64, and macOS ARM64. The audited quickjs-ng version does not publish compatible Windows ARM64 or macOS Intel x64 wheels, and normal installation must not compile or download another runtime. Those architectures can use ordinary Prodockit website features but are not supported for Mermaid PDF rendering. Windows ARM64 is not part of the automated test matrix.

Table 54.2 distinguishes automated regression coverage from manual bootstrap exercises. The installed-wheel adoption and bootstrap jobs build the candidate package afresh. Adoption tests TOML and YAML projects with the core, Mermaid-only, maths-only and combined component choices. They also check that a second apply changes no files. This narrow cross-platform matrix complements rather than replaces the full Python test suite. Bootstrap uses local bare repositories instead of a live host to exercise all four combinations of Surrey GitLab or GitHub and new or existing repositories. The GitHub new-repository route starts its first Bootstrap pass with old VS Code, Git, Pandoc, Node.js, npm, editor extensions and, on Ubuntu, Pango and Chromium, then accepts every offered upgrade before creating the project. A fifth, Surrey-only existing-repository scenario repeats those upgrades and verifies that the repository itself is not changed. Account setup, package managers, VPNs, firewalls, and real Pages publication stay in the manual matrix because a hosted test cannot reproduce those boundaries honestly.

The manual matrix gives confidence in installation and first-use integration, but it is a point-in-time result. The locally run macOS suite adds full regression coverage on that platform, although it is not enforced by a hosted pull-request gate. Windows can still regress outside the adoption workflow because it does not yet run the full suite for every change.

Windows requires native libraries for PDF generation that pip cannot install. It also uses different default text encodings. The known setup steps are documented under PDF requirements, and prodockit bootstrap checks the corresponding tools. Report a Windows-only failure rather than assuming it is local configuration; it may expose a real coverage gap.

GitLab.com manual testing was completed in September 2026, including project environment activation, Diagnostics, Template Sync, and local website/PDF checks. On macOS, Adopt aligned Pandoc to 3.10.1 before Diagnostics and both builds passed. This records manual integration evidence, not an additional automated live-provider CI gate. See Set up a machine for the host boundary.

Supported surfaces¶

Table 54.3 defines which interfaces carry a compatibility promise and which remain internal.

For observable constraints such as live-reload staleness, unsupported citation forms, and differences between browser and PDF rendering, see Known limitations. If the behaviour is not listed there, search or open a GitHub issue.

Upgrade safely¶

Read the release notes before changing a pinned version. Build the site with zensical build --clean --strict, build the PDF if the project publishes one, and run its built-output checks before merging. Template-based projects should also review changes reported by template-sync.