feat: add MkDocs Material site and publish docs + CI reports to GitHub Pages

.classpath

@@ -3,20 +3,20 @@
 	<classpathentry kind="src" output="bin/main" path="src/main/java">
 		<attributes>
 			<attribute name="gradle_scope" value="main"/>
-			<attribute name="gradle_used_by_scope" value="main,test"/>
+			<attribute name="gradle_used_by_scope" value="main,test,jmh"/>
 		</attributes>
 	</classpathentry>
 	<classpathentry kind="src" output="bin/test" path="src/test/java">
 		<attributes>
 			<attribute name="gradle_scope" value="test"/>
-			<attribute name="gradle_used_by_scope" value="test"/>
+			<attribute name="gradle_used_by_scope" value="test,jmh"/>
 			<attribute name="test" value="true"/>
 		</attributes>
 	</classpathentry>
 	<classpathentry kind="src" output="bin/main" path="src/main/resources">
 		<attributes>
 			<attribute name="gradle_scope" value="main"/>
-			<attribute name="gradle_used_by_scope" value="main,test"/>
+			<attribute name="gradle_used_by_scope" value="main,test,jmh"/>
 		</attributes>
 	</classpathentry>
 	<classpathentry kind="src" output="bin/jmh" path="src/jmh/java">
@@ -36,7 +36,7 @@
 	<classpathentry kind="src" output="bin/test" path="src/test/resources">
 		<attributes>
 			<attribute name="gradle_scope" value="test"/>
-			<attribute name="gradle_used_by_scope" value="test"/>
+			<attribute name="gradle_used_by_scope" value="test,jmh"/>
 			<attribute name="test" value="true"/>
 		</attributes>
 	</classpathentry>

.github/workflows/pages.yml

@@ -5,6 +5,8 @@ on:
     branches:
       - main
     paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
       - 'src/main/**'
       - 'src/test/**'
       - 'src/jmh/**'
@@ -50,6 +52,14 @@ jobs:
       - name: Set up Gradle caching and instrumentation
         uses: gradle/actions/setup-gradle@v4
 
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install MkDocs Material
+        run: python -m pip install --upgrade pip mkdocs-material
+
       - name: Verify reproducibility inputs
         shell: bash
         run: |
@@ -111,12 +121,17 @@ jobs:
           JMH_CSV_LINK=''
           JMH_TXT_LATEST_LINK=''
           JMH_CSV_LATEST_LINK=''
+          JMH_TXT_REPORT_MD='- Benchmark results (TXT): not currently available'
+          JMH_CSV_REPORT_MD='- Benchmark results (CSV): not currently available'
           DEPENDENCY_CHECK_LINK=''
           DEPENDENCY_CHECK_LATEST_LINK=''
+          DEPENDENCY_CHECK_REPORT_MD='- Dependency vulnerability report: not currently available'
           SBOM_JSON_LINK=''
           SBOM_XML_LINK=''
           SBOM_JSON_LATEST_LINK=''
           SBOM_XML_LATEST_LINK=''
+          SBOM_JSON_REPORT_MD='- SBOM (JSON): not currently available'
+          SBOM_XML_REPORT_MD='- SBOM (XML): not currently available'
 
           if [ -d "build/reports/jmh" ]; then
             cp -R build/reports/jmh "${RUN_DIR}/jmh"
@@ -125,10 +140,12 @@ jobs:
             if [ -f "${RUN_DIR}/jmh/jmh-results.txt" ]; then
               JMH_TXT_LINK='<li><a href="./jmh/jmh-results.txt">Benchmark Results (TXT)</a></li>'
               JMH_TXT_LATEST_LINK='<li><a href="./builds/latest/jmh/jmh-results.txt">Benchmark Results (TXT)</a></li>'
+              JMH_TXT_REPORT_MD='- [JMH benchmark results (TXT)](../builds/latest/jmh/jmh-results.txt)'
             fi
             if [ -f "${RUN_DIR}/jmh/jmh-results.csv" ]; then
               JMH_CSV_LINK='<li><a href="./jmh/jmh-results.csv">Benchmark Results (CSV)</a></li>'
               JMH_CSV_LATEST_LINK='<li><a href="./builds/latest/jmh/jmh-results.csv">Benchmark Results (CSV)</a></li>'
+              JMH_CSV_REPORT_MD='- [JMH benchmark results (CSV)](../builds/latest/jmh/jmh-results.csv)'
             fi
 
             HAS_JMH="true"
