Update documentation structure

README.md

@@ -9,7 +9,8 @@ by [ALTO Code Highlight](https://github.com/altophp/code-highlight).
   ![License](https://img.shields.io/github/license/altophp/twig-code-highlight?label=License&labelColor=050608&color=00B7FF)
   [![GitHub Sponsors](https://img.shields.io/github/sponsors/smnandre?logo=githubsponsors&logoColor=00B7FF&label=%20Sponsor&labelColor=050608&color=00B7FF)](https://github.com/sponsors/smnandre)
 
-Use the block tag for literal template content or the filter for dynamic source:
+Use the block tag for source written in a template or the filter for source
+provided by your application:
 
 ```twig
 {% code_highlight 'php' %}
@@ -21,81 +22,20 @@ Use the block tag for literal template content or the filter for dynamic source:
 
 ## Installation
 
-Install ALTO Twig Code Highlight with Composer:
-
 ```bash
 composer require alto/twig-code-highlight
 ```
 
 The package requires PHP 8.4 or later, ALTO Code Highlight 1.x, and Twig 3.28
 or later.
 
-## Setup
-
-Register the extension and its runtime:
-
-```php
-use Alto\Twig\CodeHighlight\CodeHighlightExtension;
-use Alto\Twig\CodeHighlight\Runtime\CodeHighlightRuntime;
-use Twig\RuntimeLoader\FactoryRuntimeLoader;
-
-$extension = new CodeHighlightExtension();
-$twig->addExtension($extension);
-
-$twig->addRuntimeLoader(new FactoryRuntimeLoader([
-    CodeHighlightRuntime::class => static fn (): CodeHighlightRuntime => new CodeHighlightRuntime(
-        $extension->getHighlighter(),
-        $extension->getDefaultOptions(),
-    ),
-]));
-```
-
-Default options may be configured on the extension:
-
-```php
-$extension = new CodeHighlightExtension(defaultOptions: [
-    'line_numbers' => true,
-]);
-```
-
-## Quick Start
-
-```twig
-{% code_highlight 'php' with {line_numbers: true, highlight_lines: [2]} %}
-<?php
-
-echo 'Hello world';
-{% endcode_highlight %}
-```
-
-The language may be a Twig expression:
-
-```twig
-{% code_highlight language %}
-const answer = 42;
-{% endcode_highlight %}
-```
-
-## Filter
-
-```twig
-{{ source|code_highlight('javascript') }}
-```
-
-Options are passed as the second argument:
-
-```twig
-{{ source|code_highlight('php', {line_numbers: true, highlight_lines: [1, 3]}) }}
-```
-
-## Options
-
-| Option | Type | Default |
-| --- | --- | --- |
-| `line_numbers` | `bool` | `false` |
-| `highlight_lines` | `array<int>` | `[]` |
+## Documentation
 
-A language is required for both the tag and filter. Configure themes through the core `Highlighter`; see the [theme guide](https://github.com/altophp/code-highlight/blob/main/docs/themes.md).
+- [Installation](docs/installation.md)
+- [Getting started](docs/getting-started.md)
+- [Tag](docs/tag.md)
+- [Filter](docs/filter.md)
+- [Options](docs/options.md)
 
 ## Contributing
 

docs/filter.md

@@ -0,0 +1,21 @@
+# Filter
+
+Use the `code_highlight` filter for source supplied by the application:
+
+```twig
+{{ source|code_highlight('javascript') }}
+```
+
+The language can be a variable, and options are passed as the second argument:
+
+```twig
+{{ source|code_highlight(language, {line_numbers: true, highlight_lines: [1, 3]}) }}
+```
+
+Pass plain, unescaped source. The highlighter escapes source markup and the
+filter marks only its generated result as safe HTML, so `raw` is unnecessary.
+
+Leading and trailing whitespace in the source and language is trimmed. A missing
+or empty language raises an exception, while an unknown identifier raises Code
+Highlight's `LanguageNotFoundException`. See the supported
+[languages](https://altophp.com/code-highlight/languages).

docs/getting-started.md

@@ -0,0 +1,50 @@
+# Getting started
+
+Create `highlight.php` beside the `vendor` directory:
+
+```php
+<?php
+
+require __DIR__.'/vendor/autoload.php';
+
+use Alto\Twig\CodeHighlight\CodeHighlightExtension;
+use Alto\Twig\CodeHighlight\Runtime\CodeHighlightRuntime;
+use Twig\Environment;
+use Twig\Loader\ArrayLoader;
+use Twig\RuntimeLoader\FactoryRuntimeLoader;
+
+$twig = new Environment(new ArrayLoader([
+    'example' => "{{ source|code_highlight('html') }}",
+]), ['autoescape' => 'html']);
+
+$extension = new CodeHighlightExtension();
+$twig->addExtension($extension);
+$twig->addRuntimeLoader(new FactoryRuntimeLoader([
+    CodeHighlightRuntime::class => static fn (): CodeHighlightRuntime => new CodeHighlightRuntime(
+        $extension->getHighlighter(),
+        $extension->getDefaultOptions(),
+    ),
+]));
+
+echo $twig->render('example', ['source' => '<strong>Hello</strong>']), "\n";
+```
+
+Run it:
+
+```console
+$ php highlight.php
+<pre class="alto-highlight language-html"><code class="language-html"><span class="alto-keyword">&lt;</span><span class="alto-keyword">strong</span><span class="alto-keyword">&gt;</span><span class="alto-punctuation">Hello</span><span class="alto-keyword">&lt;/</span><span class="alto-keyword">strong</span><span class="alto-keyword">&gt;</span></code></pre>
+```
+
+The result is highlighted HTML. The original `<strong>` source is escaped inside
+the code block, so it is displayed rather than interpreted as page markup.
+
+Add the theme stylesheet once to the page to see the syntax colors:
+
+```php
+echo '<style>', $extension->getHighlighter()->getTheme()->getStylesheet(), '</style>';
+```
+
+Continue with the [tag](tag.md) for template-owned snippets, the
+[filter](filter.md) for dynamic source, and [options](options.md) for line numbers
+and themes.

docs/index.md

@@ -0,0 +1,12 @@
+# Twig Code Highlight
+
+Highlight source code in Twig templates with the same server-side parsers and
+themes as [ALTO Code Highlight](https://altophp.com/code-highlight). Use a block
+tag for source written in a template or a filter for source supplied as data.
+The generated HTML needs no browser-side highlighter.
+
+- [Installation](installation.md)
+- [Getting started](getting-started.md)
+- [Tag](tag.md)
+- [Filter](filter.md)
+- [Options](options.md)

docs/installation.md

@@ -0,0 +1,14 @@
+# Installation
+
+Install the Twig integration with Composer:
+
+```bash
+composer require alto/twig-code-highlight
+```
+
+The package requires PHP 8.4 or later, Twig 3.28 or later, and ALTO Code
+Highlight 1.x. Composer installs Code Highlight and its `mbstring` and
+`tokenizer` extension requirements.
+
+In a standalone script, load `vendor/autoload.php`. Then register both the
+extension and its runtime loader as shown in [Getting started](getting-started.md).

docs/options.md

@@ -0,0 +1,45 @@
+# Options
+
+The tag and filter accept the same options:
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `line_numbers` | `bool` | `false` | Adds a numbered span to every source line. |
+| `highlight_lines` | `array<int>` | `[]` | Adds `alto-highlighted` to the selected line numbers. |
+
+Set defaults when creating the extension:
+
+```php
+use Alto\Twig\CodeHighlight\CodeHighlightExtension;
+
+$extension = new CodeHighlightExtension(defaultOptions: [
+    'line_numbers' => true,
+    'highlight_lines' => [2],
+]);
+```
+
+Options passed by a tag or filter replace matching defaults for that call. The
+`highlight_lines` array is replaced rather than combined. Only positive integers
+are retained; a non-array value becomes an empty list. Enable `line_numbers` to
+make the selected line styling visible.
+
+## Themes
+
+Pass a configured Code Highlight instance to the extension, then use that same
+instance when registering the runtime:
+
+```php
+use Alto\Code\Highlight\Highlighter;
+use Alto\Code\Highlight\Theme\AltoTheme;
+use Alto\Twig\CodeHighlight\CodeHighlightExtension;
+
+$highlighter = new Highlighter(new AltoTheme());
+$extension = new CodeHighlightExtension($highlighter);
+```
+
+The default is `AltoTheme`. See Code Highlight's [themes](https://altophp.com/code-highlight/themes)
+for built-in themes, adapters, custom themes, and stylesheet output. Emit the
+chosen theme's stylesheet once per page.
+
+Line-number appearance is controlled by application CSS. Target
+`.alto-line-number` and `.alto-line-number.alto-highlighted` when customizing it.

docs/tag.md

@@ -0,0 +1,36 @@
+# Tag
+
+Use the `code_highlight` block tag when the source belongs in the Twig template:
+
+```twig
+{% code_highlight 'php' %}
+<?php
+
+echo 'Hello, Alto!';
+{% endcode_highlight %}
+```
+
+Pass options after `with`:
+
+```twig
+{% code_highlight 'php' with {line_numbers: true, highlight_lines: [3]} %}
+<?php
+
+echo 'Hello, Alto!';
+{% endcode_highlight %}
+```
+
+The language can be any Twig expression:
+
+```twig
+{% code_highlight language %}
+const answer = 42;
+{% endcode_highlight %}
+```
+
+The block captures rendered Twig content before highlighting it. Twig expressions
+inside the block are therefore evaluated. Wrap literal Twig source in `verbatim`,
+or provide it as data through the [filter](filter.md), when it must stay unchanged.
+
+Leading and trailing whitespace is trimmed. A missing or empty language raises an
+exception. See [Options](options.md) for defaults and the complete option list.