From 7c4fff4baf63051b2c66d21539dfc68fab978853 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Simon=20Andr=C3=A9?= <smn.andre@gmail.com>
Date: Sat, 19 Sep 2026 23:11:17 +0200
Subject: [PATCH] docs: update structure

---
 README.md                                 | 22 +++---
 docs/api/index.md                         | 83 -----------------------
 docs/compatibility.md                     | 37 ++++++++++
 docs/examples.md                          |  4 +-
 docs/getting-started.md                   | 41 ++++++++++-
 docs/index.md                             | 66 ++++++------------
 docs/installation.md                      |  2 +-
 docs/{languages/index.md => languages.md} | 19 +++++-
 docs/{theming/index.md => themes.md}      | 17 +++--
 docs/{theming => themes}/adapters.md      |  2 +-
 docs/{theming => themes}/creating.md      | 13 ++++
 11 files changed, 153 insertions(+), 153 deletions(-)
 delete mode 100644 docs/api/index.md
 create mode 100644 docs/compatibility.md
 rename docs/{languages/index.md => languages.md} (90%)
 rename docs/{theming/index.md => themes.md} (78%)
 rename docs/{theming => themes}/adapters.md (97%)
 rename docs/{theming => themes}/creating.md (92%)

diff --git a/README.md b/README.md
index e7ac360..6d72fd7 100644
--- a/README.md
+++ b/README.md
@@ -90,15 +90,15 @@ embedded languages, without requiring a theme or choosing an output format.
 
 | Guide | Contents |
 |---|---|
-| [Documentation index](docs/index.md) | Choose the right guide |
+| [Installation](docs/installation.md) | Requirements, Composer, and verification |
 | [Getting started](docs/getting-started.md) | Complete rendering, line numbers, and errors |
-| [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) | Parsing, rendering, and extension contracts |
-| [Examples](docs/examples.md) | Compact examples and generated previews |
+| [Examples](docs/examples.md) | Rendered language and theme previews |
+| [Languages](docs/languages.md) | Exact identifiers and language capabilities |
+| [Themes](docs/themes.md) | Built-in variants and visual examples |
+| [Compatibility](docs/compatibility.md) | Exceptions and supported public boundaries |
+
+The [documentation index](docs/index.md) lists these pages in site navigation
+order and links their focused guides.
 
 The complete source examples are available in [`examples/languages/`](examples/languages/).
 