@@ -143,6 +160,7 @@ jobs:
             if [ -f "${RUN_DIR}/dependency-check/dependency-check-report.html" ]; then
               DEPENDENCY_CHECK_LINK='<li><a href="./dependency-check/dependency-check-report.html">Dependency Vulnerability Report</a></li>'
               DEPENDENCY_CHECK_LATEST_LINK='<li><a href="./builds/latest/dependency-check/dependency-check-report.html">Dependency Vulnerability Report</a></li>'
+              DEPENDENCY_CHECK_REPORT_MD='- [Dependency vulnerability report](../builds/latest/dependency-check/dependency-check-report.html)'
             fi
           fi
 
@@ -153,6 +171,8 @@ jobs:
             SBOM_XML_LINK='<li><a href="./sbom/radixor-sbom.xml">SBOM (XML)</a></li>'
             SBOM_JSON_LATEST_LINK='<li><a href="./builds/latest/sbom/radixor-sbom.json">SBOM (JSON)</a></li>'
             SBOM_XML_LATEST_LINK='<li><a href="./builds/latest/sbom/radixor-sbom.xml">SBOM (XML)</a></li>'
+            SBOM_JSON_REPORT_MD='- [SBOM (JSON)](../builds/latest/sbom/radixor-sbom.json)'
+            SBOM_XML_REPORT_MD='- [SBOM (XML)](../builds/latest/sbom/radixor-sbom.xml)'
           fi
 
           python3 \
@@ -169,10 +189,22 @@ jobs:
           MUTATION_BADGE_LATEST_LINK='<li><a href="./builds/latest/metrics/pitest-badge.json">Mutation Badge Metadata</a></li>'
           JMH_BADGE_LINK='<li><a href="./metrics/jmh-badge.json">Benchmark Badge Metadata</a></li>'
           JMH_BADGE_LATEST_LINK='<li><a href="./builds/latest/metrics/jmh-badge.json">Benchmark Badge Metadata</a></li>'
+          COVERAGE_BADGE_REPORT_MD='- [Coverage badge metadata](../builds/latest/metrics/coverage-badge.json)'
+          MUTATION_BADGE_REPORT_MD='- [Mutation badge metadata](../builds/latest/metrics/pitest-badge.json)'
+          JMH_BADGE_REPORT_MD='- [Benchmark badge metadata](../builds/latest/metrics/jmh-badge.json)'
 
           if [ ! -f "${RUN_METRICS_DIR}/coverage-badge.json" ]; then
             COVERAGE_BADGE_LINK='<li>Coverage Badge Metadata: not available</li>'
             COVERAGE_BADGE_LATEST_LINK='<li>Coverage Badge Metadata: not available</li>'
+            COVERAGE_BADGE_REPORT_MD='- Coverage badge metadata: not currently available'
+          fi
+
+          if [ ! -f "${RUN_METRICS_DIR}/pitest-badge.json" ]; then
+            MUTATION_BADGE_REPORT_MD='- Mutation badge metadata: not currently available'
+          fi
+
+          if [ ! -f "${RUN_METRICS_DIR}/jmh-badge.json" ]; then
+            JMH_BADGE_REPORT_MD='- Benchmark badge metadata: not currently available'
           fi
 
           cat > "${RUN_DIR}/index.html" <<EOF
@@ -221,65 +253,43 @@ jobs:
           cat > "${SITE_DIR}/.nojekyll" <<EOF
           EOF
 
-          BUILD_LIST=$(find "${SITE_DIR}/builds" -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | grep -E '^[0-9]+$' | sort -nr | head -20)
+          cat > docs/reports.md <<EOF
+          # CI Reports
 
