README

⚠️ 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 brings Blade templating to AsciiDoc document generation. Generate rich, structured AsciiDoc documents using familiar Blade syntax with specialized directives and escaping for AsciiDoc formatting.

Features

• Blade-powered AsciiDoc templating with custom .adoc.blade file extension
• Reusable component system with <x-adoc::*> syntax for modular document building
• AsciiDoc-specific escaping to prevent formatting conflicts
• Custom Blade directives for common AsciiDoc constructs
• Built-in layouts for articles and books
• Facade support for easy document generation
• Framework-agnostic core with Laravel service provider integration

Installation

You can install the package via Composer:

composer require ubertech-za/asciidoc-renderer

The package will automatically register its service provider in Laravel 5.5+.

Publish Configuration (Optional)

php artisan vendor:publish --provider="UbertechZa\AsciidocRenderer\Laravel\AsciidocRendererServiceProvider" --tag="config"

Publish Starter Templates (Optional)

php artisan vendor:publish --provider="UbertechZa\AsciidocRenderer\Laravel\AsciidocRendererServiceProvider" --tag="asciidoc-views"

Quick Start

Basic Usage

Create an AsciiDoc template at resources/asciidoc/my-document.adoc.blade:

@extends('adoc::layouts.article')

@section('content')
== Introduction

Welcome to <# $title #>!

This document was generated on <# now()->format('Y-m-d') #>.

=== Features

* Dynamic content generation
* AsciiDoc-safe escaping
* Blade directive support

@adocimg('diagram.png', 'System Architecture', ['width' => '600'])

@endsection

Generate the document:

use UbertechZa\AsciidocRenderer\Facades\Asciidoc;

$asciidoc = Asciidoc::render('adoc::my-document', [
    'title' => 'My Amazing Project',
    'author' => 'John Doe',
    'date' => '2025-01-01'
]);

// Or render directly to file
Asciidoc::renderToFile('adoc::my-document', $data, '/path/to/output.adoc');

Custom Template Tags

This package uses non-conflicting Blade tags to avoid issues with AsciiDoc syntax:

• <# ... #> - Escaped output (equivalent to {{ ... }})
• <% ... %> - Raw output (equivalent to {!! ... !!})

Built-in Layouts

Article Layout

Asciidoc::render('adoc::article', [
    'title' => 'My Article',
    'authors' => ['John Doe', 'Jane Smith'],
    'abstract' => 'This article demonstrates...',
    'summary' => 'Key takeaways from this article.',
    'keywords' => ['laravel', 'asciidoc', 'documentation'],
    'sections' => [
        ['title' => 'Introduction', 'body' => 'Welcome to our article...'],
        ['title' => 'Methodology', 'body' => 'We approached this by...'],
        // Or include external files:
        'chapters/conclusion.adoc'
    ]
]);

Book Layout

Perfect for longer documents with multiple chapters:

Asciidoc::render('adoc::book', [
    'title' => 'The Complete Guide',
    'authors' => 'Expert Author',
    'doctype' => 'book',
    'toc' => 'left',
    'toclevels' => 3,
    'chapters' => [
        'introduction.adoc',
        'getting-started.adoc',
        'advanced-topics.adoc'
    ]
]);

Custom Directives

Document Structure

{{-- Level offset management --}}
@offset(2)
== This becomes a level 4 heading
@endoffset

{{-- Raw AsciiDoc output --}}
@adoc('*bold text* and _italic text_')

{{-- Escaped inline content --}}
@adoclit($userInput)  {{-- Escapes AsciiDoc special characters --}}

{{-- Content with automatic newline --}}
@adocnl($paragraph)

Media and Inclusions

{{-- Image with attributes --}}
@adocimg('path/to/image.png', 'Alt text', ['width' => '400', 'align' => 'center'])

{{-- Include external files --}}
@adocinclude('chapters/introduction.adoc', ['lines' => '1..10'])

Reusable Components

Create reusable AsciiDoc components using familiar Laravel Blade component patterns.

Anonymous Components

Create .adoc.blade files in resources/asciidoc/components/ to define reusable components:

{{-- resources/asciidoc/components/supplier.adoc.blade --}}
@props(['name', 'contact' => null, 'website' => null])

[sidebar]
.Supplier: <# $name #>
====
Name:: <# $name #>
@if($contact)
Contact:: <# $contact #>
@endif
@if($website)
Website:: link:<# $website #>[<# parse_url($website, PHP_URL_HOST) ?: $website #>]
@endif
====

Use components in your templates with the <x-adoc::*> syntax:

== Our Suppliers

<x-adoc::supplier name="Acme Corp" contact="sales@acme.com" website="https://acme.com" />

<x-adoc::supplier name="Beta Industries" contact="john@beta.com" />

Nested Components

Organize components in subdirectories:

{{-- resources/asciidoc/components/forms/input.adoc.blade --}}
@props(['label', 'type' => 'text'])

<# $label #>:: 
[source,form]
----
<input type="<# $type #>" />
----

<x-adoc::forms.input label="Username" />
<x-adoc::forms.input label="Password" type="password" />

Class-Based Components

For more complex components, create PHP classes in app/Asciidoc/Components/:

<?php

namespace App\Asciidoc\Components;

use Illuminate\View\Component;

class DataTable extends Component
{
    public function __construct(
        public array $headers,
        public array $rows,
        public ?string $title = null
    ) {}

    public function render()
    {
        return view('adoc::components.data-table');
    }
}

{{-- resources/asciidoc/components/data-table.adoc.blade --}}
@if($title)
.<# $title #>
@endif
[%autowidth]
|===
@foreach($headers as $header)
| <# $header #>
@endforeach

@foreach($rows as $row)
@foreach($row as $cell)
| <# $cell #>
@endforeach
@endforeach
|===

<x-adoc::data-table 
    :headers="['Name', 'Email', 'Role']"
    :rows="[
        ['John Doe', 'john@example.com', 'Admin'],
        ['Jane Smith', 'jane@example.com', 'User']
    ]"
    title="User Directory" />

Component Features

• Props support with @props(['name', 'default' => 'value'])
• Custom echo syntax preserves AsciiDoc formatting
• All Blade directives work within components (@if, @foreach, etc.)
• Nested component support using dot notation
• AsciiDoc-safe output with built-in escaping

Configuration

The config/asciidoc-renderer.php file contains:

return [
    // Template search paths
    'paths' => [
        resource_path('asciidoc'),
        // Add additional paths as needed
    ],

    // Default output directory for generated files
    'output_path' => storage_path('app/asciidoc'),
];

Advanced Usage

Custom Template Renderer

Implement your own renderer by creating a class that implements TemplateRenderer:

use UbertechZa\AsciidocRenderer\Contracts\TemplateRenderer;

class MyCustomRenderer implements TemplateRenderer
{
    public function render(string $template, array $data = []): string
    {
        // Your custom rendering logic
    }
}

// Bind in a service provider
$this->app->bind(TemplateRenderer::class, MyCustomRenderer::class);

Direct Generator Usage

use UbertechZa\AsciidocRenderer\AsciidocGenerator;
use UbertechZa\AsciidocRenderer\Rendering\BladeRenderer;

$generator = new AsciidocGenerator(
    new BladeRenderer(app('view'))
);

$output = $generator->render('my-template', $data);
$generator->renderToFile('my-template', $data, '/path/to/file.adoc');

Document Variables

Common document attributes you can pass to templates:

[
    // Document metadata
    'doctype' => 'article|book',
    'title' => 'Document Title',
    'subtitle' => 'Optional Subtitle',
    'authors' => ['Author One', 'Author Two'], // or string
    
    // Revision information
    'revnumber' => '1.0',
    'revdate' => '2025-01-01',
    'revremark' => 'Initial release',
    
    // Formatting options
    'toc' => 'auto|left|right|macro',
    'toclevels' => 3,
    'sectnums' => true,
    'icons' => true,
    'source_highlighter' => 'rouge',
    'linenums' => true,
    
    // Paths
    'imagesdir' => 'images',
    'docdir' => base_path('docs'),
]

Testing

composer test

Code Style

composer format

Static Analysis

composer analyse

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Uber Technologies cc
• All Contributors

This package is inspired by and builds upon the architectural patterns from:

• thephpleague/html-to-markdown (MIT License)
• tiptap/html for JSON ↔︎ HTML conversion patterns

License

The MIT License (MIT). Please see License File for more information.

Part of PHP AsciiDoc Tool Chain

This package is part of the PHP AsciiDoc Tool Chain project, which aims to provide comprehensive AsciiDoc generation capabilities for PHP applications. Other packages in the tool chain:

• ubertech-za/html-to-asciidoc - Convert HTML to AsciiDoc
• ubertech-za/tiptap-to-asciidoc - Convert Tiptap JSON to AsciiDoc

Together, these packages enable rich document authoring workflows in familiar web-based editors with professional AsciiDoc output suitable for technical documentation, books, and publishing workflows.