Usage Reference | Asciidoc Php | Webware Documentation

This document describes every option available when using asciidoc-php, both from the command line and from the PHP API.

1. Command-line Interface

The bin/asciidoc-php binary converts one or more AsciiDoc source files to the configured output format.

1.1. Synopsis

asciidoc-php [options] FILE [FILE ...]
asciidoc-php [options] -          # read from STDIN, write to STDOUT

1.2. Options

1.2.1. `-b, --backend BACKEND`

Select the output backend.

Value Description

Value	Description
`html5` (default)	HTML 5 output via the bundled `Html5Converter`

html5 (default)

HTML 5 output via the bundled Html5Converter

Only html5 is implemented in v0.1. The flag is accepted for forward-compatibility.

1.2.2. `-d, --doctype DOCTYPE`

Set the document type, which controls which structural sections are valid and how the header is rendered.

Value Description

Value	Description
`article` (default)	Standard article — single-part document
`book`	Multi-part book — accepts `= Part Title` level-0 sections
`manpage`	UNIX man-page — `NAME`, `SYNOPSIS`, `DESCRIPTION` structure
`inline`	Fragment — renders a single inline paragraph, no block wrapper

article (default)

Standard article — single-part document

book

Multi-part book — accepts = Part Title level-0 sections

manpage

UNIX man-page — NAME, SYNOPSIS, DESCRIPTION structure

inline

Fragment — renders a single inline paragraph, no block wrapper

1.2.3. `-o, --out-file FILE`

Write the converted output to FILE instead of the default location.

Use - to write to STDOUT.
When converting multiple input files this flag applies to every file in sequence; prefer --destination-dir for batch conversion.

1.2.4. `-D, --destination-dir DIR`

Place all converted output files into DIR.

The directory is created automatically (including intermediate directories) if it does not exist.
Each output file is named after the input file with its extension replaced by .html.

