docs: add initial documentation for v1.1.0

Five KB articles covering getting started, settings reference, per-block
controls, client-side vs server-side highlighting, and developer reference.

Author: ajaydsouza

AGENTS.md

@@ -3,6 +3,7 @@
 **WebberZone Code Block Highlighting** v1.1.0. WordPress plugin extending the native Gutenberg `core/code` block with syntax highlighting via JS block filters and a `render_block_core/code` PHP filter. Does not replace the block — existing posts stay valid. Namespace: `WebberZone\Code_Block_Highlighting`. Requires WordPress 6.6+, PHP 7.4+. No Freemius.
 
 Two highlighting modes:
+
 - **Client-side** (default): Prism.js runs in the browser. Loads the Prism JS bundle + theme CSS.
 - **Server-side**: highlight.php pre-renders token spans on the server. No JS loaded. Uses the same Prism theme CSS — token class remapping (`remap_token_classes()` in `class-blocks.php`) converts hljs-* span classes to Prism `token *` classes via `strtr`, giving exact visual parity across all 21 themes.
 
@@ -31,6 +32,7 @@ npm run zip            # Plugin zip
 Bootstrap: `wzcbh()` singleton on `plugins_loaded` → instantiates `Frontend\Blocks`, `Frontend\Styles_Handler` → `Admin\Admin` on `init` (admin only).
 
 Key files:
+
 - `includes/class-main.php` — bootstrap and object wiring
 - `includes/frontend/class-blocks.php` — editor assets, REST route, `render_block_core/code` filter; `render_code_block_server()` for server mode; `remap_token_classes()` for hljs→Prism class mapping
 - `includes/frontend/class-styles-handler.php` — conditional asset loading for both modes: client (Prism JS + theme CSS) and server (theme CSS + `hljs-server-mode.css`, no JS)
@@ -48,22 +50,6 @@ Always `require` the generated `.asset.php` manifest before enqueueing block scr
 
 **`wzcbh_languages` filter** — controls the editor UI dropdown only. Does not affect which Prism grammars are bundled. Adding a slug without a matching grammar import in `frontend.js` results in plain-text output.
 
-**Editor canvas styling** — `enqueue_editor_canvas_styles()` extracts only `background` and `color` from the active Prism theme CSS and re-injects them with `.block-editor-block-list__layout` prepended to win the specificity race against the editor's own `pre` styles. Layout properties are intentionally excluded.
-
-**Themes (21):** A11y Dark, Coldark Cold, Coldark Dark, Dracula, Duotone Dark, Duotone Light, GitHub Light, Gruvbox Dark, Gruvbox Light, Lucario, Material Dark, Material Light, Night Owl, Nord, One Dark, One Light, Shades of Purple, Solarized Dark, Synthwave '84, VS Code Dark+, Xonokai (Monokai).
-
-**Default color scheme:** `prism-onedark`
-
-**If you change block attributes in JS**, update `render_code_block()` in `class-blocks.php` and the defaults flow as well.
-
-## Non-obvious implementation details
-
-**`_legacyTitle` attribute** — read-only migration attribute; copies `title` from old `code-syntax-block` format on first load, then clears itself.
-
-**`maxHeight`** — CSS-only: serialized as inline `style` by the block save function, not touched by the PHP render filter.
-
-**`wzcbh_languages` filter** — controls the editor UI dropdown only. Does not affect which Prism grammars are bundled. Adding a slug without a matching grammar import in `frontend.js` results in plain-text output.
-
 **Editor canvas styling** — `enqueue_editor_canvas_styles()` extracts only `background` and `color` from the active Prism theme CSS and re-injects them with `.block-editor-block-list__layout` prepended to win the specificity race against the editor's own `pre` styles.
 
 **Server-mode token remapping** — `remap_token_classes()` in `class-blocks.php` uses `strtr()` to convert every `class="hljs-*"` span emitted by highlight.php into the equivalent Prism `class="token *"` span. Keys are ordered longest-first to prevent prefix collisions.

docs/01-wzcbh-getting-started/code-block-highlighting-settings-reference.md

