lightbend/paradox

Paradox is an SBT plugin and documentation engine that converts Markdown files into static HTML sites. It provides features for generating navigation, handling code snippets with copy-to-clipboard functionality, and producing single-page or PDF outputs. The system supports custom directives, theme integration via WebJars, and link validation to facilitate comprehensive project documentation.

8 changes.

The Paradox project was initialized with core infrastructure, including sbt build configuration, CI setup, and Apache 2.0 licensing. The codebase underwent significant modernization by migrating to Scala 2.13/3 compatibility, upgrading the build system to sbt 1.12, and removing legacy SBT plugin implementations. Concurrently, documentation features were enhanced with new directive support, navigation improvements, and comprehensive scripted test coverage.

9 changes.

This period focused on the initial release of the Paradox documentation plugin, establishing core SBT integration for converting Markdown to HTML and PDF. It also involved developing the generic theme with advanced UI features like tabbed code snippets, copy-to-clipboard functionality, and responsive navigation. The work included adding comprehensive test coverage for markdown directives and implementing compatibility layers for sbt 0.13 and Scala 3.

The generic theme assets have been restructured to provide a more complete documentation experience. Users now benefit from a dedicated navigation menu (including a hamburger icon for mobile) and a grouped table of contents, improving content discoverability. Code blocks are now interactive, featuring a button to copy their contents directly. Additionally, the theme supports generating single-page and printable versions of the documentation, and includes a visible link to the GitHub source code for each page.

themes/generic/src/main/assets · high confidence

This change introduces the core SBT plugin for generating documentation sites from Markdown files. It adds the \ParadoxKeys\ trait defining all configuration settings (such as navigation depth, theme selection, and link validation) and the \ParadoxPlugin\ object which wires these settings into the build. Key capabilities include converting Markdown to HTML, supporting multiple output formats (single-page HTML and PDF via wkhtmltopdf), integrating with sbt-web for theme assets, and providing tasks to validate internal links and browse the generated site locally.

plugin/src/main/scala/com/lightbend · high confidence

The theme-plugin module now includes the ParadoxThemePlugin, an SBT AutoPlugin that integrates with SbtWeb to handle theme assets. This plugin adds a new setting, includeMinimalWebjars, which, when enabled, automatically detects and bundles WebJar assets referenced in theme string templates (via the $page.base$(lib/...) pattern) into the exported mappings. It also disables autoScalaLibrary and crossPaths for theme projects to ensure they are treated as pure asset bundles rather than Scala libraries.

theme-plugin · high confidence

The generic theme now includes JavaScript modules that enable tabbed code snippets (switchable via tabs or dropdowns), group-based content switching with cookie persistence and URL query parameters, copy-to-clipboard buttons 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

The repository has been initialized with core project files, including an Apache 2.0 license, a README identifying the project as Paradox (a markdown documentation tool), and release documentation. Configuration for the build tool (sbt) and code formatting (scalafmt 3.11.5 with Scala 3 dialect) has been added, along with a \.scala-steward.conf\ for automated dependency updates. CI support for AppVeyor (Windows) has been introduced, and the legacy \version.sbt\ file was removed in favor of dynamic versioning.

(repo-wide) · high confidence

The legacy Paradox SBT plugin implementation located at plugin/src/main/scala/com/typesafe/paradox/sbt/Paradox.scala has been removed. This deletion eliminates the previous SBT auto-plugin configuration, including its specific task keys (such as paradox, paradoxMarkdownToHtml, and paradoxProperties), default settings (like navigation depth and file suffixes), and the direct wiring of the ParadoxProcessor and PageTemplate. Users relying on this specific plugin structure will no longer have access to these legacy build tasks and settings.

plugin/src/main/scala/com/typesafe · high confidence

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

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

The project's build system has been significantly upgraded, moving from sbt 0.13.8 to sbt 1.12.15 and updating the Scala compiler to version 2.12.21. This change includes a rebranding from Typesafe to Lightbend, reflected in updated copyright headers and organization settings. The build now uses sbt-scalafmt instead of the deprecated scalariform for code formatting, and sbt-ci-release for publishing. Additionally, the project now supports JDK 11 and includes a new \project-info.conf\ file to configure metadata for the documentation site, such as issue trackers and release notes.

project · high confidence

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

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

The documentation processor now provides more detailed error messages when processing fails. Instead of just reporting the error text, it now identifies the specific file and line number where the issue occurred, and displays the problematic line of source content with a pointer to the exact column. This makes it significantly easier to locate and fix issues in your documentation source files.

repository · high confidence

The core library has been migrated to support Scala 2.13 and Scala 3 by introducing version-specific compatibility shims for collection conversions, while simultaneously upgrading the documentation engine. This update introduces new capabilities including auto-expanding navigation, breadcrumb paths, and tab-group switching for content organization. Code snippets now feature copy-to-clipboard buttons and source-link icons, and the table of contents supports both ordered and unordered lists with auto-expansion. Additionally, the system now supports single-page output generation and allows for raw verbatim blocks.

core/src/main · high confidence

Added test coverage for Paradox markdown directives and link handling; Expanded scripted test coverage for sbt-paradox features; Removed obsolete test suite for markdown parsing and directives.

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 watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 42.

• Code Health 50
• Architecture 74
• Maturity 47
• Readiness 77
• Security 59
• Accessibility 30

• 300 commits — 294 feature/other, 6 fixes

• project/plugins.sbt — 61 commits
• (root) — 54 commits
• project/build.properties — 47 commits
• project/Dependencies.scala — 42 commits
• core/src — 24 commits
• plugin/src — 24 commits
• .github/workflows — 19 commits
• (repo) — 13 commits
• project/Common.scala — 6 commits
• docs/src — 4 commits
• tests/src — 3 commits
• themes/generic — 3 commits

• fix: Fix default javadoc base for jdk11+ (#394)
• fix: Fix snippet label regex to allow w (#449)
• fix: Fix sonatypeProfileName
• fix: Fix: sbt lists resolvers, not repositories (#577)
• fix: RELEASING: fix link to travis (#468)
• fix: chore: optimized imports and typo fix (#606)
• change: API doc directives: accept digits in package names (#421)
• change: API doc directives: accept full character range in package names (#431)
• change: Add 'project.license' project property
• change: Add 'project.license' project property (#342)
• change: Add missing ')' #466 (#467)
• change: Add samesite=lax to paradox cookies
• change: Add sbt-ci-release (#527)
• change: Allow checking the value of a property in a template (#343)
• change: Allow matching parenthese pairs to occur inside of directive sou… (#386)
• change: Code snippets now contain a button copying the contents (#474)
• change: Create a repository directive (#575)
• change: Cross compile core with Scala 2.13 (#437)
• change: Dependency directive: produce BOM notation, modern Gradle (#462)
• change: Dependency directive: render symbol for Scala binary version (#429)
• …and 280 more

• 0 containers · 2 bounded contexts · 0 dependency edges (baseline)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

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.