Redesign the documentation experience for v1.9.2

.github/workflows/ci.yml

@@ -19,7 +19,9 @@ jobs:
         os: [ubuntu-24.04, windows-2022]
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
 
       - name: Install Free Pascal on Ubuntu
         if: runner.os == 'Linux'

CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.2] - 2026-08-22
+
+### Documentation Experience
+
+- Redesigned the generated developer documentation with hierarchical navigation, breadcrumbs, on-page outlines, and sequential previous/next links.
+- Added a responsive documentation shell with light/dark themes, accessible mobile navigation, improved typography, and focused Pascal code panels with copy support.
+- Added a version selector, lightweight offline-safe client-side search, readable responsive tables, and GitHub-style NOTE, TIP, IMPORTANT, and WARNING callouts.
+- Moved presentation assets out of the Python builder and strengthened built-site checks for assets, duplicate IDs, unsafe links, local paths, and version targets.
+- Preserved generated offline ZIP/SHA-256 output and the v1.9.1 historical documentation path.
+
+### Compatibility
+
+- No intentional breaking API changes.
+
 ## [1.9.1] - 2026-08-22
 
 ### Documentation

README.md

@@ -8,17 +8,17 @@
 [![Lazarus](https://img.shields.io/badge/Lazarus-4.0+-blue.svg)](https://www.lazarus-ide.org/)
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
 [![CI](https://github.com/ikelaiah/stringkit-fp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ikelaiah/stringkit-fp/actions/workflows/ci.yml)
-[![Version](https://img.shields.io/badge/Version-1.9.1-blueviolet.svg)](https://github.com/ikelaiah/stringkit-fp/releases/tag/v1.9.1)
+[![Version](https://img.shields.io/badge/Version-1.9.2-blueviolet.svg)](https://github.com/ikelaiah/stringkit-fp/releases/tag/v1.9.2)
 
 Practical string handling for Free Pascal and Lazarus: cleaning, identifier case conversion, validation, encoding, regex extraction, approximate matching, and readability helpers. It has no third-party runtime dependencies.
 
 ## Learn StringKit-FP
 
-- [Beginner Guide](docs/start/beginner-guide.md) — installation and the first useful calls.
-- [Recipes](docs/start/recipes.md) — complete, compiled programs with expected output.
-- [Cheat Sheet](docs/start/cheat-sheet.md) — compact API reminder.
-- [API Overview](docs/reference/api-overview.md) — find the right area quickly.
-- [Online documentation](https://ikelaiah.github.io/stringkit-fp/1.9.1/) — browsable, versioned HTML documentation.
+- [Online Documentation](https://ikelaiah.github.io/stringkit-fp/) — browsable, versioned HTML documentation.
+- [Beginner Guide](https://ikelaiah.github.io/stringkit-fp/1.9.2/start/beginner-guide.html) — installation and the first useful calls.
+- [Recipes](https://ikelaiah.github.io/stringkit-fp/1.9.2/start/recipes.html) — complete, compiled programs with expected output.
+- [Cheat Sheet](https://ikelaiah.github.io/stringkit-fp/1.9.2/start/cheat-sheet.html) — compact API reminder.
+- [API Reference](https://ikelaiah.github.io/stringkit-fp/1.9.2/reference/api-overview.html) — find the right area quickly.
 
 The repository [documentation index](docs/index.md) links to all beginner guides, topic guides, contracts, and helper references.
 

ROADMAP.md

@@ -2,6 +2,11 @@
 
 This roadmap describes direction rather than dates. Compatibility and beginner-friendly static APIs remain important release criteria.
 
+## Completed in v1.9.2
+
+- Redesigned the versioned documentation experience with a structured sidebar, responsive reading shell, light/dark themes, search, code-copy controls, and stronger built-site validation.
+- Preserved the beginner-first documentation path, offline archive support, and the v1.9.1 historical release site.
+
 ## Completed in v1.9.1
 
 - Added progressive beginner documentation, executable task recipes, and concise API/contract guides.

docs/guides/encoding.md

@@ -14,6 +14,9 @@ For the input `a b+c`:
 
 `PercentDecode` preserves a literal `+`. `FormURLDecode` and legacy `URLDecode` interpret `+` as a space. Use `PercentEncode` for URI components and `FormURLEncode` for `application/x-www-form-urlencoded` data.
 
+> [!WARNING]
+> `PercentDecode` and `FormURLDecode` do not have identical `+` semantics. Choose the decoder that matches the encoder and transport format.
+
 The [URL encoding recipe](../start/recipes.md#form-url-encoding-and-percent-encoding) is compiled and checks both output lines.
 
 ## Hex and Base64

docs/index.md

@@ -1,6 +1,6 @@
-# StringKit-FP documentation
+# StringKit-FP
 
-StringKit-FP is a lightweight string toolkit for Free Pascal and Lazarus. Start with a small task, then follow the guide that matches what you need to do.
+StringKit-FP is a modern, lightweight string toolkit for Free Pascal and Lazarus. Start with a small task, then follow the guide that matches what you need to do.
 
 ## Getting started
 
@@ -31,4 +31,4 @@ StringKit-FP is a lightweight string toolkit for Free Pascal and Lazarus. Start
 - [Roadmap](../ROADMAP.md)
 - [Contributing](../CONTRIBUTING.md)
 
-The online site is versioned. The top-level site opens the current release; `/1.9.1/` keeps this release’s documentation at a stable path. Future entries in `versions.json` identify their immutable source ref, and the publishing builder regenerates every declared release path.
+The online site is versioned. The top-level site opens the current release; `/1.9.2/` is the current documentation path and `/1.9.1/` remains a stable historical release. The version selector opens a release root when a page is not shared by every version.

docs/layout.json

@@ -1,6 +1,8 @@
 {
-  "schema_version": 1,
-  "release": "1.9.1",
+  "schema_version": 2,
+  "release": "1.9.2",
+  "site_title": "StringKit-FP documentation",
+  "description": "Practical StringKit-FP documentation for Free Pascal and Lazarus.",
   "required_pages": [
     "index.md",
     "start/index.md",
@@ -11,12 +13,56 @@
     "guides/case-conversion.md",
     "guides/validation.md",
     "guides/encoding.md",
-    "guides/fuzzy-matching.md",
     "guides/parsing-and-try-apis.md",
+    "guides/fuzzy-matching.md",
     "guides/text-analysis.md",
     "reference/api-overview.md",
-    "reference/helper-feature-flags.md",
     "reference/contracts-and-limitations.md",
+    "reference/helper-feature-flags.md",
     "reference/helper-coverage.md"
-  ]
+  ],
+  "navigation": [
+    { "title": "Getting Started", "pages": [
+      { "path": "index.md", "title": "Introduction" },
+      { "path": "start/index.md", "title": "Start Here" },
+      { "path": "start/beginner-guide.md", "title": "Beginner Guide" },
+      { "path": "start/recipes.md", "title": "Recipes" },
+      { "path": "start/cheat-sheet.md", "title": "Cheat Sheet" }
+    ] },
+    { "title": "Guides", "pages": [
+      { "path": "guides/static-vs-helper.md", "title": "Static vs Helper" },
+      { "path": "guides/case-conversion.md", "title": "Case Conversion" },
+      { "path": "guides/validation.md", "title": "Validation" },
+      { "path": "guides/encoding.md", "title": "Encoding" },
+      { "path": "guides/parsing-and-try-apis.md", "title": "Parsing & Try APIs" },
+      { "path": "guides/fuzzy-matching.md", "title": "Fuzzy Matching" },
+      { "path": "guides/text-analysis.md", "title": "Text Analysis" }
+    ] },
+    { "title": "Reference", "pages": [
+      { "path": "reference/api-overview.md", "title": "API Overview" },
+      { "path": "reference/contracts-and-limitations.md", "title": "Contracts & Limitations" },
+      { "path": "reference/helper-feature-flags.md", "title": "Helper Feature Flags" },
+      { "path": "reference/helper-coverage.md", "title": "Helper Coverage" }
+    ] }
+  ],
+  "project": [
+    { "title": "GitHub repository", "url": "https://github.com/ikelaiah/stringkit-fp" },
+    { "title": "Changelog", "project_path": "CHANGELOG.md" },
+    { "title": "Roadmap", "project_path": "ROADMAP.md" },
+    { "title": "Contributing", "project_path": "CONTRIBUTING.md" }
+  ],
+  "homepage": {
+    "tagline": "A modern string toolkit for Free Pascal and Lazarus.",
+    "actions": [
+      { "label": "Get Started", "path": "start/beginner-guide.md" },
+      { "label": "Browse Recipes", "path": "start/recipes.md" },
+      { "label": "API Reference", "path": "reference/api-overview.md" }
+    ],
+    "cards": [
+      { "eyebrow": "Get Started", "title": "Beginner Guide", "description": "Learn StringKit-FP from your first call to useful text processing.", "path": "start/beginner-guide.md" },
+      { "eyebrow": "Recipes", "title": "Common Tasks", "description": "Copy tested, working Pascal examples.", "path": "start/recipes.md" },
+      { "eyebrow": "Cheat Sheet", "title": "Quick Lookup", "description": "Find the operation you need quickly.", "path": "start/cheat-sheet.md" },
+      { "eyebrow": "API Reference", "title": "Public API", "description": "Browse StringKit's static and helper interfaces.", "path": "reference/api-overview.md" }
+    ]
+  }
 }

docs/start/beginner-guide.md

@@ -6,6 +6,9 @@
 
 Start with the static API. The optional string helper is a second spelling of most string-first calls, not a different implementation.
 
+> [!TIP]
+> Keep `StringKit` as your first import. Add `StringKitHelper` only when you specifically prefer instance-style calls.
+
 ## 2. Add StringKit-FP to a project
 
 For an FPC project, put `src/` on the unit search path and add `StringKit` to `uses`.
@@ -56,6 +59,9 @@ Use `ToCamelCase`, `ToPascalCase`, `ToSnakeCase`, or `ToKebabCase` when converti
 
 `IsValidEmail`, `IsValidURL`, `IsValidIPv4`, `IsValidIPv6`, and `IsValidDate` are practical syntax checks. They do not prove that an address exists, a URL is reachable, or input meets every RFC edge case. See [Validation](../guides/validation.md).
 
+> [!IMPORTANT]
+> `SubString` follows Pascal's 1-based indexing. Check [Contracts and limitations](../reference/contracts-and-limitations.md) before translating zero-based examples from another language.
+
 ## 9. Encode text for the right context
 
 Use `HTMLEncode` before inserting text into HTML. Use `PercentEncode` for URI components and `FormURLEncode` for HTML form data. `URLEncode` is intentionally a legacy-compatible form alias. The [encoding guide](../guides/encoding.md) explains the difference.

docs/versions.json

@@ -1,9 +1,13 @@
 {
   "schema_version": 1,
-  "current": "1.9.1",
+  "current": "1.9.2",
   "site_url": "https://ikelaiah.github.io/stringkit-fp",
   "repository_url": "https://github.com/ikelaiah/stringkit-fp",
   "versions": [
+    {
+      "release": "1.9.2",
+      "source_ref": "v1.9.2"
+    },
     {
       "release": "1.9.1",
       "source_ref": "v1.9.1"

packages/lazarus/stringkit_fp.lpk

@@ -43,7 +43,7 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE. "/>
-    <Version Major="1" Minor="9" Release="1"/>
+    <Version Major="1" Minor="9" Release="2"/>
     <Files>
       <Item>
         <Filename Value="..\..\src\StringKit.pas"/>