PHPackages                             ubertech-za/asciidoc-renderer - 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. [Templating & Views](/categories/templating)
4. /
5. ubertech-za/asciidoc-renderer

ActiveLibrary[Templating & Views](/categories/templating)

ubertech-za/asciidoc-renderer
=============================

Blade-based AsciiDoc renderer for Laravel

0.1.0(9mo ago)13MITPHPPHP ^8.2

Since Sep 16Pushed 9mo agoCompare

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

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

AsciiDoc Renderer for Laravel
=============================

[](#asciidoc-renderer-for-laravel)

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

[![Latest Version on Packagist](https://camo.githubusercontent.com/7c7c2629130cbe27c49b2164536c00231dbf54f20329997cd0fccb5b641c0736/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f75626572746563682d7a612f6173636969646f632d72656e64657265722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ubertech-za/asciidoc-renderer)[![GitHub Tests Action Status](https://camo.githubusercontent.com/305381e6e525923d6c862373e0b0946528370ea4097cfce02fec1732d3a9cbf2/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f75626572746563682d7a612f6173636969646f632d72656e64657265722f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/ubertech-za/asciidoc-renderer/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/193fd85539db88434df687ad9a0fb758c7e887a71e24cab17a96ac93c46cd438/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f75626572746563682d7a612f6173636969646f632d72656e64657265722f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/ubertech-za/asciidoc-renderer/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/5111a73981459aa2b903a165ca8ae9dde55a87c1806b565dc7b320e1e7bb0a65/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f75626572746563682d7a612f6173636969646f632d72656e64657265722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ubertech-za/asciidoc-renderer)

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
--------

[](#features)

- **Blade-powered AsciiDoc templating** with custom `.adoc.blade` file extension
- **Reusable component system** with `` 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
------------

[](#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)

[](#publish-configuration-optional)

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

### Publish Starter Templates (Optional)

[](#publish-starter-templates-optional)

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

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

[](#quick-start)

### Basic Usage

[](#basic-usage)

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

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

@section('content')
== Introduction

Welcome to !

This document was generated on 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

[](#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
----------------

[](#built-in-layouts)

### Article Layout

[](#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

[](#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
-----------------

[](#custom-directives)

### Document Structure

[](#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

[](#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
-------------------

[](#reusable-components)

Create reusable AsciiDoc components using familiar Laravel Blade component patterns.

### Anonymous Components

[](#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::
@if($contact)
Contact::
@endif
@if($website)
Website:: link:[]
@endif
====
```

Use components in your templates with the `` syntax:

```
== Our Suppliers

```

### Nested Components

[](#nested-components)

Organize components in subdirectories:

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

::
[source,form]
----

----
```

```

```

### Class-Based Components

[](#class-based-components)

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

```