PHPackages                             ubertech-za/html-to-asciidoc - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. ubertech-za/html-to-asciidoc

ActiveLibrary[Parsing & Serialization](/categories/parsing)

ubertech-za/html-to-asciidoc
============================

HTML to AsciiDoc converter for PHP, inspired by and architecturally based on The PHP League's html-to-markdown

0.1.0(7mo ago)02MITPHPPHP ^8.2

Since Sep 16Pushed 7mo agoCompare

[ Source](https://github.com/ubertech-za/html-to-asciidoc)[ Packagist](https://packagist.org/packages/ubertech-za/html-to-asciidoc)[ Docs](https://github.com/ubertech-za/html-to-asciidoc)[ Fund](https://github.com/ubertech-za)[ RSS](/packages/ubertech-za-html-to-asciidoc/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (4)Versions (2)Used By (0)

HTML to AsciiDoc Converter
==========================

[](#html-to-asciidoc-converter)

> ⚠️ **BETA SOFTWARE NOTICE**This package is currently in beta and is being prepared for testing in upcoming projects. Please expect possible breaking changes in future releases. We do not recommend using this package in production environments without thorough testing.

This package converts HTML to AsciiDoc markup, inspired by and architecturally based on [The PHP League's `html-to-markdown`](https://github.com/thephpleague/html-to-markdown) package. Like its inspiration, this library uses a DOM-based approach with pluggable converters to ensure reliable and extensible HTML parsing and conversion. We extend our gratitude to The PHP League for their excellent architectural foundation—if League would like to incorporate this AsciiDoc functionality into their ecosystem, they are most welcome to do so.

[![Tests](https://github.com/ubertech-za/html-to-asciidoc/workflows/tests/badge.svg)](https://github.com/ubertech-za/html-to-asciidoc/actions)[![Latest Stable Version](https://camo.githubusercontent.com/b8da6af09d738149b1491aef1060babd632df1a1d71b8c12a2471ac0553a2a84/68747470733a2f2f706f7365722e707567782e6f72672f75626572746563682d7a612f68746d6c2d746f2d6173636969646f632f762f737461626c65)](https://packagist.org/packages/ubertech-za/html-to-asciidoc)[![Total Downloads](https://camo.githubusercontent.com/8bc61d742a28accf7f5fe279e71c0f54157f4b8b776103d1a10cc3cfcf38cf74/68747470733a2f2f706f7365722e707567782e6f72672f75626572746563682d7a612f68746d6c2d746f2d6173636969646f632f646f776e6c6f616473)](https://packagist.org/packages/ubertech-za/html-to-asciidoc)[![License](https://camo.githubusercontent.com/2e03aca3f8b8915b04f75cc1bd4d8f72c218dd59579e778359e4a0e7735be3f0/68747470733a2f2f706f7365722e707567782e6f72672f75626572746563682d7a612f68746d6c2d746f2d6173636969646f632f6c6963656e7365)](https://packagist.org/packages/ubertech-za/html-to-asciidoc)

Features
--------

[](#features)

- 🏗️ **DOM-based parsing** - Uses PHP's DOMDocument for reliable HTML parsing
- 🔧 **Extensible architecture** - Add custom converters for specific elements
- 📝 **Complete AsciiDoc support** - Headers, emphasis, links, images, lists, tables, code blocks
- ⚙️ **Configurable** - Customize conversion behavior with options
- 🧪 **Well tested** - Comprehensive test suite with 100+ assertions
- 🚀 **Laravel integration** - Optional service provider for Laravel projects
- 📦 **Framework agnostic** - Works with any PHP project

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require ubertech-za/html-to-asciidoc
```

**Framework Independence**: This package works standalone with any PHP project. Laravel integration is completely optional and only activated when Laravel is detected in your project.

Quick Start
-----------

[](#quick-start)

```
use UbertechZa\HtmlToAsciidoc\HtmlConverter;

$converter = new HtmlConverter();

$html = '
Welcome to AsciiDoc
This is a bold statement with a link.

    First item
    Second item

';

$asciidoc = $converter->convert($html);
echo $asciidoc;
```

Output:

```
= Welcome to AsciiDoc

This is a *bold* statement with a https://asciidoc.org[link].

* First item
* Second item
```

Usage
-----

[](#usage)

### Basic Usage

[](#basic-usage)

The simplest way to convert HTML to AsciiDoc:

```
use UbertechZa\HtmlToAsciidoc\HtmlConverter;

$converter = new HtmlConverter();
$asciidoc = $converter->convert('Hello World');
// Result: = Hello World
```

### Using the Laravel Wrapper

[](#using-the-laravel-wrapper)

If you're using the package in a Laravel project, you can use the provided converter wrapper:

```
use UbertechZa\HtmlToAsciidoc\HtmlToAsciiDocConverter;

$converter = new HtmlToAsciiDocConverter();
$asciidoc = $converter->convert('Hello world!');
// Result: Hello _world_!
```

### Using the Laravel Facade

[](#using-the-laravel-facade)

For even simpler usage in Laravel, you can use the provided facade:

```
use UbertechZa\HtmlToAsciidoc\Facades\HtmlToAsciidoc;

$asciidoc = HtmlToAsciidoc::convert('Easy Conversion');
// Result: = Easy Conversion

// Chain methods for configuration
$asciidoc = HtmlToAsciidoc::setOptions(['hard_break' => true])
                          ->convert('Line 1Line 2');
```

### Configuration Options

[](#configuration-options)

Customize the conversion behavior with configuration options:

```
use UbertechZa\HtmlToAsciidoc\HtmlConverter;

$converter = new HtmlConverter([
    'header_style' => 'atx',        // Use = for headers (default)
    'hard_break' => false,          // Use + for line breaks (default)
    'list_item_style' => '*',       // Use * for unordered lists (default)
    'remove_nodes' => 'script style', // Remove these tags completely
    'strip_tags' => false,          // Don't strip unknown tags (default)
    'suppress_errors' => true,      // Suppress HTML parsing errors (default)
]);

$asciidoc = $converter->convert($html);
```

### Method Chaining

[](#method-chaining)

You can chain methods for fluent configuration:

```
$asciidoc = (new HtmlConverter())
    ->setOptions(['hard_break' => true])
    ->convert('Line 1Line 2');
```

Supported HTML Elements
-----------------------

[](#supported-html-elements)

### Headers

[](#headers)

```
Level 1
Level 2
Level 3
```

Converts to:

```
= Level 1

== Level 2

=== Level 3
```

### Text Formatting

[](#text-formatting)

```
Bold text
Also bold
Italic text
Also italic
Inline code
```

Converts to:

```
*Bold text*
*Also bold*
_Italic text_
_Also italic_
`Inline code`
```

### Links and Images

[](#links-and-images)

```
Link text

```

Converts to:

```
https://example.com[Link text]
image::/images/logo.png[Company Logo]
```

### Lists

[](#lists)

```

    Unordered item 1
    Unordered item 2

    Ordered item 1
    Ordered item 2

```

Converts to:

```
* Unordered item 1
* Unordered item 2

. Ordered item 1
. Ordered item 2
```

### Code Blocks

[](#code-blocks)

```

function hello() {
    return "Hello World";
}

```

Converts to:

```
----
function hello() {
    return "Hello World";
}
----
```

### Blockquotes

[](#blockquotes)

```

    This is a quoted paragraph.

```

Converts to:

```
> This is a quoted paragraph.
```

### Tables

[](#tables)

```

        Header 1
        Header 2

        Cell 1
        Cell 2

```

Converts to:

```
|===
|Header 1 |Header 2
|Cell 1 |Cell 2
|===
```

### Other Elements

[](#other-elements)

- `` → `'''` (horizontal rule)
- `` → ` +` (line break) or `\n` with `hard_break` option
- `` → Paragraphs with proper spacing
- `` → Content blocks with spacing

Configuration Reference
-----------------------

[](#configuration-reference)

OptionTypeDefaultDescription`header_style`string`'atx'`Header style (always uses `=` syntax for AsciiDoc)`hard_break`boolean`false`Use `\n` instead of ` +` for line breaks`list_item_style`string`'*'`Character for unordered list items`remove_nodes`string`''`Space-separated list of HTML tags to remove`strip_tags`boolean`false`Strip unknown HTML tags`suppress_errors`boolean`true`Suppress HTML parsing errors`preserve_comments`boolean`false`Preserve HTML commentsAdvanced Usage
--------------

[](#advanced-usage)

### Custom Environment

[](#custom-environment)

For more control, you can create a custom environment:

```
use UbertechZa\HtmlToAsciidoc\Environment;
use UbertechZa\HtmlToAsciidoc\HtmlConverter;

$environment = Environment::createDefaultEnvironment([
    'custom_option' => 'value'
]);

$converter = new HtmlConverter($environment);
```

### Adding Custom Converters

[](#adding-custom-converters)

Create custom converters for specific HTML elements:

```
use UbertechZa\HtmlToAsciidoc\Converter\ConverterInterface;
use UbertechZa\HtmlToAsciidoc\ElementInterface;

class CustomConverter implements ConverterInterface
{
    public function convert(ElementInterface $element): string
    {
        return 'custom output for ' . $element->getValue();
    }

    public function getSupportedTags(): array
    {
        return ['custom-tag'];
    }
}

$environment = Environment::createDefaultEnvironment();
$environment->addConverter(new CustomConverter());

$converter = new HtmlConverter($environment);
```

### Configuration-Aware Converters

[](#configuration-aware-converters)

Converters can access configuration options:

```
use UbertechZa\HtmlToAsciidoc\ConfigurationAwareInterface;
use UbertechZa\HtmlToAsciidoc\Configuration;

class ConfigurableConverter implements ConverterInterface, ConfigurationAwareInterface
{
    private $config;

    public function setConfig(Configuration $config): void
    {
        $this->config = $config;
    }

    public function convert(ElementInterface $element): string
    {
        $option = $this->config->getOption('my_option', 'default');
        // Use option in conversion logic
        return $element->getValue();
    }

    public function getSupportedTags(): array
    {
        return ['configurable-tag'];
    }
}
```

Laravel Integration
-------------------

[](#laravel-integration)

> **Note**: Laravel integration is completely optional. The core package works independently without any Laravel dependencies. Laravel features are only available when `illuminate/support` is installed.

### Automatic Registration

[](#automatic-registration)

If you're using Laravel, the service provider is automatically registered when Laravel is detected. You can publish the configuration:

```
php artisan vendor:publish --provider="UbertechZa\HtmlToAsciidoc\HtmlToAsciiDocServiceProvider"
```

This will publish a `config/html-to-asciidoc.php` configuration file where you can set default conversion options.

### Facade Registration

[](#facade-registration)

Add the facade to your `config/app.php` file if you want to use it globally:

```
'aliases' => [
    // Other aliases...
    'HtmlToAsciidoc' => UbertechZa\HtmlToAsciidoc\Facades\HtmlToAsciidoc::class,
],
```

Then use it anywhere in your application:

```
$asciidoc = HtmlToAsciidoc::convert('Global Usage');
```

### Dependency Injection

[](#dependency-injection)

Use dependency injection in your controllers:

```
use UbertechZa\HtmlToAsciidoc\HtmlToAsciiDocConverter;

class DocumentController extends Controller
{
    public function convert(HtmlToAsciiDocConverter $converter)
    {
        $html = request('html');
        $asciidoc = $converter->convert($html);

        return response()->json(['asciidoc' => $asciidoc]);
    }
}
```

### Facade Usage in Controllers

[](#facade-usage-in-controllers)

Using the facade in controllers:

```
use UbertechZa\HtmlToAsciidoc\Facades\HtmlToAsciidoc;

class DocumentController extends Controller
{
    public function convert()
    {
        $html = request('html');

        $asciidoc = HtmlToAsciidoc::setOptions([
                'hard_break' => true,
                'list_item_style' => '*'
            ])
            ->convert($html);

        return response()->json(['asciidoc' => $asciidoc]);
    }
}
```

### Blade Templates

[](#blade-templates)

Use the facade in Blade templates:

```
@php
    $html = 'Dynamic ContentFrom your CMS';
    $asciidoc = HtmlToAsciidoc::convert($html);
@endphp

{{ $asciidoc }}
```

### Available Container Bindings

[](#available-container-bindings)

The service provider registers the following bindings:

- `UbertechZa\HtmlToAsciidoc\HtmlToAsciiDocConverter::class` - Main converter instance
- `UbertechZa\HtmlToAsciidoc\HtmlConverter::class` - Core HTML converter
- `'html-to-asciidoc'` - Facade accessor binding

All bindings are registered as singletons for optimal performance.

Error Handling
--------------

[](#error-handling)

The converter handles malformed HTML gracefully:

```
try {
    $converter = new HtmlConverter();
    $result = $converter->convert('Malformed HTMLnested improperly');
    // Will still produce reasonable output
} catch (InvalidArgumentException $e) {
    // Only thrown for completely invalid HTML structure
    echo "Invalid HTML provided";
}
```

Performance Considerations
--------------------------

[](#performance-considerations)

- **DOM Parsing**: Uses PHP's native DOMDocument for reliable parsing
- **Memory Usage**: Processes HTML in memory; consider chunking for very large documents
- **Caching**: Consider caching converted output for frequently accessed content
- **Configuration**: Create converter instances once and reuse them

Testing
-------

[](#testing)

Run the test suite:

```
composer test
```

Run tests with coverage:

```
composer test-coverage
```

Run static analysis:

```
composer analyse
```

Contributing
------------

[](#contributing)

Contributions are welcome! Please see our [contributing guidelines](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Ensure all tests pass
5. Submit a pull request

Changelog
---------

[](#changelog)

Please see [CHANGELOG.md](CHANGELOG.md) for details on recent changes.

Security
--------

[](#security)

If you discover any security-related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

This package is architecturally based on and inspired by [The PHP League's html-to-markdown](https://github.com/thephpleague/html-to-markdown) package. We extend our gratitude to The PHP League for their excellent architectural foundation. Like its inspiration, this library uses a DOM-based approach with pluggable converters to ensure reliable and extensible HTML parsing and conversion.

- **Original Architecture**: [The PHP League's html-to-markdown](https://github.com/thephpleague/html-to-markdown) (MIT License)
- **AsciiDoc Implementation**: [Uber Technologies cc](https://github.com/ubertech-za)
- **Contributors**: [All contributors](../../contributors)

### Architectural Attribution

[](#architectural-attribution)

This package borrows and adapts the following architectural patterns from `thephpleague/html-to-markdown`:

- DOM-based HTML parsing approach
- Pluggable converter system for HTML elements
- Environment and configuration management
- Element interface and converter interface patterns

The implementation has been adapted specifically for AsciiDoc output format while maintaining the robust parsing and extensibility patterns established by The PHP League.

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE.md).

Related Packages
----------------

[](#related-packages)

- [thephpleague/html-to-markdown](https://github.com/thephpleague/html-to-markdown) - Convert HTML to Markdown
- [ubertech-za/tiptap-to-asciidoc](https://github.com/ubertech-za/tiptap-to-asciidoc) - Convert Tiptap JSON to AsciiDoc

---

**Made by Uber Technologies cc**

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance62

Regular maintenance activity

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

236d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/66e61cdbc703c8243f2d508e06751760f02868b9a6abede5e6909aa06080e4e9?d=identicon)[ubertech-za](/maintainers/ubertech-za)

---

Top Contributors

[![mlategan](https://avatars.githubusercontent.com/u/21269704?v=4)](https://github.com/mlategan "mlategan (2 commits)")

---

Tags

documentationhtmlconvertermarkdownasciidoc

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/ubertech-za-html-to-asciidoc/health.svg)

```
[![Health](https://phpackages.com/badges/ubertech-za-html-to-asciidoc/health.svg)](https://phpackages.com/packages/ubertech-za-html-to-asciidoc)
```

###  Alternatives

[league/html-to-markdown

An HTML-to-markdown conversion helper for PHP

1.9k28.6M199](/packages/league-html-to-markdown)[pixel418/markdownify

The HTML to Markdown converter for PHP

196800.8k8](/packages/pixel418-markdownify)[daux/daux.io

Documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly

825191.0k1](/packages/daux-dauxio)[texy/texy

Texy converts plain text in easy to read Texy syntax into structurally valid (X)HTML. It supports adding of images, links, nested lists, tables and has full support for CSS. Texy supports hyphenation of long words (which reflects language rules), clickable emails and URL (emails are obfuscated against spambots), national typographic single and double quotation marks, ellipses, em dashes, dimension sign, nonbreakable spaces (e.g. in phone numbers), acronyms, arrows and many others. Texy code can optionally contain HTML tags.

161838.9k15](/packages/texy-texy)[3f/converter

A set of classes to translate a text from HTML to BBcode and from BBCode to Markdown.

29148.7k](/packages/3f-converter)[interaction-design-foundation/nova-html-card

A Laravel Nova card to display arbitrary HTML content

67731.2k3](/packages/interaction-design-foundation-nova-html-card)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)