PHPackages                             ubertech-za/asciidoctor-wrapper - 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. [Utility & Helpers](/categories/utility)
4. /
5. ubertech-za/asciidoctor-wrapper

ActiveLibrary[Utility & Helpers](/categories/utility)

ubertech-za/asciidoctor-wrapper
===============================

PHP wrapper for Asciidoctor with configurable styling and theming support

0.1.0(9mo ago)02MITPHPPHP ^8.2

Since Sep 16Pushed 9mo agoCompare

[ Source](https://github.com/ubertech-za/asciidoctor-wrapper)[ Packagist](https://packagist.org/packages/ubertech-za/asciidoctor-wrapper)[ Docs](https://github.com/ubertech-za/asciidoctor-wrapper)[ RSS](/packages/ubertech-za-asciidoctor-wrapper/feed)WikiDiscussions master Synced today

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

AsciiDoctor Wrapper
===================

[](#asciidoctor-wrapper)

> ⚠️ **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.

A Laravel package that provides a PHP wrapper around AsciiDoctor and AsciiDoctor-PDF with advanced theming, styling, and configuration management.

[![Latest Version](https://camo.githubusercontent.com/e37ebf0f7be52766a3f6b8f6d7cfa2a5c8ce9820c80e23fd8b1c979647ded615/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f75626572746563682d7a612f6173636969646f63746f722d777261707065722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ubertech-za/asciidoctor-wrapper)[![License](https://camo.githubusercontent.com/70ce20a88e4f6f07977546556dace4c4e7a6a391de88ca0429b652db6229eda1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f75626572746563682d7a612f6173636969646f63746f722d777261707065722e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)[![Tests](https://camo.githubusercontent.com/107f4bbfd3695a03b72999a92af459d423f30330c7ea57bce91e87b2b152fffb/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f75626572746563682d7a612f6173636969646f63746f722d777261707065722f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/ubertech-za/asciidoctor-wrapper/actions)

Overview
--------

[](#overview)

This package bridges the gap between PHP applications and the powerful AsciiDoctor ecosystem, providing:

- **Configurable AsciiDoctor Integration**: Support for both `asciidoctor` and `asciidoctor-pdf` executables
- **Advanced Theming System**: Create, extend, and manage themes with JSON configuration
- **Style Object Composition**: Programmatically build themes using fluent APIs
- **Theme Inheritance**: Extend built-in AsciiDoctor themes or custom themes
- **Laravel Integration**: Service providers, facades, and configuration management
- **Type Safety**: Full PHP 8.2+ type declarations and comprehensive testing

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

[](#installation)

Install the package via Composer:

```
composer require ubertech-za/asciidoctor-wrapper
```

### Prerequisites

[](#prerequisites)

You need to have AsciiDoctor installed on your system:

```
# Install AsciiDoctor (Ruby required)
gem install asciidoctor

# Install AsciiDoctor-PDF for PDF generation
gem install asciidoctor-pdf
```

Alternatively, use Docker:

```
docker pull asciidoctor/docker-asciidoctor
```

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

[](#laravel-integration)

### Configuration

[](#configuration)

Publish the configuration file:

```
php artisan vendor:publish --tag=asciidoctor-config
```

Configure your executables in `config/asciidoctor.php`:

```
return [
    'executables' => [
        'asciidoctor' => env('ASCIIDOCTOR_PATH', 'asciidoctor'),
        'asciidoctor_pdf' => env('ASCIIDOCTOR_PDF_PATH', 'asciidoctor-pdf'),
    ],

    'default_theme' => env('ASCIIDOCTOR_DEFAULT_THEME', 'default'),
    'themes_path' => env('ASCIIDOCTOR_THEMES_PATH', storage_path('asciidoc/themes')),
    'templates_path' => env('ASCIIDOCTOR_TEMPLATES_PATH', storage_path('asciidoc/templates')),
    'fonts_path' => env('ASCIIDOCTOR_FONTS_PATH', storage_path('asciidoc/fonts')),
    'output_path' => env('ASCIIDOCTOR_OUTPUT_PATH', storage_path('asciidoc/documents')),

    // ... additional configuration
];
```

### Environment Variables

[](#environment-variables)

Add to your `.env` file:

```
ASCIIDOCTOR_PATH=/usr/local/bin/asciidoctor
ASCIIDOCTOR_PDF_PATH=/usr/local/bin/asciidoctor-pdf
ASCIIDOCTOR_DEFAULT_THEME=default-with-font-fallbacks
ASCIIDOCTOR_THEMES_PATH=/path/to/themes
ASCIIDOCTOR_TEMPLATES_PATH=/path/to/templates
ASCIIDOCTOR_FONTS_PATH=/path/to/your/fonts
ASCIIDOCTOR_OUTPUT_PATH=/path/to/output
ASCIIDOCTOR_CACHE_ENABLED=true
ASCIIDOCTOR_CACHE_TTL=3600
```

Usage
-----

[](#usage)

### Basic Usage

[](#basic-usage)

```
use UbertechZa\AsciidoctorWrapper\Facades\Asciidoctor;

// Convert AsciiDoc to HTML
$result = Asciidoctor::convert(
    input: 'document.adoc',
    output: 'document.html',
    format: 'html5'
);

// Convert to PDF
$result = Asciidoctor::convert(
    input: 'document.adoc',
    output: 'document.pdf',
    format: 'pdf'
);

if ($result['success']) {
    echo "Conversion successful!";
} else {
    echo "Error: " . $result['error'];
}
```

### Using the Wrapper Class Directly

[](#using-the-wrapper-class-directly)

```
use UbertechZa\AsciidoctorWrapper\AsciidoctorWrapper;

$wrapper = new AsciidoctorWrapper(
    asciidoctorPath: '/usr/local/bin/asciidoctor',
    asciidoctorPdfPath: '/usr/local/bin/asciidoctor-pdf'
);

$result = $wrapper->convert('input.adoc', 'output.pdf', 'pdf');
```

Theme System
------------

[](#theme-system)

### Creating Themes with the Theme Builder

[](#creating-themes-with-the-theme-builder)

```
use UbertechZa\AsciidoctorWrapper\Builder\ThemeBuilder;

$theme = app(ThemeBuilder::class)
    ->name('modern-theme')
    ->extending('default')
    ->withColors([
        'primary' => '#2563eb',
        'secondary' => '#64748b',
        'accent' => '#059669',
        'text' => '#0f172a',
        'background' => '#ffffff'
    ])
    ->withFont('heading', 'Inter', '16pt', 'bold')
    ->withFont('body', 'Inter', '11pt', 'normal')
    ->withFont('mono', 'JetBrains Mono', '9pt', 'normal')
    ->withElementStyle('document', [
        'color' => '#0f172a',
        'font' => ['family' => 'Inter', 'size' => '11pt']
    ])
    ->withElementStyle('heading1', [
        'color' => '#2563eb',
        'font' => ['family' => 'Inter', 'size' => '24pt', 'weight' => 'bold']
    ])
    ->build();

// Use the theme
$result = Asciidoctor::convert('input.adoc', 'output.pdf', 'pdf', $theme);
```

### Loading Themes from JSON

[](#loading-themes-from-json)

Create a theme file at `resources/asciidoctor/themes/my-theme.json`:

```
{
  "name": "my-theme",
  "extends": "default",
  "colors": {
    "primary": "#2563eb",
    "secondary": "#64748b",
    "accent": "#059669",
    "text": "#0f172a",
    "background": "#ffffff"
  },
  "fonts": {
    "heading": {
      "family": "Inter",
      "size": "16pt",
      "weight": "bold"
    },
    "body": {
      "family": "Inter",
      "size": "11pt",
      "weight": "normal"
    },
    "mono": {
      "family": "JetBrains Mono",
      "size": "9pt",
      "weight": "normal"
    }
  },
  "styles": {
    "document": {
      "color": "#0f172a",
      "font": {
        "family": "Inter",
        "size": "11pt"
      }
    },
    "heading1": {
      "color": "#2563eb",
      "font": {
        "family": "Inter",
        "size": "24pt",
        "weight": "bold"
      }
    }
  }
}
```

Load and use the theme:

```
use UbertechZa\AsciidoctorWrapper\StyleManager;

$styleManager = app(StyleManager::class);
$theme = $styleManager->loadFromJson(resource_path('asciidoctor/themes/my-theme.json'));

$result = Asciidoctor::convert('input.adoc', 'output.pdf', 'pdf', $theme);
```

### Theme Inheritance

[](#theme-inheritance)

Themes can extend other themes:

```
{
  "name": "dark-theme",
  "extends": "modern-theme",
  "colors": {
    "text": "#ffffff",
    "background": "#1a1a1a"
  }
}
```

Built-in themes can also be extended:

```
{
  "name": "custom-default",
  "extends": "default",
  "colors": {
    "primary": "#ff6b35"
  }
}
```

Font Management
---------------

[](#font-management)

### Custom Fonts Configuration

[](#custom-fonts-configuration)

The package supports custom fonts for PDF generation. Fonts are automatically loaded from the configured fonts directory and made available to asciidoctor-pdf themes.

#### Setting Up Custom Fonts

[](#setting-up-custom-fonts)

1. **Configure the fonts directory** in `config/asciidoctor.php`:

```
'fonts_path' => env('ASCIIDOCTOR_FONTS_PATH', storage_path('asciidoc/fonts')),
```

2. **Add font files** to your fonts directory:

```
storage/asciidoc/fonts/
├── MyFont-Regular.ttf
├── MyFont-Bold.ttf
├── MyFont-Italic.ttf
├── MyFont-BoldItalic.ttf
├── MonoFont-Regular.ttf
└── MonoFont-Bold.ttf

```

3. **Use fonts in themes** - the package automatically generates the font catalog:

```
$theme = app(ThemeBuilder::class)
    ->name('custom-font-theme')
    ->extending('default-with-font-fallbacks')
    ->withColors([
        'primary' => '#2563eb',
        'text' => '#0f172a'
    ])
    ->build();
```

#### Font Catalog Generation

[](#font-catalog-generation)

When using custom fonts, the package automatically:

- Scans the `fonts_path` directory for TTF files
- Generates a proper font catalog in the theme YAML
- Sets the `pdf-fontsdir` attribute for asciidoctor-pdf
- Maps fonts to appropriate theme elements (base, heading, code)

Example generated theme YAML:

```
extends: default-with-font-fallbacks

font:
  catalog:
    merge: true
    MyFont:
      normal: MyFont-Regular.ttf
      bold: MyFont-Bold.ttf
      italic: MyFont-Italic.ttf
      bold_italic: MyFont-BoldItalic.ttf
    MonoFont:
      normal: MonoFont-Regular.ttf
      bold: MonoFont-Bold.ttf

base:
  font_family: MyFont
  font_size: 11
  font_color: 0f172a

heading:
  font_family: MyFont
  font_color: 2563eb
  font_style: bold

code:
  font_family: MonoFont
  font_size: 9
```

#### Font Environment Variable

[](#font-environment-variable)

Set the fonts directory via environment variable:

```
# Use absolute path
ASCIIDOCTOR_FONTS_PATH=/usr/share/fonts/custom

# Or relative to Laravel storage
ASCIIDOCTOR_FONTS_PATH=/path/to/laravel/storage/asciidoc/fonts
```

#### Supported Font Formats

[](#supported-font-formats)

- **TTF (TrueType)** - Primary supported format
- **OTF (OpenType)** - Also supported by asciidoctor-pdf

#### Font Naming Convention

[](#font-naming-convention)

For automatic detection of font variants, use this naming pattern:

- `FontName-Regular.ttf` (normal weight)
- `FontName-Bold.ttf` (bold weight)
- `FontName-Italic.ttf` (italic style)
- `FontName-BoldItalic.ttf` (bold italic)

Supported Output Formats
------------------------

[](#supported-output-formats)

- `html` / `html5` - HTML output
- `docbook` / `docbook5` - DocBook XML
- `manpage` - Unix manual pages
- `pdf` - PDF documents (requires asciidoctor-pdf)
- `docx` - Microsoft Word documents

```
// Generate multiple formats
$formats = ['html5', 'pdf', 'docx'];

foreach ($formats as $format) {
    $result = Asciidoctor::convert(
        input: 'document.adoc',
        output: "document.{$format}",
        format: $format,
        theme: $theme
    );
}
```

Advanced Configuration
----------------------

[](#advanced-configuration)

### Custom Attributes

[](#custom-attributes)

```
$result = Asciidoctor::convert(
    input: 'document.adoc',
    output: 'document.html',
    format: 'html5',
    attributes: [
        'source-highlighter' => 'rouge',
        'icons' => 'font',
        'sectanchors' => true,
        'toc' => 'left',
        'toclevels' => 3
    ]
);
```

### Safe Mode

[](#safe-mode)

```
$result = Asciidoctor::convert(
    input: 'document.adoc',
    output: 'document.html',
    format: 'html5',
    safeMode: 'safe' // unsafe, safe, server, secure
);
```

Style Objects
-------------

[](#style-objects)

### Color Styles

[](#color-styles)

```
use UbertechZa\AsciidoctorWrapper\Style\ColorStyle;

$colors = new ColorStyle(
    primary: '#2563eb',
    secondary: '#64748b',
    accent: '#059669',
    text: '#0f172a',
    background: '#ffffff'
);

// Validate colors
if ($colors->isValidHex('#2563eb')) {
    echo "Valid hex color!";
}
```

### Font Styles

[](#font-styles)

```
use UbertechZa\AsciidoctorWrapper\Style\FontStyle;

$font = new FontStyle(
    family: 'Inter',
    size: '12pt',
    weight: 'bold',
    style: 'normal'
);

// Convert to array for processing
$fontArray = $font->toArray();
```

### Element Styles

[](#element-styles)

```
use UbertechZa\AsciidoctorWrapper\Style\ElementStyle;

$heading = new ElementStyle(
    color: '#2563eb',
    backgroundColor: '#ffffff',
    font: new FontStyle('Inter', '18pt', 'bold'),
    margin: '1em 0',
    padding: '0.5em'
);
```

Testing and Validation
----------------------

[](#testing-and-validation)

### Check Executable Availability

[](#check-executable-availability)

```
$wrapper = app(AsciidoctorWrapper::class);

if ($wrapper->isAsciidoctorAvailable()) {
    echo "AsciiDoctor is available!";
}

if ($wrapper->isAsciidoctorPdfAvailable()) {
    echo "AsciiDoctor-PDF is available!";
}

$formats = $wrapper->getSupportedFormats();
// ['html', 'html5', 'docbook', 'docbook5', 'manpage', 'pdf', 'docx']
```

### Theme Validation

[](#theme-validation)

```
use UbertechZa\AsciidoctorWrapper\StyleManager;

$styleManager = app(StyleManager::class);
$theme = $styleManager->loadFromJson('theme.json');

if ($styleManager->validateTheme($theme)) {
    echo "Theme is valid!";
} else {
    $errors = $styleManager->getValidationErrors();
    foreach ($errors as $error) {
        echo "Error: {$error}\n";
    }
}
```

Artisan Commands
----------------

[](#artisan-commands)

The package doesn't include Artisan commands by default, but you can create your own:

```