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

1.0.5

This version

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.dev3.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.dev3-py3-none-any.whl (24.9 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: fontlab_www_toolkit-1.0.5.dev3.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.dev3.tar.gz
Algorithm Hash digest
SHA256 041a7593d3e3465bf71323b51e024e561c2103e8ca87342d4bd6e936d76465da
MD5 7a39b8df8e20776b6b0a7639815145b2
BLAKE2b-256 d87881b999b25043a425df4b60ebd65ffd89a8a4317276b0aa9ebdd6d6f76684

See more details on using hashes here.

File details

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

File metadata

  • Download URL: fontlab_www_toolkit-1.0.5.dev3-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.dev3-py3-none-any.whl
Algorithm Hash digest
SHA256 f204166ef72b3a48e24550f04d9965c11647836b50de0df169cfa85b8ae95716
MD5 708d0806ebc7511d2dfb823521a79b7b
BLAKE2b-256 f809a02a38392393242ec75d08778b314b7137f291cadc7a9f78d5a44041225a

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