fontlab-www-toolkit

Shared ProperDocs + MaterialX site builder and deploy helpers used by the FontLab web properties (www.fontlab.com, www.vexy.art, and the api.fontlab.com/www-admin/ PHP UI).

Install

uv add fontlab-www-toolkit          # in a project
uvx fontlab-www-toolkit --help      # one-shot
pip install fontlab-www-toolkit

CLI

Three equivalent ways to invoke it:

fontlab-www-toolkit COMMAND        # console script (works under uvx too)
fontlab-build       COMMAND        # backwards-compat alias
python -m fontlab_www_toolkit COMMAND

Commands:

Command	Effect
`build [--skip_webflow] [--update_stubs]`	Pull Webflow stubs, build with MkDocs/ProperDocs, overlay `wf_cache/` + `static_docs/`, publish to `public/`.
`pull-webflow [--update_stubs]`	Refresh `wf_cache/` only.
`convert-old`	Regenerate OLD pages from `src_docs/old-pages.yml`.
`clean`	Delete `build_docs/` and `public/`.
`setup [--venv PATH] [--clear]`	Create / refresh a uv venv for the admin pipeline.
`mirror --manifest_url URL --dest DIR [--dry_run]`	Mirror a static site folder over HTTPS from its `manifest.json` (size + SHA-256 verified, atomic folder swap).
`version`	Print the installed version.

All commands accept --root PATH; default is the current working directory.

Mirroring a published static site

Some properties are not built by this toolkit but by their own CI — e.g. the TTH Debugger, whose GitHub Actions build lands in https://fontlab.dev/tth-debugger/alpha-sdx992/. Such a build exposes a manifest.json (schema: fontlab-site-manifest/1) listing every file with path, size, sha256, type (HTML entries may add sha256Normalized, the hash with ASCII whitespace removed), plus name, version, commit, builtAt, baseUrl, entry. mirror consumes that:

fontlab-www-toolkit mirror \
  --manifest_url https://fontlab.dev/tth-debugger/alpha-sdx992/manifest.json \
  --dest /path/to/live/studio.fontlab.com/public/tth-debugger

Files already present with a matching hash are reused; everything else is downloaded, verified, and the folder is swapped in with a rename so the live site never sees a half-written tree. Cloudflare's injected bot-detection <script> in HTML responses is stripped before verification. The manifest is saved into the destination as manifest.json for provenance. Standard library only — no extra dependencies in the admin venv.

Site repo layout it expects

Sites can set theme_assets in fontlab-www-toolkit.json to a list of HTTPS CSS and JavaScript URLs. The builder adds missing links and deferred scripts after all Webflow/static overlays, so imported pages use the same shared theme as Markdown pages. Existing asset URLs are deduplicated. This is opt-in.

site/
├── src_docs/
│   ├── mkdocs.yml
│   ├── md/                   # Markdown sources (+ Webflow stubs via frontmatter)
│   └── old-pages.yml         # OPTIONAL — one-time HTML → MD conversions
├── static_docs/              # Copied verbatim over build_docs/ during overlay
├── wf_cache/                 # Generated — Webflow snapshots
├── build_docs/               # Generated — MkDocs output
└── public/                   # Generated — final publish tree

A Webflow stub is any Markdown file with frontmatter:

---
title: Page
webflow-import-url: https://example.webflow.io/page
---

Refreshing stub bodies (`--update_stubs`)

Normally only wf_cache/ is refreshed; the stub Markdown body stays as a placeholder (the cached HTML overlays it at build time). Pass --update_stubs to pull-webflow or build to also rewrite each stub's body from the freshly cached HTML, while preserving the stub's frontmatter verbatim:

fontlab-www-toolkit pull-webflow --update_stubs

For each stub it strips non-prose noise (<script>/<style>/<noscript> and hidden Webflow Windflow plugin metadata), serves the cleaned cached HTML over a loopback HTTP server, and runs url22md to extract Markdown. This requires the url22md CLI on PATH (or set url22md_bin in config); it is an external runtime tool, not a packaged dependency.

Configuration

You can customize the builder's behavior using a JSON configuration file (by default fontlab-www-toolkit.json in the root directory, or passed via --config CLI option). Alternatively, individual pages can specify page-specific overrides inside the input HTML:

<head>
  <script id="fontlab-toolkit-config" type="application/json">
  {
    "cloudinary": {
      "cl_responsive": {
        "methodology": "legacy"
      }
    }
  }
  </script>
</head>

Global Overrides

The following settings can be overridden in the root configuration object:

frontmatter_key (string): The YAML frontmatter key used to identify Webflow URLs. Defaults to "webflow-import-url".
webflow_badge_hide_css (string): CSS injected to hide the Webflow badge.
old_pages_config (string): Path to the legacy pages mapping file. Defaults to "src_docs/old-pages.yml".
mkdocs_command (string | array): The custom build command for MkDocs/ProperDocs. Can include the {config_file} placeholder.
user_agent (string): Custom User-Agent header used when pulling Webflow pages. Defaults to "fontlab_www_toolkit".
split_google_fonts (bool): When true (default), split a multi-family fonts.googleapis.com/css2?family=A&family=B&… link into one ?family=X&display=swap link per family. This keeps web fonts loading even if a downstream step truncates the served URL at the first & (otherwise only the first family loads and the rest fall back to a system font).
url22md_bin (string): Path to the url22md executable used by --update_stubs. Defaults to whatever is found on PATH.
url22md_tool (int | null): Forces a specific url22md extraction engine (1=trafilatura, 3=readability, …). Defaults to 1 for offline, deterministic extraction; set to null to let url22md run its full fallback chain (may reach cloud tools).
url22md_timeout (int): Per-page extraction timeout in seconds. Defaults to 60.

