Skip to main content

html-to-gutenberg

Конвертация HTML в WordPress Gutenberg блоки — Python-библиотека и CLI

Usage

CLI (for humans and agents; html-to-gutenberg and html_to_gutenberg are the same command):

html-to-gutenberg convert page.html              # markup to stdout
html-to-gutenberg convert page.html -o out.html  # write to a file
html-to-gutenberg convert page.html --json       # {"ok": true, "blocks": "...", "output": null}

Wrappers like div/section are unwrapped, tags without a native block are kept as Custom HTML (wp:html), script/style/head are dropped — each such case is a warning (stderr; "warnings" under --json), so nothing disappears silently. html-to-gutenberg convert --help lists the native blocks.

Python library:

from rb_html_to_gutenberg import HtmlToGutenberg

blocks = HtmlToGutenberg().convert("<h2>Title</h2><p>Text</p>")
report = HtmlToGutenberg().convert_report(html)  # report.blocks, report.warnings

In another uv project, depend on it editable (edits here are picked up immediately) or from Gitea:

uv add --editable /Users/bolandau/Work/tools/rb-html-to-gutenberg
uv add "rb-html-to-gutenberg @ git+https://homeserver.tailee01ab.ts.net:3000/bolandeu/html-to-gutenberg.git@vX.Y.Z"

The distribution is rb-html-to-gutenberg (standard §10); the import package (html_to_gutenberg) and the command (html-to-gutenberg) keep their names. Pin a tag (@vX.Y.Z) rather than a branch.

Development

uv sync
uv run html-to-gutenberg --help
uv run pytest --snapshot-update  # after changing a command's help; review tests/snapshots/help/

The gate is gate check, run on this machine before a commit. the changelog and the release are Antagor's (antagor board, antagor publish); the version is the git tag (vX.Y.Z), pyproject.toml has no version =.

Install

On this machine, from a local checkout — editable, so code edits take effect in the global command without reinstalling:

uv tool install --editable .

From the Gitea registry (the package is released there):

uv tool uninstall html_to_gutenberg   # once: the old distribution name (before v0.4.0)

From the git tag (any machine, any OS):

uv tool install "rb-html-to-gutenberg @ git+https://homeserver.tailee01ab.ts.net:3000/bolandeu/html-to-gutenberg.git@vX.Y.Z"

vX.Y.Z is a release tag cut by antagor publish. Uninstall the old html_to_gutenberg tool first, otherwise two tools fight over the same command. This is also how an AI agent bootstraps this CLI on a fresh machine/sandbox where it isn't installed yet — see src/rb_html_to_gutenberg/data/SKILL.md.

Update an installed copy to the latest commit:

uv tool upgrade rb-html-to-gutenberg

After install, the command html_to_gutenberg is available globally, on macOS, Linux and Windows alike (see architecture.md in the cli-generator plugin for why: no shelling out, no hardcoded POSIX paths).

To pick up later template changes, see existing-package.md in the cli-generator plugin (copier update).

Architecture

This project follows a fixed CLI architecture:

  • src/rb_html_to_gutenberg/commands/ — argument parsing only, no business logic.
  • src/rb_html_to_gutenberg/core/ — services, models, errors: the real logic.
  • src/rb_html_to_gutenberg/providers/ — external APIs/integrations.
  • src/rb_html_to_gutenberg/credentials/ — secrets via the OS keychain (keyring) and environment variables. Secrets never live in .html_to_gutenberg/config.toml.
  • src/rb_html_to_gutenberg/output/ — human (rich) and --json rendering.

Run html_to_gutenberg doctor to check environment/config/auth readiness, and html_to_gutenberg --help for the full command surface. Every command supports --json for machine/agent consumption; errors are structured (error.code, fixed exit codes, error.action telling you what to do next) and go to stderr in human mode, so stdout is always safe to pipe.

A project can require a minimum CLI version in its .html_to_gutenberg/config.toml ([cli] min_version = "..."); an older install refuses with exit 6 and uv tool upgrade rb-html-to-gutenberg fixes it.

See src/rb_html_to_gutenberg/data/SKILL.md for the agent-facing usage guide bundled with this package — install it into an AI tool with html_to_gutenberg skill install, or get it as plain text with html_to_gutenberg --ai (works even without file access).

Metadata

Release files for rb-html-to-gutenberg 0.5.6

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

Source distribution (sdist)

Source distribution for rb-html-to-gutenberg 0.5.6
File Size Uploaded Provenance Actions
rb_html_to_gutenberg-0.5.6.tar.gz 76.1 kB Without provenance Details for rb_html_to_gutenberg-0.5.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rb-html-to-gutenberg 0.5.6
File Interpreter ABI Platform Actions
rb_html_to_gutenberg-0.5.6-py3-none-any.whl Python 3 none any Details for rb_html_to_gutenberg-0.5.6-py3-none-any.whl

Total release size: 128.1 kB

Release files / rb_html_to_gutenberg-0.5.6.tar.gz

Download URL rb_html_to_gutenberg-0.5.6.tar.gz
Size 76.1 kB
Tags Source
SHA-256 checksum
How to use checksums
cf0642553e5ed01e0fd411c88e68c5d2905d5598a4a47305b7847d9a91c9a48b
BLAKE2b-256 checksum
How to use checksums
3dac6cb421494947ca66c361781ac7d379ef8a44933e29d1e1172edbc70feab5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","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 / rb_html_to_gutenberg-0.5.6-py3-none-any.whl

Download URL rb_html_to_gutenberg-0.5.6-py3-none-any.whl
Size 52.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
de732a9b1cf241b92e844a6f645b240769116b8e70708d3d3e44bf6bc76433df
BLAKE2b-256 checksum
How to use checksums
4e0d8baf12c09a6fcc4ede761cad7de49a859e75b25b23a71d8b22a110666fe1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","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 rb-html-to-gutenberg 0.5.6

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

0.5.6 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page