lightbend/paradox
54.3
Adequate · 6 November 2026
5.8k
lines of production code
Scala
with Java
4
measurements over time
What this system is
Paradox is a Scala-based documentation engine and SBT plugin designed to generate static documentation sites from Markdown sources. It provides comprehensive features for content structuring, including navigation groups, breadcrumbs, and version management, alongside robust link validation and error reporting. The system supports multiple output formats such as HTML, single-page views, and PDFs, and includes a generic theme with interactive elements like tabbed code snippets and copy-to-clipboard functionality.
How it got here
2015 — Project initialization and core refactoring
8 changes.
The Paradox project was initialized with a new repository structure, migrating the build infrastructure to sbt 1.13 and shifting the organization from Typesafe to Lightbend. The core engine was refactored for Scala 2.13/3 compatibility, introducing new navigation features and source reference capabilities while removing legacy SBT plugin implementations.
2016–2026 — Structured error handling and theme overhaul
9 changes.
This period focused on enhancing the Paradox documentation engine with structured error reporting, link validation, and a comprehensive sbt plugin for configuration. The generic theme was significantly overhauled to support single-page, print, and grouped navigation modes, featuring tabbed code snippets and version warnings. Compatibility layers were also added to support both sbt 0.13 and Scala 3 environments.
Features
Introduce Paradox sbt plugin with comprehensive documentation generation settings
The Paradox sbt plugin is now available, providing a full suite of keys and settings for building documentation sites. Users can configure navigation depth, auto-expanding menus, and leading breadcrumbs, while also enabling link validation with configurable retry counts and ignore paths. The plugin supports generating single-page HTML and PDF outputs, allows custom directive injection, and automatically populates project metadata (such as URL, version, and license) into the documentation properties. It also integrates with the generic theme by default and supports overlay directories for custom templates.
plugin/src/main/scala/com/lightbend · high confidence
Introduce ParadoxThemePlugin for managing theme assets
A new SBT plugin, ParadoxThemePlugin, has been added to handle common settings for themes. It integrates with SBT Web to automatically bundle referenced WebJar assets into the theme output. Users can control this behavior via the \includeMinimalWebjars\ setting, which defaults to true, ensuring that assets referenced in string template files (\.st\) are correctly mapped and exported.
theme-plugin · high confidence
Introduce structured error reporting and link validation
Paradox now provides structured error handling via the new ErrorContext and ErrorCollector classes, which collect errors with file and line-number context and log them with source snippets when processing fails. Additionally, a new LinkCapturer component captures all links during a validation pass, enabling the tool to detect and report broken internal links and missing anchors before generating the final site.
repository · high confidence
New generic theme with tabbed code snippets, group switching, and version warnings
The generic theme now includes JavaScript modules that enable tabbed code snippets (switchable via dropdowns or query parameters), a copy-to-clipboard button for code blocks, and a warning banner when the browsed documentation version differs from the current project version. It also adds Magellan-based smooth scrolling for page navigation anchors.
themes/generic/src/main/assets/js · high confidence
Paradox core refactored for Scala 2.13/3 compatibility and new navigation features
The core documentation engine has been restructured to support Scala 2.13 and 3 by introducing version-specific compatibility shims (replacing JavaConverters with CollectionConverters) and migrating the package namespace from com.typesafe.paradox to com.lightbend.paradox. This update introduces new user-facing navigation capabilities, including configurable breadcrumbs, group-based content switching via dropdowns, and enhanced table of contents with auto-expanding sections. It also adds support for single-page output generation, copy-to-clipboard buttons on code snippets, and improved error handling for broken links and anchors.
core/src/main · high confidence
Project initialization and repository setup
The repository has been initialized with the core project structure, including the Apache 2.0 license, a README identifying the project as Paradox (a markdown documentation tool), and release documentation. Configuration files for code formatting (scalafmt 3.11.5 with Scala 3 dialect), dependency updates (Scala Steward), and CI (AppVeyor) have been added. The legacy version.sbt file was removed in favor of sbt-dynver, and the .gitignore was updated to exclude IDE and BSP directories.
(repo-wide) · high confidence
Removals
Removal of legacy Paradox SBT plugin implementation
The file defining the \Paradox\ SBT AutoPlugin and its associated keys (such as \paradox\, \paradoxMarkdownToHtml\, and \paradoxTemplateDirectory\) has been deleted. This change removes the previous implementation of the Paradox site builder plugin from the codebase, indicating a migration to a different structure or version of the plugin.
plugin/src/main/scala/com/typesafe · high confidence
Behavioural changes
Added Scala 3 compatibility layer for the sbt plugin
The plugin now includes a new compatibility module (Compat.scala) specifically for Scala 3, mirroring the existing Scala 2.12 version. This change adapts internal helper methods to handle Scala 3-specific types, such as using \xsbti.HashedVirtualFileRef\ instead of \xsbti.FileConverter\ for mappings and updating license parsing logic, enabling the plugin to function correctly when built with or used in Scala 3 environments.
plugin/src/main/scala-2.12, plugin/src/main/scala-3 · high confidence
Added sbt 0.13 compatibility layer for source file discovery
A new compatibility shim (Compat.scala) has been added to the sbt 0.13-specific plugin source directory to support cross-building. This file provides a \sourcesFor\ method that wraps the sbt 0.13 API for discovering source files in directories, ensuring the plugin functions correctly on older sbt versions.
plugin/src/main/scala-sbt-0.13 · high confidence
Directive source references now support both direct text and external references
The directive system has been refactored to distinguish between direct source text and external source references. The \DirectiveNode\ now uses a \Source\ abstraction (with \Direct\ and \Ref\ subtypes) instead of a plain string for the source field, allowing directives to link to external source definitions rather than just embedding text. Additionally, a new \VerbatimGroupNode\ class supports grouping verbatim blocks with associated CSS classes and source URLs, and directive attributes now support default values for keys. These changes enhance the flexibility of source code snippets and documentation directives.
_akka-stream-alpakka-cassandra\2.11 · high confidence
Generic theme introduces icon-based UI and single-page/print styling
The generic theme now uses a custom icon font for header anchors and includes a copy-to-clipboard button for code snippets, replacing previous text-based links. It also adds dedicated CSS for single-page and print layouts, enabling numbered headings and proper pagination for PDF or single-page exports.
themes/generic/src/main/assets/css · high confidence
Generic theme overhaul with single-page, print, and grouping support
The generic theme templates have been replaced to support new output modes and navigation structures. Users can now generate single-page HTML views and print-ready documents (including a cover page and XSLT-based table of contents) via new \single.st\, \print.st\, \print-cover.st\, and \print-toc.xslt\ assets. The main page layout (\page.st\) and navigation (\navigation.st\, \menu.st\) have been updated to include a new groups-based navigation block, a version number display, and a GitHub source link for documentation pages. Additionally, the theme now integrates JavaScript for handling code snippets, version warnings, and the new groups logic.
themes/generic/src/main/assets · high confidence
Migrate build infrastructure to sbt 1.13 and Lightbend organization
The project build has been upgraded from sbt 0.13 to sbt 1.13, requiring users to update their sbt installation. The organization has shifted from Typesafe to Lightbend, reflected in updated copyright headers and dependency coordinates (e.g., sbt-web moved to com.github.sbt). The build now targets Java 11 and Scala 2.12, replacing the deprecated scalariform formatter with scalafmt and removing Bintray publishing in favor of sbt-ci-release for Sonatype publishing. Additionally, a new project-info configuration file defines metadata for the Paradox documentation site, and a meta-theme plugin project has been added to support the documentation build.
project · high confidence
Test coverage
Add scripted tests for sbt-paradox configuration and features; Added test coverage for Paradox markdown directives and link handling; Removed obsolete test suite for markdown parsing and directives.
Dependencies
Add documentation build examples and scripted tests for Paradox plugin
This change adds example build configuration files (build.gradle, build.sbt, pom.xml) for the \akka-stream-alpakka-cassandra\ dependency to the documentation resources, providing users with ready-to-use setup snippets for Gradle, SBT, and Maven. It also introduces a comprehensive suite of scripted tests for the Paradox plugin, covering features such as custom configurations, custom directives, default theming, documentation overlays, source generation, GitHub link integration, library dependency handling, navigation settings, parameterized external links, snippet handling, template overriding, and PDF generation.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 43 → 54 (+11.5)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 40 → 63 (+23.1)
- Architecture 93 → 92 (-0.6)
- Maturity 27 → 41 (+13.3)
- Readiness 64 → 64 (+0.0)
- Security 80 → 70 (-10.2)
Findings
- No change — the same findings as the prior survey.
Architecture
- Unchanged — 0 containers · 2 contexts · 0 edges
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
lightbend/paradox was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 6 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 1abe48e4762278a8edb3ea2865dda6c7aa847d77 — the exact code this score is about.
- Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.3+preprod-410a2463fa58.