@@ -148,9 +148,9 @@ $light = new GitHubTheme(dark: false);
 $dark = new GitHubTheme();
 ```
 
-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).
+Browse the [built-in theme matrix](docs/themes.md), learn how to
+[create a theme](docs/themes/creating.md), or reuse an existing stylesheet
+through a [theme adapter](docs/themes/adapters.md).
 
 ## Integrations
 
diff --git a/docs/api/index.md b/docs/api/index.md
deleted file mode 100644
index 244b72f..0000000
--- a/docs/api/index.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# Public API
-
-Alto Code Highlight follows semantic versioning for the supported entry points
-and extension contracts described here. Patch and minor releases preserve
-their documented signatures and behavior throughout the 1.x series.
-
-## Parsing
-
-`CodeParser` parses source into a `ParsedStream` without rendering it. Its
-supported operations are:
-
-- construction with an optional embedding registry and optional language list;
-- `parse()` for semantically scoped tokens;
-- `registerLanguage()` for adding or replacing a parser;
-- `getEmbeddedRegistry()` for inspecting embedding plans;
-- `setEmbeddingEnabled()` for toggling a configured host and target pair.
-
-`parse()` preserves the source supplied by the caller. Concatenating the token
-text, or calling `ParsedStream::toString()`, returns that source exactly.
-Selecting `php` parses PHP from the first byte even when the opening tag is
-omitted.
-
-## HTML rendering
-
-`Highlighter` renders the same parsed representation as escaped HTML. Its
-supported operations are:
-
-- construction with a `ThemeInterface`, optional embedding registry, and
-  optional language list;
-- `highlight()` for escaped HTML output;
-- `getTheme()` for the configured theme;
-- `registerLanguage()` for adding or replacing a parser;
-- `getEmbeddedRegistry()` for inspecting embedding plans;
-- `setEmbeddingEnabled()` for toggling a configured host and target pair.
-
-`HighlighterInterface` defines the portable highlighting operation for code
-that depends on an abstraction rather than the concrete facade.
-
-## Theme extension contract
-
-Custom themes implement `ThemeInterface`. The `Scope` enum and its string
-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](../theming/creating.md) and
-[Theme adapters](../theming/adapters.md) for complete examples.
-
-## Language extension contract
-
-Custom parsers implement `LanguageInterface` and return a `ParsedStream` made
-of `ParsedToken` values. `StreamBuilder`, `TokenType`, and `Scope` are supported
-building blocks for those parsers.
-`Languages::getDefaultLanguages()` returns the built-in registry.
-
-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/index.md) and
-[Embedded languages](../languages/embedded.md)
-for usage and behavior.
-
-## Exceptions
-
-`LanguageNotFoundException` reports an unknown language identifier.
-`ParseException` reports source that a semantic parser cannot process. Both are
-part of the supported exception contract.
-
-## Compatibility boundary
-
-The following details are not compatibility contracts:
-
-- concrete lexer, semantic parser, state, and token classes inside a built-in
-  language implementation;
-- exact whitespace inside generated HTML;
-- private methods and undocumented implementation details;
-- test fixtures, documentation tooling, and generated showcase assets.
-
-The generated element structure, documented CSS classes, source escaping,
-language identifiers, semantic scope values, and public signatures are covered
-by semantic versioning. Changes outside that boundary may occur in a minor or
-patch release when documented behavior remains intact.
diff --git a/docs/compatibility.md b/docs/compatibility.md
new file mode 100644
index 0000000..fe1cb78
--- /dev/null
+++ b/docs/compatibility.md
@@ -0,0 +1,37 @@
+# Compatibility
+
+Alto Code Highlight follows semantic versioning for its documented entry
+points and extension contracts. Patch and minor releases preserve their
+signatures and behavior throughout the 1.x series.
+
+## Exceptions
+
+`LanguageNotFoundException` reports an unknown language identifier.
+`ParseException` reports source that a semantic parser cannot process. Both are
+part of the supported exception contract.
+
+Applications may catch those exceptions individually, or catch the package
+exception interface when the same recovery applies to every highlighting
+failure. Keep the original source visible when highlighting is optional.
+
+## Supported boundary
+
+The compatibility promise covers:
+
+- generated element structure and documented CSS classes;
+- source escaping;
+- registered language identifiers;
+- semantic `Scope` values;
+- documented public signatures;
+- the language and theme extension contracts.
+
+The following details are implementation details:
+
+- concrete lexer, parser, state, and token classes inside a built-in language;
+- exact whitespace inside generated HTML;
+- private methods and undocumented types;
+- test fixtures, documentation tooling, and generated showcase assets.
+
+Those details may change in a minor or patch release when documented behavior
+stays compatible. Review the [Languages](languages.md) and
+[Themes](themes.md) pages for the public extension contracts.
diff --git a/docs/examples.md b/docs/examples.md
index dfaa9f9..ad38324 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -6,7 +6,7 @@ parser checks.
 
 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).
+or use the individual links in the [language reference](languages.md).
 
 ## Featured preview matrix
 
@@ -64,5 +64,5 @@ API.
 | ![CSS highlighted with GitHub Dark](assets/examples/github-dark/css.png) | ![CSS highlighted with GitHub Light](assets/examples/github-light/css.png) |
 
 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
+[Creating a theme](themes/creating.md) to use them when reviewing a custom
 theme.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 9b8bd1c..5f77ec3 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -2,6 +2,9 @@
 
 This guide renders a complete HTML page with one highlighted PHP example.
 
+Save the script below as `highlight.php` beside `vendor`, then run
+`php highlight.php > highlight.html` and open the result in a browser.
+
 ## Render a code block
 
 ```php
@@ -48,6 +51,37 @@ The highlighter escapes source text before it creates HTML. Insert its return
 value as trusted generated markup; escaping that value again would display the
 `<pre>`, `<code>`, and `<span>` tags as text.
 
