ubertech-za / asciidoc-renderer
Blade-based AsciiDoc renderer for Laravel
Requires
- php: ^8.2
Requires (Dev)
- laravel/pint: ^1.0
- orchestra/testbench: ^9.0
- pestphp/pest: ^3.0
- phpstan/phpstan: ^1.11
Suggests
- illuminate/filesystem: ^10.0|^11.0|^12.0
- illuminate/support: ^10.0|^11.0|^12.0
- illuminate/view: ^10.0|^11.0|^12.0
This package is auto-updated.
Last update: 2025-09-16 20:46:56 UTC
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
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 AsciiDocubertech-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.