@@ -0,0 +1,48 @@
+---
+slug: code-block-highlighting-settings-reference
+title: "Code Block Highlighting Settings Reference"
+products: [code-block-highlighting]
+sections: [01-wzcbh-getting-started]
+tags: [code-block-highlighting, settings]
+status: publish
+order: 0
+---
+
+[kbtoc]
+
+All [WebberZone Code Block Highlighting](https://webberzone.com/plugins/webberzone-code-block-highlighting/) settings are available at **Settings > Code Block Highlighting**. Settings are stored in a single WordPress option: `wzcbh_settings`.
+
+## Highlighting Mode
+
+Controls whether syntax highlighting runs in the browser or on the server. Setting key: `highlighting-mode`.
+
+- **Client-side (Prism.js)** *(default)* — Prism.js runs in the browser. This mode supports interactive features such as copy-to-clipboard and expand/collapse.
+- **Server-side (highlight.php)** — highlight.php pre-renders syntax token spans on the server before the page is sent to the browser. No JavaScript is loaded for highlighting in this mode.
+
+Both modes use the same 21 Prism themes.
+
+## Color Scheme
+
+Selects the syntax highlighting theme applied to all code blocks. The same Prism theme is used in both client-side and server-side modes. Setting key: `color-scheme`. Default: **One Dark**.
+
+## Copy to Clipboard
+
+When enabled, a **Copy** button appears in the code block toolbar. Visitors can copy the entire code snippet with one click. Setting key: `copy-to-clipboard`. Default: enabled.
+
+This feature is available in client-side mode only. It has no effect when **Highlighting Mode** is set to server-side.
+
+## Show Language Label
+
+When enabled, the programming language name is displayed in the toolbar above each code block. Setting key: `show-language-label`. Default: enabled.
+
+## Show File Name
+
+When enabled, the file name or title is displayed in the toolbar above each code block, provided a title has been set on the block. Setting key: `show-file-name`. Default: enabled.
+
+## Default Language
+
+The language pre-selected when a new code block is inserted in the editor. Leave this field blank to insert new code blocks with no language pre-selected. Setting key: `default-lang`.
+
+## Font Size (px)
+
+Font size in pixels for code blocks. Set to `0` to inherit the font size from the active theme. Setting key: `font-size`.

docs/01-wzcbh-getting-started/getting-started-with-webberzone-code-block-highlighting.md

@@ -0,0 +1,41 @@
+---
+slug: getting-started-with-webberzone-code-block-highlighting
+title: "Getting Started with WebberZone Code Block Highlighting"
+products: [code-block-highlighting]
+sections: [01-wzcbh-getting-started]
+tags: [code-block-highlighting, installation]
+status: publish
+order: 0
+---
+
+WebberZone Code Block Highlighting extends the native WordPress Gutenberg `core/code` block with syntax highlighting, and is available for free on WordPress.org.
+
+## WordPress install (The easy way)
+
+1. Go to **Plugins > Add New**.
+2. Search for **WebberZone Code Block Highlighting**.
+3. Click **Install Now**, then **Activate**.
+
+## Manual install
+
+1. Download the latest release from [WordPress.org](https://wordpress.org/plugins/webberzone-code-block-highlighting/) or from [GitHub Releases](https://github.com/WebberZone/webberzone-code-block-highlighting/releases).
+2. Unzip the archive and upload the `webberzone-code-block-highlighting` folder to `/wp-content/plugins/`.
+3. Go to **Plugins** in your WordPress admin and activate **WebberZone Code Block Highlighting**.
+
+## Installing via WP CLI
+
+```bash
+wp plugin install webberzone-code-block-highlighting --activate
+```
+
+On a Multisite network, use `--activate-network` to network-activate the plugin:
+
+```bash
+wp plugin install webberzone-code-block-highlighting --activate-network
+```
+
+## Using WebberZone Code Block Highlighting
+
+After activation, open the block editor and add a **Code** block (or select an existing one). A **Code Highlighting** panel appears in the Inspector Controls sidebar on the right. Use that panel to choose the language, color scheme, and other display options for that block.
+
+The plugin works as a filter on top of `core/code` — it never replaces the block. If you deactivate the plugin, syntax highlighting is removed but all code blocks remain intact and valid. No content is lost.

docs/02-wzcbh-advanced/client-side-vs-server-side-highlighting.md

@@ -0,0 +1,41 @@
+---
+slug: client-side-vs-server-side-highlighting
+title: "Client-Side vs Server-Side Highlighting"
+products: [code-block-highlighting]
+sections: [02-wzcbh-advanced]
+tags: [code-block-highlighting, server-side, prism, highlight.php]
+status: publish
+order: 0
+---
+
+[WebberZone Code Block Highlighting](https://webberzone.com/plugins/webberzone-code-block-highlighting/) supports two rendering modes: client-side (Prism.js in the browser) and server-side (highlight.php on the server). The mode is set globally and applies to all code blocks on the site.
+
+[kbtoc]
+
+## Client-side mode (default)
+
+<a href="https://prismjs.com/" target="_blank" rel="noopener">Prism.js</a> loads in the visitor's browser and highlights the code on page load. The Prism JS bundle (containing all bundled grammars and plugins) and the active theme CSS are enqueued on pages that contain at least one code block. Interactive toolbar features — copy-to-clipboard, expand/collapse, and the language label — are all available in this mode.
+
+## Server-side mode
+
+<a href="https://github.com/scrivo/highlight.php" target="_blank" rel="noopener">highlight.php</a> runs during WordPress page rendering and pre-bakes the highlighted token spans directly into the HTML. No Prism JS is loaded on the frontend. Only the active Prism theme CSS and a small helper stylesheet (`hljs-server-mode.css`) are enqueued.
+
+This mode is suitable for:
+
+- Sites where JavaScript is disabled or restricted by a content-security policy
+- Performance-focused setups that want fewer frontend scripts
+- AMP-compatible pages
+
+In server-side mode, the copy-to-clipboard and expand/collapse toolbar buttons are not available. The **Highlight Lines** per-block control has no effect.
+
+## Visual output
+
+Both modes load the same 21 Prism themes and produce visually identical output. The plugin remaps the token class names emitted by highlight.php to match Prism's class conventions, so the same theme CSS applies correctly in both modes. You can switch modes at any time from **Settings > Code Block Highlighting** without any visible change to your code blocks.
+
+## Asset loading
+
+In both modes, assets are only enqueued on pages that contain at least one `core/code` block. Pages without code blocks are not affected. Use the `wzcbh_force_load_assets` filter to override this behavior if needed.
+
+## Switching modes
+
+Go to **Settings > Code Block Highlighting** and change **Highlighting Mode** to either **Client-side (Prism.js)** or **Server-side (highlight.php)**. No other configuration is required.

docs/02-wzcbh-advanced/per-block-controls.md

@@ -0,0 +1,39 @@
+---
+slug: per-block-controls
+title: "Per-Block Controls"
+products: [code-block-highlighting]
+sections: [02-wzcbh-advanced]
+tags: [code-block-highlighting, block editor, inspector controls]
+status: publish
+order: 0
+---
+
+Each code block has its own highlighting settings, available in the **Code Highlighting** panel of the Inspector Controls sidebar. These override the global defaults set on the [Code Block Highlighting settings page](https://webberzone.com/plugins/webberzone-code-block-highlighting/).
+
+[kbtoc]
+
+## Language
+
+A dropdown listing 40+ supported languages. Selecting a language applies the correct Prism grammar (or highlight.php language in server-side mode). Choosing **Plain Text** renders the code with the active theme's styling but no syntax highlighting.
+
+The `wzcbh_languages` filter can be used to add or remove entries from the dropdown. Adding a language to the filter only affects the UI dropdown; the corresponding Prism.js grammar must also be available in `frontend.js` for the language to highlight correctly in client-side mode.
+
+## Line Numbers
+
+Toggle to show or hide line numbers on this block. When enabled, a **Start Line** field appears. Set this to any integer to begin numbering from that value — useful when showing a code excerpt that starts partway through a file.
+
+## Title
+
+A text field for an optional filename or label (e.g. `config.yml`). When **Show File Name** is enabled in global settings, the title appears in the toolbar above the block. If **Show File Name** is disabled globally, the title field is still saved but not displayed.
+
+## Highlight Lines
+
+Enter a comma-separated list of line numbers or ranges (e.g. `1,3-5,8`) to visually highlight those lines. This maps to the Prism `data-line` attribute. Available in client-side mode only; has no effect in server-side mode.
+
+## Max Height
+
+Set a maximum visible height in pixels. When the code block content exceeds this height, an **Expand** button appears in the toolbar; clicking it reveals the full block. Set to `0` (the default) to disable this limit. The height limit is applied as inline CSS and is not affected by the highlighting mode.
+
+## Word Wrap
+
+Toggle soft word wrapping for long lines. When disabled (the default), long lines scroll horizontally.