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

This version

1.0.7

1.0.6

1.0.6.dev1 pre-release

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.7.tar.gz (32.4 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.7-py3-none-any.whl (26.1 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: fontlab_www_toolkit-1.0.7.tar.gz
  • Upload date:
  • Size: 32.4 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.7.tar.gz
Algorithm Hash digest
SHA256 40ce455115d62a1d095f8e2b35d963c8c6f6406613b48c33c47229810695a974
MD5 c68e9f4f5937755417f8448c8b2cd45e
BLAKE2b-256 bf391da74373707817cbdca4d5d07730ffc6318345663587a5ece8efe279aa86

See more details on using hashes here.

File details

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

File metadata

  • Download URL: fontlab_www_toolkit-1.0.7-py3-none-any.whl
  • Upload date:
  • Size: 26.1 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.7-py3-none-any.whl
Algorithm Hash digest
SHA256 47db62c1ffde6b7484ac36b65f63fbf3bf03db9fda3a38cf1a2ed0596211aec1
MD5 82c599e9d76b5c6087936886fac0135d
BLAKE2b-256 d849d61e4e2697e3ca987b284fa04922530455bc371d5aadfe14cffbeb6bd555

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