diff --git a/README.md b/README.md
index c538d04..e9a37b6 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,8 @@ by [ALTO Code Highlight](https://github.com/altophp/code-highlight).
[](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,8 +22,6 @@ 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
```
@@ -30,72 +29,13 @@ 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]} %}
-` | `[]` |
+## 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
diff --git a/docs/filter.md b/docs/filter.md
new file mode 100644
index 0000000..cd3d748
--- /dev/null
+++ b/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).
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..45d34b5
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,50 @@
+# Getting started
+
+Create `highlight.php` beside the `vendor` directory:
+
+```php
+ "{{ 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' => 'Hello']), "\n";
+```
+
+Run it:
+
+```console
+$ php highlight.php
+<strong>Hello</strong>
+```
+
+The result is highlighted HTML. The original `` 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 '';
+```
+
+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.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..75c1951
--- /dev/null
+++ b/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)
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..5854316
--- /dev/null
+++ b/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).
diff --git a/docs/options.md b/docs/options.md
new file mode 100644
index 0000000..2b69e0d
--- /dev/null
+++ b/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` | `[]` | 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.
diff --git a/docs/tag.md b/docs/tag.md
new file mode 100644
index 0000000..fa7cda1
--- /dev/null
+++ b/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' %}
+