asciidoc-php -D html/ docs/*.adoc

1.2.5. `-B, --base-dir DIR`

Override the base directory used to resolve include:: directives.

Defaults to the directory of the input file when --out-file / a positional path is given, or the current working directory for STDIN.

1.2.6. `-S, --safe-mode MODE`

Control which features are available based on trust level.

Value Integer Description

Value	Integer	Description
`unsafe`	0	All features enabled; use only for fully trusted input
`safe`	1 (default)	Standard restrictions; external includes allowed from within `base-dir`
`server`	10	Stricter; restricts access to the filesystem above `base-dir`
`secure`	20	Maximum restriction; `include::` disabled, no filesystem access

unsafe

All features enabled; use only for fully trusted input

safe

1 (default)

Standard restrictions; external includes allowed from within base-dir

server

Stricter; restricts access to the filesystem above base-dir

secure

Maximum restriction; include:: disabled, no filesystem access

1.2.7. `-a, --attribute KEY[=VALUE]`

Set (or unset) a document attribute. Repeatable.

Form Effect

Form	Effect
`-a mykey`	Sets `mykey` to an empty string
`-a mykey=myvalue`	Sets `mykey` to `myvalue`
`-a mykey!`	Explicitly unsets `mykey`

-a mykey

Sets mykey to an empty string

-a mykey=myvalue

Sets mykey to myvalue

-a mykey!

Explicitly unsets mykey

Attributes set via -a are applied before the document header is read, so they can be referenced in the source. They cannot be overridden by attribute entries in the source file (they are locked).

Common attributes you may want to set via -a:

Attribute Purpose

Attribute	Purpose
`toc`	Enable table of contents (`auto`, `left`, `right`)
`toc-title`	Override TOC heading text (default: `Table of Contents`)
`sectnums`	Auto-number sections
`icons`	Enable icons; set to `font` to use Font Awesome
`source-highlighter`	Syntax highlighter (`highlight.js`)
`skip-front-matter`	Strip leading YAML front matter before parsing (see YAML Front Matter)
`imagesdir`	Base path prepended to all `image::` targets
`experimental`	Enable UI macro (`btn:[]`, `kbd:[]`, `menu:[]`)
`docinfo`	Inject external docinfo files (`shared`, `private`, `shared-head`, etc.)

toc

Enable table of contents (auto, left, right)

toc-title

Override TOC heading text (default: Table of Contents)

sectnums

Auto-number sections

icons

Enable icons; set to font to use Font Awesome

source-highlighter

Syntax highlighter (highlight.js)

skip-front-matter

Strip leading YAML front matter before parsing (see YAML Front Matter)

imagesdir

Base path prepended to all image:: targets

experimental

Enable UI macro (btn:[], kbd:[], menu:[])

docinfo

Inject external docinfo files (shared, private, shared-head, etc.)

1.2.8. `-s, --no-header-footer`

Produce an embedded (fragment) document — omit the <html>, <head>, and <body> wrapper elements. Useful when embedding the output into an existing page.

1.2.9. `--concurrency N`

Maximum number of files to convert concurrently when processing multiple input files.

Value Behaviour

Value	Behaviour
`0` (default)	Sequential (no concurrency)
Any positive integer	Cap concurrent conversions at N

0 (default)

Sequential (no concurrency)

Any positive integer

Cap concurrent conversions at N

1.2.10. `-q, --quiet`

Suppress all informational messages. Only fatal errors are written to STDERR.

1.2.11. `-v, --verbose`

Log each converted file to the logger (or STDOUT) after it completes.

1.2.12. `-t, --timings`

Print a timing breakdown for each file after conversion.

1.2.13. `--trace`

Print a full PHP stack trace when a conversion error is caught. Without this flag only the error message is shown.

1.2.14. `-h, --help`

Print the help message and exit with code 0.

1.2.15. `--version`

Print the library version string and exit with code 0.

1.3. Examples

Convert a single file (output alongside source)

asciidoc-php docs/guide.adoc

Convert with left-sidebar TOC

asciidoc-php -a toc=left docs/guide.adoc

Convert multiple files to an output directory

asciidoc-php -D html/ docs/*.adoc

Read from STDIN, write to STDOUT (pipeline)

cat fragment.adoc | asciidoc-php -s -o - -

Set multiple attributes

asciidoc-php -a toc=left -a sectnums -a icons=font docs/guide.adoc

Strip YAML front matter

asciidoc-php -a skip-front-matter docs/page.adoc

Quiet batch conversion

asciidoc-php -q -D out/ docs/*.adoc

2. PHP API

2.1. `Asciidoc::convert()`

Convert an AsciiDoc string directly.

use Webware\AsciidocPhp\Asciidoc;

$html = Asciidoc::convert($source, $opts);

$source is any valid AsciiDoc string. $opts is an optional associative array — see API Option Keys for all recognised keys.

2.2. `Asciidoc::convertFile()`

Read an AsciiDoc file from disk and convert it.

$html = Asciidoc::convertFile('/path/to/guide.adoc', $opts);

Throws \RuntimeException if the file does not exist or cannot be read.
base_dir defaults to dirname($path) when not supplied.

2.3. API Option Keys

Key Type Default Description

Key	Type	Default	Description
`backend`	`string`	`'html5'`	Output backend. Currently only `'html5'` is supported.
`doctype`	`string`	`'article'`	Document type: `article`, `book`, `manpage`, `inline`.
`safe`	`SafeMode`	`SafeMode::SAFE`	Trust level. Pass a `\Webware\AsciidocPhp\SafeMode` enum case.
`attributes`	`array<string, string\|false>`	`[]`	Initial document attributes. `false` explicitly unsets an attribute; a string sets it. Keys set here are locked — the document header cannot override them.
`header_footer`	`bool`	`true`	When `false`, output is an embedded fragment (no `<html>`/`<head>`/`<body>`).
`base_dir`	`string\|null`	`null`	Base directory for `include::` resolution. Defaults to `dirname($path)` for `convertFile()`.
`converter`	`ConverterInterface`	`Html5Converter`	Custom converter instance. Implement `\Webware\AsciidocPhp\Converter\ConverterInterface` to supply your own.
`sourcemap`	`bool`	`false`	Attach source-location metadata to AST nodes (for tooling / IDE use).

backend

string

'html5'

Output backend. Currently only 'html5' is supported.

doctype

string

'article'

Document type: article, book, manpage, inline.

safe

SafeMode

SafeMode::SAFE

Trust level. Pass a \Webware\AsciidocPhp\SafeMode enum case.

attributes

array<string, string|false>

[]

Initial document attributes. false explicitly unsets an attribute; a string sets it. Keys set here are locked — the document header cannot override them.

header_footer

bool

true

When false, output is an embedded fragment (no <html>/<head>/<body>).

base_dir

string|null

null

Base directory for include:: resolution. Defaults to dirname($path) for convertFile().

converter

ConverterInterface

Html5Converter

Custom converter instance. Implement \Webware\AsciidocPhp\Converter\ConverterInterface to supply your own.

sourcemap

bool

false

Attach source-location metadata to AST nodes (for tooling / IDE use).

2.4. API Examples

Minimal conversion

$html = Asciidoc::convert('= Hello World');

Embedded fragment

$fragment = Asciidoc::convert($source, ['header_footer' => false]);

Set attributes programmatically

$html = Asciidoc::convert($source, [
    'attributes' => [
        'toc'              => 'left',
        'sectnums'         => '',
        'icons'            => 'font',
        'source-highlighter' => 'highlight.js',
    ],
]);

Strip YAML front matter and read promoted attributes

use Webware\AsciidocPhp\Asciidoc;
use Webware\AsciidocPhp\Document;
use Webware\AsciidocPhp\Parser\Parser;
use Webware\AsciidocPhp\Reader\Cursor;
use Webware\AsciidocPhp\Reader\PreprocessorReader;

// High-level: skip-front-matter via the facade
$html = Asciidoc::convertFile('page.adoc', [
    'attributes' => ['skip-front-matter' => ''],
]);

// The raw YAML block is available as the `front-matter` document attribute
// after the parse if you work at the lower-level API.

Use a strict safe mode

use Webware\AsciidocPhp\SafeMode;

$html = Asciidoc::convertFile('untrusted.adoc', [
    'safe' => SafeMode::SECURE,
]);

3. YAML Front Matter

When the skip-front-matter attribute is set, asciidoc-php recognises a YAML front matter block at the very start of the document.

3.1. Format

The block is delimited by --- on its own line, must begin on the first line of the file, and must be closed by a second --- line before any AsciiDoc content.

---
layout: default
title: "My Page"
author: Alice
---
= My Page
Alice
:toc: left

Document body starts here.

3.2. Behaviour

Rule Detail

Rule	Detail
Activation	Front matter is only parsed when `skip-front-matter` is set; otherwise the `---` lines are treated as literal content.
Storage	The raw YAML text (between the delimiters, delimiters excluded) is stored in the `front-matter` document attribute.
Attribute promotion	Simple scalar `key: value` pairs are promoted as document attributes.
Quote stripping	Values wrapped in `"…"` or `'…'` have their surrounding quotes stripped.
No override	A promoted key never overwrites an attribute already set on the document (e.g. via `-a`).
Unclosed block	If no closing `---` is found, the lines are restored and no front matter is extracted.

Activation

Front matter is only parsed when skip-front-matter is set; otherwise the --- lines are treated as literal content.

Storage

The raw YAML text (between the delimiters, delimiters excluded) is stored in the front-matter document attribute.

Attribute promotion

Simple scalar key: value pairs are promoted as document attributes.

Quote stripping

Values wrapped in "…" or '…' have their surrounding quotes stripped.

No override

A promoted key never overwrites an attribute already set on the document (e.g. via -a).

Unclosed block

If no closing --- is found, the lines are restored and no front matter is extracted.

3.3. Activating via CLI

asciidoc-php -a skip-front-matter docs/page.adoc

3.4. Activating via API

$html = Asciidoc::convertFile('page.adoc', [
    'attributes' => ['skip-front-matter' => ''],
]);

4. Document Attributes Reference

The following built-in attributes are set automatically on every document. They can be read by the document source, overridden via -a / attributes, or queried from Document::getAttribute().

4.1. Read-only (set by the converter)

Attribute Value

Attribute	Value
`asciidoc-version`	Library version string (e.g. `0.1.0`)
`asciidoctor-version`	Same as `asciidoc-version`
`backend`	Active backend name (e.g. `html5`)
`basebackend`	Base backend family (`html`, `docbook`)
`doctype`	Active doctype (e.g. `article`)
`encoding`	Always `UTF-8`
`filetype`	Output file type (e.g. `html`)
`outfilesuffix`	Output file extension (e.g. `.html`)
`docdate`	Date the document was converted (`YYYY-MM-DD`)
`doctime`	Time the document was converted (`HH:MM:SS`)
`docdatetime`	Date + time combined
`localdate`	Same as `docdate`
`localtime`	Same as `doctime`
`localdatetime`	Same as `docdatetime`

asciidoc-version

Library version string (e.g. 0.1.0)

asciidoctor-version

Same as asciidoc-version

backend

Active backend name (e.g. html5)

basebackend

Base backend family (html, docbook)

doctype

Active doctype (e.g. article)

encoding

Always UTF-8

filetype

Output file type (e.g. html)

outfilesuffix

Output file extension (e.g. .html)

docdate

Date the document was converted (YYYY-MM-DD)

doctime

Time the document was converted (HH:MM:SS)

docdatetime

Date + time combined

localdate

Same as docdate

localtime

Same as doctime

localdatetime

Same as docdatetime

4.2. Configurable

Attribute Default Description

Attribute	Default	Description
`toc`	(unset)	Enable TOC and set placement: `auto` (inline after title), `left`, `right`
`toc-title`	`Table of Contents`	Heading text shown above the TOC
`toc-placement`	`auto`	Alternative placement key; `left` and `right` work the same as `:toc: left/right`
`sectnums`	(unset)	Auto-number sections when set
`sectanchors`	(unset)	Prepend anchor links to section titles when set
`sectlinks`	(unset)	Make section titles clickable anchor links when set
`icons`	(unset)	Set to `font` to use Font Awesome icons in admonitions
`source-highlighter`	(unset)	Set to `highlight.js` to enable client-side syntax highlighting
`skip-front-matter`	(unset)	Strip leading YAML front matter when set
`imagesdir`	(unset)	Prepended to all `image::` / `image:` target paths
`experimental`	(unset)	Enable UI macros (`btn:[]`, `kbd:[]`, `menu:[]`) when set
`caution-caption`	`Caution`	Label for CAUTION admonition blocks
`important-caption`	`Important`	Label for IMPORTANT admonition blocks
`note-caption`	`Note`	Label for NOTE admonition blocks
`tip-caption`	`Tip`	Label for TIP admonition blocks
`warning-caption`	`Warning`	Label for WARNING admonition blocks
`table-caption`	`Table`	Caption prefix for auto-numbered tables
`figure-caption`	`Figure`	Caption prefix for auto-numbered figures
`example-caption`	`Example`	Caption prefix for auto-numbered examples

toc

(unset)

Enable TOC and set placement: auto (inline after title), left, right

toc-title

Table of Contents

Heading text shown above the TOC

toc-placement

auto

Alternative placement key; left and right work the same as :toc: left/right

sectnums

(unset)

Auto-number sections when set

sectanchors

(unset)

Prepend anchor links to section titles when set

sectlinks

(unset)

Make section titles clickable anchor links when set

icons

(unset)

Set to font to use Font Awesome icons in admonitions

source-highlighter

(unset)

Set to highlight.js to enable client-side syntax highlighting

skip-front-matter

(unset)

Strip leading YAML front matter when set

imagesdir

(unset)

Prepended to all image:: / image: target paths

experimental

(unset)

Enable UI macros (btn:[], kbd:[], menu:[]) when set

caution-caption

Caution

Label for CAUTION admonition blocks

important-caption

Important

Label for IMPORTANT admonition blocks

note-caption

Note

Label for NOTE admonition blocks

tip-caption

Tip

Label for TIP admonition blocks

warning-caption

Warning

Label for WARNING admonition blocks

table-caption

Table

Caption prefix for auto-numbered tables

figure-caption

Figure

Caption prefix for auto-numbered figures

example-caption

Example

Caption prefix for auto-numbered examples

1. Command-line Interface

1.1. Synopsis

1.2. Options

1.2.1. -b, --backend BACKEND

1.2.2. -d, --doctype DOCTYPE

1.2.3. -o, --out-file FILE

1.2.4. -D, --destination-dir DIR

1.2.5. -B, --base-dir DIR

1.2.6. -S, --safe-mode MODE

1.2.7. -a, --attribute KEY[=VALUE]

1.2.8. -s, --no-header-footer

1.2.9. --concurrency N

1.2.10. -q, --quiet

1.2.11. -v, --verbose

1.2.12. -t, --timings

1.2.13. --trace

1.2.14. -h, --help

1.2.15. --version

1.3. Examples

2. PHP API

2.1. Asciidoc::convert()

2.2. Asciidoc::convertFile()

2.3. API Option Keys

2.4. API Examples

3. YAML Front Matter

3.1. Format

3.2. Behaviour

3.3. Activating via CLI

3.4. Activating via API

4. Document Attributes Reference

4.1. Read-only (set by the converter)

4.2. Configurable

1.2.1. `-b, --backend BACKEND`

1.2.2. `-d, --doctype DOCTYPE`

1.2.3. `-o, --out-file FILE`

1.2.4. `-D, --destination-dir DIR`

1.2.5. `-B, --base-dir DIR`

1.2.6. `-S, --safe-mode MODE`

1.2.7. `-a, --attribute KEY[=VALUE]`

1.2.8. `-s, --no-header-footer`

1.2.9. `--concurrency N`

1.2.10. `-q, --quiet`

1.2.11. `-v, --verbose`

1.2.12. `-t, --timings`

1.2.13. `--trace`

1.2.14. `-h, --help`

1.2.15. `--version`

2.1. `Asciidoc::convert()`

2.2. `Asciidoc::convertFile()`