Shared ProperDocs + MaterialX site builder and deploy helpers for FontLab web properties.

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for twardoch from gravatar.com twardoch

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: Fontlab Ltd.
  • Tags fontlab , materialx , mkdocs , properdocs , static-site , webflow
  • Requires: Python >=3.12
Classifiers
Report project as malware

Project description

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.
version Print the installed version.

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

Site repo layout it expects

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
uv run pytest -q

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

Publish

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

Requires UV_PUBLISH_TOKEN (PyPI token) in the environment.

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for twardoch from gravatar.com twardoch

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: Fontlab Ltd.
  • Tags fontlab , materialx , mkdocs , properdocs , static-site , webflow
  • Requires: Python >=3.12
Classifiers

Release history Release notifications | RSS feed

1.0.7

1.0.6

1.0.6.dev1 pre-release

This version

1.0.5

1.0.5.dev3 pre-release

1.0.4

1.0.4.dev3 pre-release

1.0.3

1.0.2

1.0.1

1.0.1.dev1 pre-release

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fontlab_www_toolkit-1.0.5.tar.gz (30.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

fontlab_www_toolkit-1.0.5-py3-none-any.whl (24.9 kB view details)

Uploaded Python 3

File details

Details for the file fontlab_www_toolkit-1.0.5.tar.gz.

File metadata

  • Download URL: fontlab_www_toolkit-1.0.5.tar.gz
  • Upload date:
  • Size: 30.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","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}

File hashes

Hashes for fontlab_www_toolkit-1.0.5.tar.gz
Algorithm Hash digest
SHA256 a4280fad5ce5c748fe5b59e9306e1cb28902b27b405c88ac231399d75fc56060
MD5 a5f181f518037c8c8d195b8ac0f3d729
BLAKE2b-256 557f9e7edc057557a63ef2ee6b1287e5f401fe60644b3c9e8550bb99e728cde0

See more details on using hashes here.

File details

Details for the file fontlab_www_toolkit-1.0.5-py3-none-any.whl.

File metadata

  • Download URL: fontlab_www_toolkit-1.0.5-py3-none-any.whl
  • Upload date:
  • Size: 24.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","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}

File hashes

Hashes for fontlab_www_toolkit-1.0.5-py3-none-any.whl
Algorithm Hash digest
SHA256 0080e45b15acd8f0e1a729bd54e61771722f21ab5b7ce1473f9500b39a9e9d24
MD5 de7ec44cc31f3e229dc1458ac35f5819
BLAKE2b-256 89f78af4e884fbe0a501418695eb6c69fb18fb972b83215a5a330835fa2f6c17

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page