Cloudinary Options

The cloudinary block allows automatic mapping of image URLs to Cloudinary and setup of responsive client-side loading:

{
  "cloudinary": {
    "cl_cloud": "mycloud",
    "cl_map": {
      "https://cdn.example-files.com/assets": "assets_prefix",
      "https://images.example.com": "images_prefix"
    },
    "cl_trans": "c_limit,w_auto/f_auto,q_auto,dpr_auto/",
    "cl_responsive": {
      "cl_trans_thumb": "c_limit,w_128/f_auto,q_1/",
      "cl_core_js": "https://unpkg.com/cloudinary-core@latest",
      "methodology": "modern"
    }
  }
}

cl_cloud: Cloudinary cloud name.
cl_map: Map of source URL prefixes to Cloudinary upload folder prefixes. Any matching image URLs found in attributes (like src, href, style background-image) will be replaced.
cl_trans: The default Cloudinary image transformation string.
cl_responsive: (Optional) Enables responsive client-side images:
- Adds class="cld-responsive" to matching <img> elements.
- Sets the src attribute to a thumbnail transformation (using cl_trans_thumb).
- Sets the data-src attribute to the main transformation (using cl_trans).
- Clears srcset to avoid browser conflict.
- Injects responsive initialization scripts before the closing </body> tag:
  - methodology: "modern" (Recommended): Injects a lightweight vanilla JS script using ResizeObserver to update image source dynamically, avoiding heavy external library dependencies.
  - methodology: "legacy": Injects the cloudinary-core library (cl_core_js) and invokes cl.responsive().

Deploy helpers (library use)

from pathlib import Path
from fontlab_www_toolkit import DeployTarget, run_full_deploy

target = DeployTarget(
    site_root=Path("/path/to/site"),
    site_label="www.example.com",
    local_source=Path("/path/to/site/public"),
    backup_dest=Path("/path/to/web-fontlab/src/ionos/live/example.com/public"),
    remote_path="live/example.com/public",
)
run_full_deploy(target, commit_message="Deploy www.example.com")

Mirrors the local backup, rsyncs to the remote, commits both the site repo and (if present) the web-fontlab/ mirror repo.

Develop

git clone git@github.com:Fontlab/fontlab-www-toolkit.git
cd fontlab-www-toolkit
uv sync --group dev
uv run ruff check src/ tests/      # lint
uv run mypy src/fontlab_www_toolkit/  # typecheck
uv run pytest -q                   # test

Version comes from git tags via hatch-vcs. Tag with semver (v1.2.3) to bump.

See CHANGELOG.md for release history and src_docs/ for full documentation covering the four-layer build flow, Webflow stub format, wf_cache/ layout, and www-admin integration.

Publish

./publish.sh   # uvx hatch clean ; uvx gitnextver ; uv build ; uv publish

Requires UV_PUBLISH_TOKEN (PyPI token) in the environment.

Metadata

Release files for fontlab-www-toolkit 1.0.14

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fontlab-www-toolkit 1.0.14
File	Size	Uploaded	Provenance	Actions
fontlab_www_toolkit-1.0.14.tar.gz	45.0 kB	Sep 23, 2026	Without provenance	Details for fontlab_www_toolkit-1.0.14.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fontlab-www-toolkit 1.0.14
File	Interpreter	ABI	Platform	Actions Reset
fontlab_www_toolkit-1.0.14-py3-none-any.whl 33.9 kB Sep 23, 2026 Without provenance	Python 3	none	any	Details for fontlab_www_toolkit-1.0.14-py3-none-any.whl

Total release size: 78.9 kB

Release files / fontlab_www_toolkit-1.0.14.tar.gz

Download URL	fontlab_www_toolkit-1.0.14.tar.gz
Size	45.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`295480ec77d266646c5ba2403dc4bc292c31ccd457163ffe79e494ba102bd0c8`
BLAKE2b-256 checksum How to use checksums	`81e210f51071aed2ce7480e292448ccc496c1d9b37505a04c1e6a1ee0b351e8e`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / fontlab_www_toolkit-1.0.14-py3-none-any.whl

Download URL	fontlab_www_toolkit-1.0.14-py3-none-any.whl
Size	33.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5c59a5925b671c092aade234c2f6b1143bd2a732aff79d7dae47eda0cc149af4`
BLAKE2b-256 checksum How to use checksums	`bcb632fce37bc2d0532aa4cb2372ba2d0c59d422d568a2362d7d97bb6af436f7`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Security for fontlab-www-toolkit 1.0.14

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.14 This release

Sep 23, 2026 2 release files No provenance

fontlab-www-toolkit 1.0.14