From 5499feb2890f0623ada3ca2553bdcc64aef5f511 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20Andr=C3=A9?= Date: Sat, 19 Sep 2026 23:27:40 +0200 Subject: [PATCH] docs: update structure --- README.md | 76 +++++------------------------------------ docs/filter.md | 21 ++++++++++++ docs/getting-started.md | 50 +++++++++++++++++++++++++++ docs/index.md | 12 +++++++ docs/installation.md | 14 ++++++++ docs/options.md | 45 ++++++++++++++++++++++++ docs/tag.md | 36 +++++++++++++++++++ 7 files changed, 186 insertions(+), 68 deletions(-) create mode 100644 docs/filter.md create mode 100644 docs/getting-started.md create mode 100644 docs/index.md create mode 100644 docs/installation.md create mode 100644 docs/options.md create mode 100644 docs/tag.md 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).   ![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,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' %} +