-          {
+          Radixor publishes durable CI artifacts to GitHub Pages on every qualifying run of \`.github/workflows/pages.yml\`.
-            cat <<EOF
-          <!doctype html>
-          <html lang="en">
-          <head>
-            <meta charset="utf-8">
-            <meta name="viewport" content="width=device-width, initial-scale=1">
-            <title>Radixor Reports</title>
-            <style>
-              body { font-family: Arial, sans-serif; max-width: 1000px; margin: 2rem auto; padding: 0 1rem; line-height: 1.5; }
-              h1, h2 { margin-bottom: 0.5rem; }
-              ul { padding-left: 1.25rem; }
-              code { background: #f4f4f4; padding: 0.1rem 0.3rem; }
-              .meta { color: #555; }
-            </style>
-          </head>
-          <body>
-            <h1>Radixor Published Reports</h1>
-            <p class="meta">Durable CI reports published from GitHub Actions to the <code>gh-pages</code> branch.</p>
 
-            <h2>Latest</h2>
+          ## Primary report entry points
-            <ul>
+
-              <li><a href="./builds/latest/">Latest build summary</a></li>
+          - [Latest build summary](../builds/latest/)
-              <li><a href="./builds/latest/javadoc/">Javadoc</a></li>
+          - [Javadoc](../builds/latest/javadoc/)
-              <li><a href="./builds/latest/test/">Test Report</a></li>
+          - [Unit test report](../builds/latest/test/)
-              <li><a href="./builds/latest/pmd/main.html">PMD Report</a></li>
+          - [PMD report](../builds/latest/pmd/main.html)
-              <li><a href="./builds/latest/coverage/">Coverage Report</a></li>
+          - [JaCoCo coverage report](../builds/latest/coverage/)
-              ${DEPENDENCY_CHECK_LATEST_LINK:-<li>Dependency Vulnerability Report: not currently available</li>}
+          - [PIT mutation testing report](../builds/latest/pitest/)
-              ${SBOM_JSON_LATEST_LINK:-<li>SBOM (JSON): not available</li>}
+          ${DEPENDENCY_CHECK_REPORT_MD}
-              ${SBOM_XML_LATEST_LINK:-<li>SBOM (XML): not available</li>}
+          ${SBOM_JSON_REPORT_MD}
-              ${COVERAGE_BADGE_LATEST_LINK}
+          ${SBOM_XML_REPORT_MD}
-              ${MUTATION_BADGE_LATEST_LINK}
+
-              ${JMH_BADGE_LATEST_LINK}
+          ## Benchmark and badge metadata
-              <li><a href="./builds/latest/pitest/">Mutation Testing Report</a></li>
+
-              $(
+          ${JMH_TXT_REPORT_MD}
-                [ "${HAS_JMH}" = "true" ] && { echo "${JMH_TXT_LATEST_LINK:-<li>Benchmark Results (TXT): not available</li>}"; echo "${JMH_CSV_LATEST_LINK:-<li>Benchmark Results (CSV): not available</li>}"; } \
+          ${JMH_CSV_REPORT_MD}
-                || echo '<li>Benchmark results: not currently available</li>'
+          ${COVERAGE_BADGE_REPORT_MD}
-              )
+          ${MUTATION_BADGE_REPORT_MD}
+          ${JMH_BADGE_REPORT_MD}
+
+          ## Historical runs
+
+          - [Browse historical build reports](../builds/)
           EOF
 
-            cat <<EOF
+      - name: Build documentation site (MkDocs Material)
-            </ul>
+        shell: bash
-
+        run: |
-            <h2>Recent historical builds</h2>
+          set -euo pipefail
-            <ul>
+          mkdocs build --strict --site-dir .mkdocs-site
-          EOF
+          rsync -a --delete --exclude 'builds/' .mkdocs-site/ .gh-pages/
-
+          rm -rf .mkdocs-site
-            for build in ${BUILD_LIST}; do
-              echo "      <li><a href=\"./builds/${build}/\">Build ${build}</a></li>"
-            done
-
-            cat <<EOF
-            </ul>
-          </body>
-          </html>
-          EOF
-          } > "${SITE_DIR}/index.html"
 
       - name: Commit and push gh-pages
         shell: bash

docs/architecture-and-reduction.md

@@ -1,7 +1,5 @@
 # Architecture and Reduction
 
-> ← Back to [README.md](../README.md)
-
 This document describes the internal architecture of **Radixor** and the principles behind its **trie compilation and reduction model**.
 
 It explains:

docs/benchmarking.md

@@ -1,7 +1,5 @@
 # Benchmarking
 
-> ← Back to [README.md](../README.md)
-
 Radixor includes a JMH benchmark suite for both the internal algorithmic core and a side-by-side English comparison against the Snowball Porter stemmer family.
 
 This document explains what is benchmarked, how to run it, and how to interpret the results responsibly.

docs/built-in-languages.md

@@ -1,7 +1,5 @@
 # Built-in Languages
 
-> ← Back to [README.md](../README.md)
-
 Radixor provides a set of **bundled stemmer dictionaries** that can be loaded directly without preparing custom data.
 
 These built-in resources are useful for:

docs/cli-compilation.md

@@ -1,7 +1,5 @@
 # CLI Compilation
 
-> ← Back to [README.md](../README.md)
-
 Radixor provides a command-line tool for compiling dictionary files into compact, production-ready binary stemmer tables.
 
 This is the recommended workflow for deployment environments, as it separates:

docs/dictionary-format.md

@@ -1,7 +1,5 @@
 # Dictionary Format
 
-> ← Back to [README.md](../README.md)
-
 Radixor uses a simple, line-oriented dictionary format to define mappings between **word forms** and their **canonical stems**.
 
 This format is intentionally minimal, language-agnostic, and easy to generate from existing linguistic resources or corpora.

docs/index.md

@@ -0,0 +1,20 @@
+# Radixor
+
+**Radixor** is a high-performance, multi-language stemmer for Java, designed for production-grade search and text-processing systems.
+
+It modernizes the proven Egothor patch-command trie approach and delivers:
+
+- **Fast runtime stemming** with compact lookup structures
+- **Multi-language adaptability** through dictionary-driven compilation
+- **Deterministic behavior** suitable for reproducible processing pipelines
+- **Flexible integration paths**, including CLI-based and programmatic workflows
+- **Operational transparency** via continuously published quality and benchmark reports
+
+Radixor is built for teams that need consistent stemming quality at scale without sacrificing maintainability or deployment efficiency.
+
+## Start here
+
+- Read [Quick Start](quick-start.md) for immediate implementation guidance.
+- Use [Programmatic Usage](programmatic-usage.md) for application integration patterns.
+- Review [Benchmarking](benchmarking.md) for reproducible performance methodology.
+- Open [CI Reports](reports.md) to inspect published build artifacts and quality metrics.

docs/programmatic-usage.md

@@ -1,7 +1,5 @@
 # Programmatic Usage
 
-> ← Back to [README.md](../README.md)
-
 This document describes how to use **Radixor** programmatically from Java.
 
 It covers:

docs/quality-and-operations.md

@@ -1,7 +1,5 @@
 # Quality and Operations
 
-> ← Back to [README.md](../README.md)
-
 This document describes quality, testing, and operational practices for **Radixor**.
 
 It focuses on:

docs/quick-start.md

@@ -1,7 +1,5 @@
 # Quick Start
 
-> ← Back to [README.md](../README.md)
-
 This guide shows the fastest way to start using **Radixor** and the most common next steps.
 
 ## Hello world

docs/reports.md

@@ -0,0 +1,27 @@
+# CI Reports
+
+Radixor publishes durable CI artifacts to GitHub Pages on every qualifying run of `.github/workflows/pages.yml`.
+
+## Primary report entry points
+
+- [Latest build summary](../builds/latest/)
+- [Javadoc](../builds/latest/javadoc/)
+- [Unit test report](../builds/latest/test/)
+- [PMD report](../builds/latest/pmd/main.html)
+- [JaCoCo coverage report](../builds/latest/coverage/)
+- [PIT mutation testing report](../builds/latest/pitest/)
+- [Dependency vulnerability report](../builds/latest/dependency-check/dependency-check-report.html)
+- [SBOM (JSON)](../builds/latest/sbom/radixor-sbom.json)
+- [SBOM (XML)](../builds/latest/sbom/radixor-sbom.xml)
+
+## Benchmark and badge metadata
+
+- [JMH benchmark results (TXT)](../builds/latest/jmh/jmh-results.txt)
+- [JMH benchmark results (CSV)](../builds/latest/jmh/jmh-results.csv)
+- [Coverage badge metadata](../builds/latest/metrics/coverage-badge.json)
+- [Mutation badge metadata](../builds/latest/metrics/pitest-badge.json)
+- [Benchmark badge metadata](../builds/latest/metrics/jmh-badge.json)
+
+## Historical runs
+
+- [Browse historical build reports](../builds/)

mkdocs.yml

@@ -0,0 +1,42 @@
+site_name: Radixor
+site_description: High-performance multi-language stemming toolkit for Java
+site_url: https://leogalambos.github.io/Radixor/
+repo_url: https://github.com/leogalambos/Radixor
+repo_name: leogalambos/Radixor
+copyright: "&copy; ${year} Egothor. Licensed under <a href='https://github.com/leogalambos/Radixor/blob/main/LICENSE'>BSD-3-Clause</a>."
+
+theme:
+  name: material
+  language: en
+  features:
+    - navigation.instant
+    - navigation.sections
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: indigo
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - md_in_html
+  - pymdownx.details
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - tables
+
+nav:
+  - Home: index.md
+  - Quick Start: quick-start.md
+  - Dictionary Format: dictionary-format.md
+  - CLI Compilation: cli-compilation.md
+  - Programmatic Usage: programmatic-usage.md
+  - Built-in Languages: built-in-languages.md
+  - Architecture and Reduction: architecture-and-reduction.md
+  - Quality and Operations: quality-and-operations.md
+  - Benchmarking: benchmarking.md
+  - CI Reports: reports.md