Download the PHP package kntnt/html-to-markdown without Composer

kntnt/html-to-markdown

A dependency-free PHP 8.4 library that converts HTML into GitHub Flavored Markdown (GFM). If you need to turn HTML into clean, predictable Markdown — to feed page content to an LLM, archive content portably, or render it elsewhere — and you want output that matches a battle-tested reference implementation, this is for you.

Description

kntnt/html-to-markdown is a faithful PHP port of the Go library JohannesKaufmann/html-to-markdown (v2). It ports the converter core and the base, commonmark, strikethrough, and table plugins, reproducing the Go library's output byte-for-byte: upstream's golden test fixtures are asserted character-for-character by the test suite.

It has zero runtime dependencies. Every dependency the Go library reaches for maps onto a PHP built-in — Dom\HTMLDocument for HTML5 parsing and CSS selectors and mbstring for text handling — with relative-URL resolution hand-ported from RFC 3986, so the package drops into any PHP 8.4 project without dragging in a dependency tree or risking version conflicts. It is used by other Kntnt projects via Composer.

Key Features

• Faithful port. Output matches the Go library byte-for-byte wherever PHP's HTML5 parser and Go's x/net/html agree; upstream's golden fixtures are asserted in the test suite.
• Zero runtime dependencies. No Composer runtime packages — only the near-ubiquitous ext-dom and ext-mbstring.
• GitHub Flavored Markdown. Full CommonMark core plus GFM tables and strikethrough.
• Tables done properly. Pipe tables with alignment, colspan/rowspan, captions, header promotion, and presentation-table handling.
• Smart, context-aware escaping. Text that merely looks like Markdown stays literal, while real formatting elements become real Markdown.
• Relative-URL resolution. Resolve href/src against a base domain to produce absolute links and images.
• Scoped conversion. Include or exclude parts of the document with CSS selectors.
• Configurable output. Choose emphasis delimiters, heading style, code fences, list markers, and more.
• Two entry points. A one-line static facade for the common case, and a deep, extensible Converter for everything else.

The problem

More and more PHP applications need Markdown out of HTML, and the naive approaches all fail in their own way: stripping tags throws away structure, and hand-rolled regular expressions produce invalid or surprising Markdown. Getting it right is harder than it looks, and the subtlest part is escaping: a sentence that happens to contain ** or a leading # must not silently turn into bold text or a heading when it round-trips through Markdown.

How this library helps

Rather than inventing yet another converter, this library ports a mature, widely used, well-tested one — JohannesKaufmann/html-to-markdown — and holds itself to that reference byte-for-byte. You get GitHub Flavored Markdown out of the box: headings, emphasis, links, images, code, blockquotes, lists, thematic breaks, hard breaks, comments, GFM tables, and strikethrough. Relative URLs can be resolved against a base domain, conversion can be scoped to part of a document, and escaping is handled by a two-phase, context-aware model that decides per occurrence whether a character needs a backslash. Because it has zero runtime dependencies, it installs cleanly into any PHP 8.4 codebase.

Limitations

• No task lists. This is the one deliberate gap in GFM coverage: a checkbox list item (<li><input type="checkbox">…) is rendered as a plain list item, not - [ ] / - [x]. Task lists are out of scope upstream too.
• Autolinks and the tagfilter do not apply. Both are parsing features that act on Markdown input; when the input is HTML there is nothing for them to do. See Supported Markdown for the details.
• It is a converter, not a sanitizer. It emits Markdown (and strips script/style/iframe-style tags in the process), but it is not designed or audited as a security boundary against hostile HTML. Sanitize untrusted input separately if that is your threat model.
• PHP 8.4+ only. The port uses modern language and standard-library features (notably Dom\HTMLDocument, the native HTML5 parser added in 8.4) and carries no back-compatibility shims for older PHP.

Requirements

• PHP 8.4 or newer
• ext-dom and ext-mbstring (both bundled with virtually every PHP build)

Installation

No further configuration is required.

Usage

The facade

For the common case, the static facade mirrors upstream's ConvertString. It wires up the base and commonmark plugins and converts in one call:

Pass options as named arguments. To resolve relative URLs against a base domain:

The facade also accepts includeSelector and excludeSelector (see Include / exclude selectors). For strikethrough, tables, or custom output styling, build a Converter directly.

The converter

For full control — strikethrough and tables, custom output options, or custom plugins — build a Converter. The base and commonmark plugins are the minimum needed for sensible output; add strikethrough and table as required:

A single converter is safe to reuse across many conversions: options that vary per request — the base domain and the include/exclude selectors — live on the Options object passed to convertString(), not on the converter itself. If you already hold a parsed DOM, convertNode() takes a Dom\Node instead of a string.

Commonmark options

The CommonmarkPlugin accepts the same options as upstream, as named constructor arguments:

" headingStyle: 'setext', // default "atx" ); bash composer update kntnt/html-to-markdown bash git clone https://github.com/Kntnt/kntnt-html-to-markdown.git cd kntnt-html-to-markdown composer install bash git archive --format=tar.gz --prefix=kntnt-html-to-markdown/ -o kntnt-html-to-markdown.tar.gz HEAD bash composer test # Pest test suite composer test:coverage # Pest with code coverage (needs pcov or Xdebug) composer stan # PHPStan, level max composer cs # PHP-CS-Fixer, PSR-12 (dry run) composer cs-fix # PHP-CS-Fixer, apply fixes

All four run in CI on every push and pull request against PHP 8.4. New code is expected to keep the golden fixtures passing, stay green under PHPStan at level max, and conform to PSR-12.

### Technical documentation

- [`docs/architecture.md`](docs/architecture.md) — the porting record: the full Go→PHP module map, the escaping model, the URL-resolution notes, and every bridged Go-vs-PHP implementation difference. Read this before changing the engine.
- [`docs/coding-standards.md`](docs/coding-standards.md) — the project's coding standard.
- [`CLAUDE.md`](CLAUDE.md) / [`AGENTS.md`](AGENTS.md) — entry points for AI coding agents working in the repository.
- [`NOTICE.md`](NOTICE.md) — the upstream pin and the full licensing lineage.

## How you can contribute

Contributions are welcome, large or small. You can help by [opening an issue](https://github.com/Kntnt/kntnt-html-to-markdown/issues) to report a bug or request a feature, by sending a pull request with a fix or improvement, or by improving the documentation. Because **fidelity to the upstream Go library is the contract**, code contributions are expected to keep the golden fixtures passing byte-for-byte; if a change would alter output, explain why, and never weaken the converter to paper over a difference. When in doubt, open a discussion first.

## Acknowledgements

This library stands on the work of others. Thanks to **Johannes Kaufmann** for [`html-to-markdown`](https://github.com/JohannesKaufmann/html-to-markdown), the Go library this is a port of; and to **Dom Christie** ([Turndown](https://github.com/mixmark-io/turndown)) and **Luc Thevenard** ([collapse-whitespace](https://github.com/wooorm/collapse-white-space)), whose whitespace-collapsing code lives on in the port's lineage. The full attribution chain is in [`NOTICE.md`](NOTICE.md).

## License

Released under the MIT License, with dual copyright: Johannes Kaufmann for the original Go library, and Thomas Barregren / Kntnt for the PHP port. The license text is in [`LICENSE`](LICENSE); the complete lineage and per-component attribution are in [`NOTICE.md`](NOTICE.md).

## Changelog

See [`CHANGELOG.md`](CHANGELOG.md) for the release history. The project follows [Keep a Changelog](https://keepachangelog.com/) and [Semantic Versioning](https://semver.org/).