+The generated page contains a `<pre class="alto-highlight language-php">`
+block and the bundled Alto stylesheet. Compare its rendered colors with the
+checked-in [PHP previews](examples.md#php).
+
+## Parse without rendering
+
+Use `CodeParser` when another component needs semantic tokens instead of HTML:
+
+```php
+use Alto\Code\Highlight\CodeParser;
+
+$stream = (new CodeParser())->parse(
+    '$total = array_sum($prices);',
+    'php',
+);
+
+foreach ($stream as $token) {
+    echo $token->text.' '.$token->scope->value.PHP_EOL;
+}
+```
+
+`parse()` returns a `ParsedStream` and preserves the source exactly:
+`$stream->toString()` equals the original code. The parser also resolves
+configured embedded languages without requiring a theme or choosing an output
+format.
+
+`CodeParser` accepts an optional embedding registry and language list. It also
+exposes `registerLanguage()`, `getEmbeddedRegistry()`, and
+`setEmbeddingEnabled()` for the same parser configuration used by
+`Highlighter`.
+
 ## Construct a highlighter
 
 The concrete constructor accepts a theme and two optional custom registries:
@@ -83,7 +117,7 @@ interface HighlighterInterface
 ```
 
 - `$code` is the source text.
-- `$language` is an exact [registered identifier](languages/index.md).
+- `$language` is an exact [registered identifier](languages.md).
 - `$lineNumbers` adds a numbered span at the start of every line.
 - `$highlightLines` is a list of 1-indexed line numbers. Highlighted numbers
   receive the `alto-highlighted` class.
@@ -169,7 +203,7 @@ Do not emit it for every code block. The same `Highlighter` instance can render
 multiple blocks with the selected theme.
 
 To switch themes, create the requested theme and a corresponding highlighter
-before rendering the page. See the [built-in theme variants](theming/index.md).
+before rendering the page. See the [built-in theme variants](themes.md).
 
 ## Other public operations
 
@@ -179,4 +213,5 @@ before rendering the page. See the [built-in theme variants](theming/index.md).
 - `getEmbeddedRegistry()` to inspect the active embedding plans;
 - `setEmbeddingEnabled()` to toggle a configured host/target pair.
 
-See [Embedded languages](languages/embedded.md) for the embedding contracts.
+See [Embedded languages](languages/embedded.md) for the embedding contracts
+and [Compatibility](compatibility.md) for supported public boundaries.
diff --git a/docs/index.md b/docs/index.md
index 796b7ad..433649a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,54 +1,32 @@
-# Alto Code Highlight documentation
+# Alto Code Highlight
 
-Alto Code Highlight is a server-side syntax highlighter for PHP 8.4 and later.
-It parses source code in PHP and returns escaped, theme-ready HTML. It does not
-require a browser-side highlighter.
-
-## Documentation
-
-- [Installation](installation.md) covers requirements, Composer, and a smoke
-  test.
-- [Getting started](getting-started.md) goes from source code to a complete HTML
-  page.
-- [Examples](examples.md) presents canonical examples and generated visual
-  previews.
-
-## Languages
-
-- [Languages](languages/index.md) lists every accepted language identifier.
-- [Embedded languages](languages/embedded.md) explains HTML, SVG, Markdown, and
-  Twig delegation.
-
-## Theming
-
-- [Themes](theming/index.md) lists all built-in variants and constructors.
-- [Theme adapters](theming/adapters.md) shows how to reuse local Highlight.js,
-  Prism, or TextMate theme files.
-- [Creating a theme](theming/creating.md) implements `ThemeInterface` from
-  semantic scopes to CSS.
-
-## API
-
-- [Public API](api/index.md) defines the supported entry points, extension
-  contracts, and compatibility boundary.
-
-## Public API at a glance
-
-Use `CodeParser` when you need tokens, and `Highlighter` when you need HTML:
+Alto Code Highlight parses source code and renders escaped, theme-ready HTML
+entirely in PHP. Semantic scopes distinguish language concepts across 27
+built-in languages, including embedded CSS, JavaScript, PHP, and markup.
 
 ```php
-use Alto\Code\Highlight\CodeParser;
 use Alto\Code\Highlight\Highlighter;
 use Alto\Code\Highlight\Theme\AltoTheme;
 
-$tokens = (new CodeParser())->parse('$answer = 42;', 'php');
-
 $highlighter = new Highlighter(new AltoTheme());
 $html = $highlighter->highlight('<?php echo "Hello";', 'php');
-$css = $highlighter->getTheme()->getStylesheet();
 ```
 
-The returned HTML is a `<pre class="alto-highlight">` element containing a
-`<code>` element and semantic `<span>` elements. Source text is HTML-escaped
-during rendering. Add the selected theme's stylesheet once to the page, then
-insert the returned HTML without escaping it again.
+The result is escaped semantic HTML ready for the selected theme stylesheet:
+
+```html
+<pre class="alto-highlight language-php"><code class="language-php"><span class="alto-punctuation">&lt;?php </span><span class="alto-keyword">echo</span> <span class="alto-string">&quot;Hello&quot;</span><span class="alto-punctuation">;</span></code></pre>
+```
+
+The package needs no browser-side highlighter, Node.js process, external
+service, or third-party PHP runtime package. It also adapts Highlight.js,
+Prism, and TextMate themes without handing parsing to those tools.
+
+## Documentation
+
+- [Installation](installation.md)
+- [Getting started](getting-started.md)
+- [Examples](examples.md)
+- [Languages](languages.md)
+- [Themes](themes.md)
+- [Compatibility](compatibility.md)
diff --git a/docs/installation.md b/docs/installation.md
index 7d3313f..3bb8623 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -91,7 +91,7 @@ the script that executes it. A framework bootstrap usually already includes
 
 ### A language is reported as unsupported
 
-Use an exact identifier from the [language reference](languages/index.md). The
+Use an exact identifier from the [language reference](languages.md). The
 highlighter normalizes case and surrounding whitespace, but does not provide
 aliases such as `js`, `ts`, `sh`, `yml`, or `cs`.
 
diff --git a/docs/languages/index.md b/docs/languages.md
similarity index 90%
rename from docs/languages/index.md
rename to docs/languages.md
index 1d8b4bc..fa655ec 100644
--- a/docs/languages/index.md
+++ b/docs/languages.md
@@ -7,6 +7,9 @@ Identifiers are case-insensitive after trimming, but there are no short
 aliases. Use `javascript`, not `js`; `typescript`, not `ts`; `bash`, not `sh`;
 `yaml`, not `yml`; and `csharp`, not `cs`.
 
+Read [Embedded languages](languages/embedded.md) for HTML, SVG, Markdown, and
+Twig delegation.
+
 ## Default registry
 
 | Language | Identifier | Category | Typical extension | Parsing focus | Example |
@@ -40,7 +43,7 @@ aliases. Use `javascript`, not `js`; `typescript`, not `ts`; `bash`, not `sh`;
 | YAML | `yaml` | Data | `.yaml` | Mappings, sequences, anchors, aliases, values, and comments | [Source](https://github.com/altophp/code-highlight/blob/main/examples/languages/yaml.yaml) |
 
 The source files above are the canonical compact documentation examples.
-See [Examples](../examples.md) for generated previews.
+See [Examples](examples.md) for generated previews.
 
 ## PHP snippets without an opening tag
 
@@ -91,4 +94,16 @@ $highlighter->registerLanguage(new MyLanguage());
 
 Registering an existing identifier replaces that parser on the highlighter
 instance. Theme authors style the generic semantic scopes emitted by parsers;
-see [Creating a theme](../theming/creating.md).
+see [Creating a theme](themes/creating.md).
+
+## Extension contract
+
+Custom parsers implement `LanguageInterface` and return a `ParsedStream` made
+of `ParsedToken` values. `StreamBuilder`, `TokenType`, and `Scope` are
+supported building blocks. `Languages::getDefaultLanguages()` returns the
+built-in registry.
+
+Embedded parsers use `EmbeddedLanguageCapable`, `EmbeddedLanguageContext`, and
+the public types under `Alto\Code\Highlight\Embedded`. Their documented
+constructors and methods follow the same compatibility promise described in
+[Compatibility](compatibility.md).
diff --git a/docs/theming/index.md b/docs/themes.md
similarity index 78%
rename from docs/theming/index.md
rename to docs/themes.md
index 4c45d1b..5a6e2cf 100644
--- a/docs/theming/index.md
+++ b/docs/themes.md
@@ -4,6 +4,11 @@ Alto Code Highlight includes seven theme families and twelve selectable
 variants. A theme maps semantic scopes to CSS classes and provides the
 stylesheet for those classes.
 
+Continue with:
+
+- [Adapters](themes/adapters.md) for local Highlight.js, Prism, or TextMate themes.
+- [Creating](themes/creating.md) to implement a theme from semantic scopes.
+
 ## Built-in variants
 
 | Family | Variant | Mode | Constructor |
@@ -61,25 +66,25 @@ The same PHP example rendered with the four primary documentation variants:
 
 | Alto Dark | Alto Light |
 |---|---|
-| ![PHP highlighted with Alto Dark](../assets/examples/alto-dark/php.png) | ![PHP highlighted with Alto Light](../assets/examples/alto-light/php.png) |
+| ![PHP highlighted with Alto Dark](assets/examples/alto-dark/php.png) | ![PHP highlighted with Alto Light](assets/examples/alto-light/php.png) |
 
 | GitHub Dark | GitHub Light |
 |---|---|
-| ![PHP highlighted with GitHub Dark](../assets/examples/github-dark/php.png) | ![PHP highlighted with GitHub Light](../assets/examples/github-light/php.png) |
+| ![PHP highlighted with GitHub Dark](assets/examples/github-dark/php.png) | ![PHP highlighted with GitHub Light](assets/examples/github-light/php.png) |
 
 The full PHP, Twig, HTML, JavaScript, and CSS matrix is available in
-[Examples](../examples.md).
+[Examples](examples.md).
 
 ## Line numbers and selected lines
 
 The highlighter emits structural `alto-line-number` and `alto-highlighted`
 classes when those options are enabled. Built-in theme stylesheets do not
 define their layout. Add application CSS for those classes as shown in
-[Getting started](../getting-started.md#line-numbers-and-selected-lines).
+[Getting started](getting-started.md#line-numbers-and-selected-lines).
 
 ## Other theme sources
 
-- Use [theme adapters](adapters.md) for local Highlight.js, Prism, or
+- Use [theme adapters](themes/adapters.md) for local Highlight.js, Prism, or
   TextMate theme files.
-- Follow [Creating a theme](creating.md) to implement
+- Follow [Creating a theme](themes/creating.md) to implement
   `ThemeInterface` directly.
diff --git a/docs/theming/adapters.md b/docs/themes/adapters.md
similarity index 97%
rename from docs/theming/adapters.md
rename to docs/themes/adapters.md
index 6c377e1..573070d 100644
--- a/docs/theming/adapters.md
+++ b/docs/themes/adapters.md
@@ -112,5 +112,5 @@ Adapters translate style classes only:
 - source escaping and output structure remain Alto's responsibility;
 - line numbers still use `alto-line-number` and `alto-highlighted`.
 
-See [Languages](../languages/index.md), [Getting started](../getting-started.md),
+See [Languages](../languages.md), [Getting started](../getting-started.md),
 and [Creating a theme](creating.md) for those separate contracts.
diff --git a/docs/theming/creating.md b/docs/themes/creating.md
similarity index 92%
rename from docs/theming/creating.md
rename to docs/themes/creating.md
index 5dee5e0..e623929 100644
--- a/docs/theming/creating.md
+++ b/docs/themes/creating.md
@@ -215,3 +215,16 @@ Also review the theme in a browser:
 
 The canonical samples in [Examples](../examples.md) provide stable inputs for
 visual review.
+
+## Extension contract
+
+Custom themes implement `ThemeInterface`. The `Scope` enum and its string
+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.
+
+The interface requires `getName()`, `isDark()`, `getCssClasses()`, and
+`getStylesheet()`. Every current `Scope` needs a class mapping; the stylesheet
+then defines those classes for the generated HTML.
+
+See [Compatibility](../compatibility.md) for the semantic-versioning boundary.