altophp · smnandre · Aug 13, 2026 · Aug 13, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -1,20 +1,17 @@
 * text=auto eol=lf
 
-/.github/                   export-ignore
-/.gitattributes             export-ignore
-/.gitignore                 export-ignore
-/.php-cs-fixer.dist.php     export-ignore
-/phpstan.neon.dist          export-ignore
-/phpunit.xml.dist           export-ignore
-/bin/                       export-ignore
-/docs/                      export-ignore
-/examples/                  export-ignore
-/tests/                     export-ignore
-/tools/                     export-ignore
+/.gitattributes              export-ignore
+/.github                     export-ignore
+/.gitignore                  export-ignore
+/.php-cs-fixer.dist.php      export-ignore
+/bin                         export-ignore
+/docs                        export-ignore
+/examples                    export-ignore
+/phpstan.neon.dist           export-ignore
+/phpunit.xml.dist            export-ignore
+/tests                       export-ignore
+/tools                       export-ignore
 
-/bin/**                     linguist-vendored
-/docs/**                    linguist-documentation
-/examples/**                linguist-documentation
-/tests/**                   linguist-vendored
-/tests/Language/**/*.html   linguist-generated
-/tools/**                   linguist-vendored
+/docs/**                     linguist-documentation
+/examples/**                 linguist-documentation
+/tests/Language/**           -linguist-detectable
diff --git a/.gitignore b/.gitignore
@@ -1,9 +1,8 @@
-/.phpunit.cache/
-/var/
 /vendor/
-/.php-cs-fixer.php
+/composer.lock
+/.phpunit.cache/
+/.phpunit.result.cache
 /.php-cs-fixer.cache
+/coverage/
 /coverage.xml
-/composer.lock
-/phpstan.neon
-/phpunit.xml
+/clover.xml
diff --git a/.php-cs-fixer.dist.php b/.php-cs-fixer.dist.php
@@ -1,34 +1,28 @@
 <?php
 
+declare(strict_types=1);
+
 $licence = <<<'EOF'
 This file is part of the ALTO library.
 
-© 2026–present Simon André
+© 2026-present Simon André
 
 For full copyright and license information, please see
 the LICENSE file distributed with this source code.
 EOF;
 
-$finder = (new PhpCsFixer\Finder())
-    ->in([
-        __DIR__.'/src',
-        __DIR__.'/tests',
-    ])
-    ->exclude([
-        'Language/php',
-    ])
-;
+$finder = PhpCsFixer\Finder::create()
+    ->in([__DIR__.'/src', __DIR__.'/tests'])
+    ->exclude('Language/php');
 
 return (new PhpCsFixer\Config())
-    ->setParallelConfig(PhpCsFixer\Runner\Parallel\ParallelConfigFactory::detect())
-    ->setFinder($finder)
     ->setRiskyAllowed(true)
     ->setRules([
-        '@PER-CS' => true,
-        '@Symfony' => true,
+        '@PER-CS2.0' => true,
         'declare_strict_types' => true,
         'header_comment' => ['header' => $licence],
-        'ordered_imports' => ['sort_algorithm' => 'alpha'],
         'no_unused_imports' => true,
+        'ordered_imports' => ['imports_order' => ['class', 'function', 'const']],
+        'phpdoc_line_span' => ['const' => 'multi', 'property' => 'multi', 'method' => 'multi'],
     ])
-;
+    ->setFinder($finder);
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,21 +1,11 @@
-# Changelog
+# CHANGELOG
 
-All notable changes to this project will be documented in this file.
+## [Unreleased]
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+- Rework documentation.
 
 ## [1.0.0] - 2026-08-09
 
-### Added
-
-- Syntax highlighting
-- 27 languages
-- Embedded languages
-- 12 themes
-- External theme adapters
-- Line numbers and highlighting
-- Zero runtime dependencies
-- Guides and examples
+- Initial release.
 
 [1.0.0]: https://github.com/altophp/code-highlight/releases/tag/v1.0.0
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026-Present Simon André
+Copyright (c) 2026-present Simon André
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -1,11 +1,13 @@
-# ALTO \ Code Highlight
+# ALTO Code Highlight
 
 Server-side syntax highlighting for PHP applications, with semantic scopes,
 embedded languages, and no third-party PHP package dependencies at runtime.
 
-[![CI](https://github.com/altophp/code-highlight/actions/workflows/CI.yml/badge.svg)](https://github.com/altophp/code-highlight/actions/workflows/CI.yml)
-[![PHP](https://img.shields.io/badge/PHP-8.4%2B-777BB4?logo=php&logoColor=white)](https://www.php.net/)
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+&nbsp; ![PHP Version](https://img.shields.io/badge/PHP-8.4%2B-00B7FF?logoColor=00B7FF&labelColor=050608)
+&nbsp; ![CI](https://img.shields.io/github/actions/workflow/status/altophp/code-highlight/CI.yml?branch=main&label=Tests&labelColor=050608&color=00B7FF)
+&nbsp; [![Packagist](https://img.shields.io/packagist/v/alto/code-highlight?label=Packagist&labelColor=050608&color=00B7FF)](https://packagist.org/packages/alto/code-highlight)
+&nbsp; ![License](https://img.shields.io/github/license/altophp/code-highlight?label=License&labelColor=050608&color=00B7FF)
+&nbsp; [![GitHub Sponsors](https://img.shields.io/github/sponsors/smnandre?logo=githubsponsors&logoColor=00B7FF&label=%20Sponsor&labelColor=050608&color=00B7FF)](https://github.com/sponsors/smnandre)
 
 ![PHP highlighted with the Alto Dark theme](docs/assets/examples/alto-dark/php.png)
 
@@ -14,22 +16,22 @@ process, or external service. Its parsers assign semantic scopes, so themes can
 distinguish a function definition from a call or a type definition from a
 reference.
 
-## Install
+## Installation
+
+Install ALTO Code Highlight with Composer:
 
 ```bash
 composer require alto/code-highlight
 ```
 
-Requirements:
-
-- PHP 8.4 or later;
-- `ext-mbstring`;
-- `ext-tokenizer`.
+ALTO Code Highlight requires PHP 8.4 or later, Mbstring, and Tokenizer.
+Tokenizer is included with PHP; Mbstring is available in most PHP distributions
+but must be enabled.
 
 See the [installation guide](docs/installation.md) for verification and
 troubleshooting.
 
-## Quick start
+## Quick Start
 
 ```php
 <?php
@@ -69,12 +71,12 @@ once per page, then reuse the highlighter for every code block.
 |---|---|
 | [Documentation index](docs/index.md) | Choose the right guide |
 | [Getting started](docs/getting-started.md) | Complete rendering, line numbers, and errors |
-| [Languages](docs/languages.md) | Exact identifiers and language capabilities |
-| [Themes](docs/themes.md) | Built-in variants and visual examples |
-| [Create a theme](docs/creating-a-theme.md) | Implement `ThemeInterface` |
-| [Embedded languages](docs/embedded-languages.md) | HTML, SVG, Markdown, and Twig |
-| [Theme adapters](docs/theme-adapters.md) | Highlight.js, Prism, and TextMate |
-| [Public API](docs/public-api.md) | Supported entry points and extension contracts |
+| [Languages](docs/languages/index.md) | Exact identifiers and language capabilities |
+| [Themes](docs/theming/index.md) | Built-in variants and visual examples |
+| [Create a theme](docs/theming/creating.md) | Implement `ThemeInterface` |
+| [Embedded languages](docs/languages/embedded.md) | HTML, SVG, Markdown, and Twig |
+| [Theme adapters](docs/theming/adapters.md) | Highlight.js, Prism, and TextMate |
+| [Public API](docs/api/index.md) | Supported entry points and extension contracts |
 | [Examples](docs/examples.md) | Compact examples and generated previews |
 
 The complete source examples are available in [`examples/languages/`](examples/languages/).
@@ -93,7 +95,7 @@ xml         yaml
 ```
 
 The special `php-snippet` identifier accepts PHP without an opening `<?php`
-tag. The [language reference](docs/languages.md) documents exact behavior and
+tag. The [language reference](docs/languages/index.md) documents exact behavior and
 embedded-language support.
 
 ## Line numbers and highlighted lines
@@ -116,9 +118,9 @@ $light = new GitHubTheme(dark: false);
 $dark = new GitHubTheme();
 ```
 
-Browse the [built-in theme matrix](docs/themes.md), learn how to
-[create a theme](docs/creating-a-theme.md), or reuse an existing stylesheet
-through a [theme adapter](docs/theme-adapters.md).
+Browse the [built-in theme matrix](docs/theming/index.md), learn how to
+[create a theme](docs/theming/creating.md), or reuse an existing stylesheet
+through a [theme adapter](docs/theming/adapters.md).
 
 ## Integrations
 
@@ -129,16 +131,33 @@ static generators, or any PHP rendering pipeline.
 
 ## Contributing
 
-Issues and pull requests are welcome. Before proposing a change, run:
+Contributions of all kinds are welcome. Visit the
+[project on GitHub](https://github.com/altophp/code-highlight) to
+[report a bug](https://github.com/altophp/code-highlight/issues/new),
+[suggest a feature](https://github.com/altophp/code-highlight/issues/new), or
+[open a pull request](https://github.com/altophp/code-highlight/pulls).
+
+Before submitting code, run:
 
 ```bash
+# Runs PHP CS Fixer, PHPStan, and PHPUnit
 composer qa
 ```
 
 Language parsers use fixtures under `tests/Language/`. Public showcase examples
 live separately under `examples/languages/`; they are short documentation
 samples rather than exhaustive parser tests.
 
+## Support
+
+ALTO Code Highlight is open source. You can support its continued development through
+[GitHub Sponsors](https://github.com/sponsors/smnandre).
+
+Sharing this package with others or
+[starring it on GitHub](https://github.com/altophp/code-highlight) is also much
+appreciated.
+
 ## License
 
-ALTO Code Highlight is released under the [MIT License](LICENSE).
+ALTO Code Highlight is released by [ALTO PHP](https://altophp.com) under the
+[MIT License](LICENSE).
diff --git a/composer.json b/composer.json
@@ -1,6 +1,6 @@
 {
     "name": "alto/code-highlight",
-    "description": "Server-side syntax highlighting for PHP with 27 languages, semantic scopes, embedded languages, and adaptable themes",
+    "description": "Server-side syntax highlighting for PHP with semantic scopes, embedded languages, and adaptable themes.",
     "license": "MIT",
     "type": "library",
     "keywords": [
@@ -21,10 +21,11 @@
             "email": "smn.andre@gmail.com"
         }
     ],
-    "homepage": "https://github.com/altophp/code-highlight",
+    "homepage": "https://altophp.com/code-highlight",
     "support": {
         "issues": "https://github.com/altophp/code-highlight/issues",
-        "docs": "https://github.com/altophp/code-highlight/blob/main/docs/index.md"
+        "source": "https://github.com/altophp/code-highlight",
+        "docs": "https://altophp.com/code-highlight"
     },
     "funding": [
         {
@@ -41,12 +42,10 @@
         "ext-simplexml": "Required by the optional TextMate theme adapter"
     },
     "require-dev": {
-        "friendsofphp/php-cs-fixer": "^3.68",
-        "phpstan/phpstan": "^2.0",
-        "phpunit/phpunit": "^12.0"
+        "friendsofphp/php-cs-fixer": "^3.94",
+        "phpstan/phpstan": "^2.1",
+        "phpunit/phpunit": "^12.5"
     },
-    "minimum-stability": "stable",
-    "prefer-stable": true,
     "autoload": {
         "psr-4": {
             "Alto\\Code\\Highlight\\": "src/"
@@ -61,7 +60,8 @@
         "sort-packages": true
     },
     "scripts": {
-        "cs": "vendor/bin/php-cs-fixer fix --diff",
+        "cs": "vendor/bin/php-cs-fixer fix --dry-run --diff --sequential",
+        "cs:fix": "vendor/bin/php-cs-fixer fix --sequential",
         "docs:capture": "npm --prefix tools/docs-showcase run capture",
         "docs:generate": "composer --working-dir=tools/docs-showcase generate",
         "docs:refresh": [
@@ -76,7 +76,7 @@
             "@test"
         ],
         "sa": "vendor/bin/phpstan analyse --memory-limit=-1",
-        "test": "vendor/bin/phpunit",
+        "test": "phpunit",
         "coverage": "vendor/bin/phpunit --coverage-text"
     }
 }
diff --git a/docs/public-api.md → docs/api/index.md b/docs/public-api.md → docs/api/index.md
@@ -26,8 +26,8 @@ values form the semantic vocabulary supplied to themes. The built-in theme
 classes and the Highlight.js, Prism, and TextMate adapters are supported public
 implementations.
 
-See [Creating a theme](creating-a-theme.md) and
-[Theme adapters](theme-adapters.md) for complete examples.
+See [Creating a theme](../theming/creating.md) and
+[Theme adapters](../theming/adapters.md) for complete examples.
 
 ## Language extension contract
 
@@ -40,7 +40,8 @@ Embedded parsers use `EmbeddedLanguageCapable`, `EmbeddedLanguageContext`, and
 the types under `Alto\Code\Highlight\Embedded`. Their documented constructors
 and public methods are covered by the same 1.x compatibility promise.
 
-See [Languages](languages.md) and [Embedded languages](embedded-languages.md)
+See [Languages](../languages/index.md) and
+[Embedded languages](../languages/embedded.md)
 for usage and behavior.
 
 ## Exceptions

diff --git a/docs/examples.md b/docs/examples.md
@@ -4,9 +4,9 @@ The repository contains one curated, compact source example for each of the 27
 default languages. The same stable inputs drive documentation previews and
 parser checks.
 
-Browse the complete source catalog in
-[`examples/languages/`](../examples/languages/), or use the individual links in
-the [language reference](languages.md).
+Browse the complete source catalog on
+[GitHub](https://github.com/altophp/code-highlight/tree/main/examples/languages),
+or use the individual links in the [language reference](languages/index.md).
 
 ## Featured preview matrix
 
@@ -63,45 +63,6 @@ API.
 |---|---|
 | ![CSS highlighted with GitHub Dark](assets/examples/github-dark/css.png) | ![CSS highlighted with GitHub Light](assets/examples/github-light/css.png) |
 
-## Generate previews locally
-
-The isolated showcase tool can render a specific language/theme pair, one
-language across themes, one theme across languages, or its default featured
-matrix:
-
-```bash
-cd tools/docs-showcase
-composer install
-npm install
-npx playwright install chromium
-
-npm run refresh
-npm run generate -- --language=php
-npm run generate -- --theme=alto-dark
-npm run generate -- --language=php --theme=github-light
-npm run capture -- --language=php --theme=github-light
-```
-
-`refresh` generates, captures, and verifies the featured matrix. Use `--all`
-with the `generate`, `capture`, and `verify` commands for the complete
-language/theme matrix. Generated intermediate HTML stays under
-`tools/docs-showcase/build/`; published images are written under
-`docs/assets/examples/`.
-
-The generator accepts every registered language and every built-in theme
-variant. Its default publication set is the five languages shown above across
-Alto Dark, Alto Light, GitHub Dark, and GitHub Light.
-
-## Example contract
-
-Every canonical source file:
-
-- stays within an 8-13 visible-line budget;
-- uses the language's exact public identifier in the catalog;
-- contains representative, deterministic source;
-- reconstructs exactly after highlighting;
-- fits in the fixed-size preview without wrapping or clipping.
-
-The catalog and verification tools reject missing, duplicate, or unknown
-language entries. See [Creating a theme](creating-a-theme.md) to use these
-samples when reviewing a custom theme.
+The previews use the same source samples as the package tests. See
+[Creating a theme](theming/creating.md) to use them when reviewing a custom
+theme.