scalameta/mdoc
54.8
Adequate · 6 November 2026
9.3k
lines of production code
Scala
primary language
4
measurements over time
What this system is
Features
Add Scastie modifier and worksheet support via service registrations
The mdoc runtime now supports the Scastie modifier and internal worksheet evaluation through new Java service provider interface (SPI) registrations. The \META-INF/services/mdoc.StringModifier\ file registers \mdoc.modifiers.ScastieModifier\, enabling Scastie-specific code execution, while \META-INF/services/mdoc.interfaces.Mdoc\ registers \mdoc.internal.worksheets.Mdoc\ to expose the public API for evaluating worksheets. These changes allow users to run Scastie snippets and interact with worksheets directly within the documentation generation process.
mdoc/src/main/resources · high confidence
Add custom mdoc modifiers for documentation generation
The mdoc-docs module now includes a set of custom string and post modifiers to enhance documentation rendering. This introduces an \EvilplotModifier\ for generating charts from Scala code, a \FileModifier\ to embed external file contents, and an \MdocModifier\ that processes markdown with link hygiene checks. Additionally, \SbtModifier\ and \FooModifier\ are added to support specific documentation tasks, with service provider files registering these components for use.
mdoc-docs · high confidence
Add live-reload server for markdown preview
Introduces a new internal live-reload server (powered by Undertow) that serves markdown previews in the browser and automatically refreshes the page when source files change. The server handles WebSocket connections for reload notifications, serves static assets (CSS, JavaScript), and includes a fallback mechanism to bind to a free port if the preferred port is already in use.
mdoc/src/main/scala/mdoc/internal/livereload · high confidence
Add mdoc:js modifier for Scala.js integration
Users can now use the \mdoc:js\ code fence modifier to compile and run Scala.js code directly within markdown documentation. This feature introduces a new \JsModifier\ that compiles Scala.js sources, links them, and generates the necessary JavaScript output. It supports multiple module kinds (ES Modules, CommonJS, and NoModule) via the \js-module-kind\ site variable, allowing users to configure how the generated scripts are loaded in the browser. The implementation includes specific loader scripts (\mdoc\_esmodule.js\ and \mdoc\_nomodule.js\) to handle dynamic imports or eval-based execution depending on the module type, and provides configuration options for classpaths, optimization levels, and library scripts.
mdoc-js · high confidence
Add release testing and migration utility scripts
Two new shell scripts are added to the bin directory to support release workflows. test-release.sh fetches specific versions of mdoc artifacts (including JVM, JS, and SBT plugin variants) using Coursier to verify release integrity. migrate-tut.sh provides a utility to migrate documentation files by replacing legacy 'tut' code block markers with 'scala mdoc'.
bin · high confidence
Initial Scala 3 support for mdoc
mdoc now supports Scala 3, enabling users to run code blocks and worksheets in Scala 3 projects. This release introduces a new Scala 3 compiler integration (MarkdownCompiler) that uses the standard Dotty driver, a custom class loader (AbstractFileClassLoader) for handling in-memory class files, and specific instrumenters (Instrumenter, FailInstrumenter) to generate Scala 3-compatible code for execution. It also includes compatibility shims (VirtualDirectoryCompat, CollectionEnrichments) to bridge Scala 2 and Scala 3 APIs where necessary.
mdoc/src/main/scala-3 · high confidence
Initial repository configuration and documentation setup
This change establishes the foundational project configuration and documentation for the mdoc repository. It introduces standard repository files including the Apache 2.0 license, contributing guidelines, and agent-specific instructions (AGENTS.md, CLAUDE.md). It also configures the development environment with a Scalafmt configuration (version 3.11.5), a Scala Steward configuration for dependency updates, and JVM options for the build. Additionally, it sets up CI automation via Mergify, defines git attributes for line endings, and updates the README to reflect JDK compatibility requirements (JDK 8 for older versions, JDK 11+ for latest).
(repo-wide) · high confidence
Introduce mdoc language server for live markdown preview and diagnostics
This change adds the \mdoc-lsp\ module, implementing a Language Server Protocol (LSP) server that enables real-time feedback for mdoc markdown files. The server provides live HTML previews of markdown documents directly in the editor, displays compiler errors and warnings as in-line diagnostics, and supports live-reload functionality. It also integrates with the editor's logging system to surface mdoc output and handles configuration via \mdoc.properties\ files found in the workspace.
mdoc-lsp · high confidence
Introduce public API for programmatic mdoc integration
Users can now integrate mdoc into other JVM applications (such as sbt) without risking process termination on errors. The new \mdoc.SbtMain\ entry point throws an exception instead of calling \sys.exit\ when processing fails, allowing the host application to handle the error gracefully. Additionally, \mdoc.MainSettings\ provides a fluent, programmatic API for configuring mdoc's behavior (such as input/output paths, classpaths, and check modes) from within a running JVM, replacing the previous reliance on CLI argument parsing for embedded use cases.
mdoc/src/main/scala/mdoc · high confidence
Introduce public modifier and context APIs for mdoc extensions
The mdoc CLI now exposes a set of new public classes and traits in the \mdoc\ package to support custom code processing. Users can implement \PreModifier\, \PostModifier\, and \StringModifier\ to hook into the markdown processing lifecycle, utilizing new context classes (\OnLoadContext\, \PreModifierContext\, \PostModifierContext\, \PostModifierContext\) that provide access to file paths, settings, and reporters. Additionally, the \Variable\ class is now publicly available to represent captured code variables, and a \Reporter\ trait is exposed for handling warnings and errors.
cli/src/main/scala/mdoc · high confidence
Launch of the mdoc documentation website
The project now includes a dedicated documentation website built with Docusaurus, providing users with a structured hub for installation guides, feature overviews, and API references. The site features Algolia-powered search, a blog section, and community links to Discord and GitHub, ensuring easier access to documentation and support resources.
website · high confidence
New position mapping utilities for source edits
The mdoc internal position module now includes new utilities to map code positions between original and revised source strings. DiffUtils provides unified diff generation, PositionSyntax adds helpers for formatting error messages and converting between mdoc and Scala Meta positions, and TokenEditDistance enables mapping offsets between similar code snippets using token-level diffing. These changes improve how mdoc handles position information when source code is modified.
mdoc/src/main/scala/mdoc/internal/pos · high confidence
New public API for evaluating worksheets and markdown documents
The \mdoc-interfaces\ module now exposes a public Java API for programmatic evaluation of Scala worksheets and Markdown documents. Users can invoke \Mdoc.evaluateWorksheet\ and \Mdoc.evaluateMarkdownDocument\ to receive structured results including diagnostics, statement summaries, and metadata such as imported files, Scalac options, and library dependencies. The API also supports configuration via working directory, classpath, and screen dimensions, enabling richer integration with IDEs and tooling.
mdoc-interfaces · high confidence
Public API for evaluating worksheets and markdown documents
A new public API class \Mdoc\ is introduced in the worksheets module, allowing external consumers to programmatically evaluate Scala worksheets and Markdown documents. This API exposes methods to configure the evaluation environment (working directory, classpath, scalac options, screen dimensions) and provides entry points \evaluateWorksheet\ and \evaluateMarkdownDocument\ that return structured results including diagnostics and evaluated content.
mdoc/src/main/scala/mdoc/internal/worksheets · high confidence
Support for embedding Scastie code snippets in Markdown
Users can now embed interactive Scala code snippets from Scastie directly into their documentation using the \mdoc:scastie\ modifier. This new modifier generates either an inline embedded snippet or a link to an existing Scastie snippet, allowing for live code execution or reference within the generated HTML. The implementation defaults to Scala version 2.12.21 and supports theming.
mdoc/src/main/scala/mdoc/internal/modifiers · high confidence
Removals
Removal of placeholder Main object in scalamd
The placeholder \Main\ object in \scalamd/src/main/scala/scalamd/Scalamd.scala\, which previously printed "Hello!", has been removed. This cleanup eliminates the unused entry point from the library's source code.
scalamd · high confidence
Architecture
Refactored markdown processing engine into modular internal components
The markdown processing logic in \mdoc/src/main/scala/mdoc/internal/markdown\ has been restructured into a set of dedicated classes to improve clarity and maintainability. Key additions include \CodeBuilder\ for efficient string construction, \Gensym\ for generating fresh identifiers that respect user-defined names to avoid collisions, and \Nesting\ for managing code block indentation. The core processing flow is now handled by a \Processor\ class that coordinates parsing, instrumentation, and evaluation, while \MarkdownBuilder\ manages the compilation and classloader execution. Supporting components like \Renderer\ (handling output formatting and crash reporting), \SectionInput\ (wrapping parsed sources), and \VariableRegex\ (for site variable substitution) have been extracted into their own files. This change organizes the internal architecture without altering the external user-facing behavior.
mdoc/src/main/scala/mdoc/internal/markdown · high confidence
Behavioural changes
1 commit (0 fixes) modifying mdoc-js-worker
A change to existing behaviour in mdoc-js-worker — 1 commit, 2 files: “Give the worker's logger a Java superclass”. Also in this area: Isolate Scala.js linker in a separate classloader.
mdoc-js-worker · medium confidence · unverified
Added Java 17+ classloader compatibility support
Users running mdoc on Java 17 or newer will now have correct classpath resolution for worksheets and Scala 3 code. A new internal \CompatClassloader\ utility handles the differences in how Java 9+ and specifically Java 16+ (where the \ucp\ field moved from \AppClassLoader\ to \BuiltinClassLoader\) expose classloader URLs, ensuring that dependency resolution works reliably across these JDK versions.
mdoc/src/main/scala/mdoc/internal · high confidence
Added Scala 2-specific compatibility layer for source code and printing
This change introduces a new compatibility layer in the Scala 2 runtime to support Scala 3 migration. It adds \Compat\ and \Printing\ modules that bridge internal dependencies like \pprint\ and \fansi\ for type and value rendering, and implements \Macros.scala\ to explicitly handle \SourceStatement\ generation using Scala 2 reflection APIs, replacing implicit casts with direct macro invocations.
runtime/src/main/scala-2 · high confidence
Added Scala 2.11 and 2.13 version-specific compatibility layers
This change introduces new source files under the scala-2.11 and scala-2.13 directories to handle compiler and collection API differences between Scala versions. Specifically, it adds \VersionSpecificFilteringReporter\ implementations to adapt to changes in the reporter API (extending \AbstractReporter\ in 2.11 vs \FilteringReporter\ in 2.13), updates \CollectionEnrichments\ to use the correct extension traits (\DecorateAsJava\/\DecorateAsScala\ in 2.11 vs \AsJavaExtensions\/\AsScalaExtensions\ in 2.13), and provides \Compat\ objects to manage compiler-specific behaviors like the \close()\ method on the Global compiler instance.
mdoc/src/main/scala-2.11, mdoc/src/main/scala-2.13 · high confidence
Added Scala 2.12-specific compatibility implementations
This change introduces version-specific source files for the Scala 2.12 build target, ensuring the library compiles and functions correctly on this older Scala version. The new files include \VersionSpecificFilteringReporter\ to handle compiler reporting logic specific to 2.12, \CollectionEnrichments\ to provide Java/Scala collection conversion utilities, and a \Compat\ object in the worksheets module to suppress unused import warnings. These additions support the broader goal of maintaining compatibility across multiple Scala versions.
mdoc/src/main/scala-2.12 · high confidence
Improved array printing and null safety in Scala 3 document rendering
The Scala 3 document rendering logic now prints the actual contents of arrays (e.g., Array(1, 2, 3)) instead of relying on the default toString method, and correctly handles nested arrays. Additionally, the system no longer crashes when encountering null values, displaying 'null' instead, and summary strings are cleaned of excessive whitespace for a more consistent output.
runtime/src/main/scala-3/mdoc/internal/document · high confidence
Improved worksheet exception handling and output capture
The worksheet evaluation engine now treats all exceptions during user-code execution as non-fatal, preventing fatal crashes and ensuring that partially evaluated documents are returned even when errors occur. Additionally, output is now captured via a dedicated PrintStream, and stack traces are trimmed to remove internal mdoc frames for cleaner error reporting.
runtime/src/main/scala/mdoc/internal · high confidence
Introduce Java interfaces for Scala.js worker isolation and configuration
This change adds a new set of Java interfaces and configuration classes in the \mdoc-js-interfaces\ module to support isolating the Scala.js linker in a separate classloader. It introduces \ScalajsWorkerApi\ and \ScalajsWorkerProvider\ to define the contract for worker-based linking, \ScalajsConfig\ to expose build options such as module type (ESModule, CommonJS, or NoModule), optimization, source maps, and import maps, and \ScalajsLogger\ to handle logging and tracing within the isolated environment.
mdoc-js-interfaces · high confidence
Introduce structured CLI settings and code fence modifier system
The CLI now uses a structured \Settings\ class to manage input/output paths, compiler options, and site variables, replacing the previous ad-hoc argument parsing. This change introduces a new \Mod\ and \Modifier\ system for parsing code fence directives (such as \compile-only\, \fail\, \warn\, and \nest\), enabling more robust handling of modifier combinations and errors. Additionally, the \InputFile\ case class standardizes how input and output paths are resolved and paired, ensuring consistent file mapping across the tool.
repository · high confidence
Introduce structured console reporting and file-watching infrastructure
The mdoc tool now uses a new internal reporting system that provides colored, structured output for errors, warnings, and info messages, while also capturing diagnostics in a structured format suitable for programmatic consumption (e.g., by language servers). Additionally, a new file-watching mechanism has been added to support live-reload functionality, allowing mdoc to automatically re-process files when they are created or modified in the watched directories.
mdoc/src/main/scala/mdoc/internal/io · high confidence
Introduces Scala 3 source-code extraction macros
Adds a new Scala 3-specific implementation for source-code metadata extraction. The new \Macros.scala\ file defines a \StatementMacro\ that uses Scala 3 quote macros to capture the source code text of expressions at compile time, replacing the previous implicit cast mechanism and removing the dependency on the pprint library for this specific functionality.
runtime/src/main/scala-3/mdoc/internal/sourcecode · high confidence
Introduction of ParserSettings trait for indented code fence configuration
A new ParserSettings trait has been added to the parser/shared module, defining a configuration interface that includes an allowCodeFenceIndented boolean flag. This change establishes the structural basis for controlling how indented code fences are parsed within the mdoc parser, allowing future implementations to expose this setting to users.
parser/shared · medium confidence
Migrate build to sbt 2.0.8 with Scala 3 support and IDE filtering
The project build has been upgraded from sbt 0.13.16 to sbt 2.0.8, enabling support for Scala 3.3.8 and the upcoming Scala 3.8.4 alongside Scala 2.12 and 2.13. The build structure was refactored to use sbt 2's built-in ProjectMatrix instead of external plugins, introducing an Extensions object that manages cross-platform source directories (JVM, JS, Native) and IDE import filtering. This allows IDEs to selectively import specific Scala versions and platforms via system properties, resolving compatibility issues with multi-version imports. Additionally, the build now includes sbt-buildinfo, sbt-ci-release, sbt-scalajs (1.22.0), and sbt-scala-native (0.5.12) plugins, and updates jsoup to 1.23.2.
project · high confidence
New document model and exception handling structures
The runtime now introduces a new set of core classes in the \mdoc.document\ package to support the document model, including \Binder\ for binding values with type and position information, \RangePosition\ for tracking code locations, and \DocumentException\ for handling errors with section and position context. The legacy \PositionedException\ is deprecated in favor of \DocumentException\. These changes underpin the new public API for evaluating worksheets and support for Scala 3, providing the foundational data structures for document representation and error reporting.
runtime/src/main/scala/mdoc/document · high confidence
Refactor CLI engine to support multiple input/output pairs and dependency-aware compilation
The CLI engine has been restructured to support multiple input/output file or directory pairs, allowing users to map several source locations to corresponding output destinations. The compilation process now respects per-document library dependencies and custom scalac options, ensuring that each markdown file is compiled with the correct classpath and compiler flags. Additionally, the CLI now handles regular (non-markdown) files by copying them to the output directory and provides improved validation for input/output path configurations.
mdoc/src/main/scala/mdoc/internal/cli · high confidence
Refactor CLI internals and upgrade scalameta to v4.16.0
The CLI module has been restructured by moving internal utilities (such as input handling, position logic, and CLI feedback messages) into the \mdoc.internal.cli\ package and introducing new helpers for markdown processing like \GitHubIdGenerator\ and \ReplVariablePrinter\. This change accompanies an upgrade of the scalameta dependency to version 4.16.0, which requires removing usage of deprecated internal scalameta methods and updating imports to maintain compatibility.
cli/src/main/scala/mdoc/internal · high confidence
Refactored Scala 2 code instrumentation and compilation engine
The Scala 2 code instrumentation and compilation logic has been restructured to improve modularity and support for specific markdown modifiers. A new \FailInstrumenter\ class now handles the generation of code for \@fail\ and \@warn\ sections, separating this logic from the main \Instrumenter\. The main \Instrumenter\ now explicitly manages \using\ directives (via \MagicImports\) to support dependency resolution and file imports, and it correctly instruments \@crash\ and \@compile-only\ sections with appropriate document markers. Additionally, the \MarkdownCompiler\ now explicitly enables the empty package (\-Yrangepos\ and \exposeEmptyPackage\) and configures lambda inlining to prevent timeouts, ensuring more robust compilation of instrumented code.
mdoc/src/main/scala-2 · high confidence
Replace external pprint library with built-in Scala 3 type rendering
The Scala 3 runtime no longer depends on the external pprint library for type printing. Instead, it uses a new internal TypePrinter that leverages Scala 3's native quote and reflect APIs to render type strings, simplifying dependencies and relying on the language's default type representation capabilities.
runtime/src/main/scala-3/mdoc/internal/pprint · high confidence
Support for sbt 2.0 and Scala 3 via compatibility layer, plus Docusaurus HTML processing
The sbt plugin now supports sbt 2.0 and Scala 3 by introducing a \MdocPluginCompat\ trait with separate implementations for Scala 2 and Scala 3, ensuring correct classpath and file reference handling across versions. Additionally, a new \Relativize\ utility has been added to process generated HTML sites (used by the Docusaurus integration), fixing relative links and protocol-relative URLs so the static site works correctly when opened locally or served.
mdoc-sbt/src/main · high confidence
Test coverage
1 commit adding/updating tests in mdoc-sbt; 1 commit adding/updating tests in tests/websiteJs; 2 commits adding/updating tests in tests/unit-js; Add sbt-test for Docusaurus v3 site generation; Add scripted tests for mdoc across multiple Scala versions; Added BaseSuite test infrastructure with Scala version filtering; Added CLI test infrastructure for unit testing; Added Scala version compatibility helpers for markdown tests; Added Scala.js test fixtures for npm dependency integration; Added compiler-plugin integration test; Added demo documentation test file; Added markdown test infrastructure; Added scripted test source file; Added test for scalac options deduplication in Scala 3; Added test for scalacOptions with spaces; Added test input file for CLI classpath functionality; Added test suites for worksheet evaluation and markdown processing; Added tests for HTML path relativization in the Docusaurus plugin; Added tests for sbt-mdoc extra arguments; Added unit tests for JavaScript code generation and ES module import remapping; Added unit tests for mdoc modifiers, CLI, and imports.
Dependencies
Updated build dependencies and added scripted tests for mdoc
The build configuration has been updated to use newer versions of key dependencies, including scalameta, metaconfig, and flexmark, alongside a switch to MUnit for testing. Additionally, a suite of new scripted tests has been added to verify mdoc's behavior across different Scala versions (2.12, 2.13, 3.3, and 3.9), including specific tests for Scala.js integration, Docusaurus v3 support, compiler plugin handling, and scalac option parsing.
(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 53 → 55 (+1.8)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 65 → 64 (-1.1)
- Architecture 92 → 91 (-1.2)
- Maturity 44 → 51 (+7.0)
- Readiness 59 → 59 (-0.6)
- Security 56 → 51 (-4.9)
Resolved (8)
- Off-boarding risk: anonymized user #1
- Outdated: co.fs2:fs2-core_2.13
- Outdated: io.get-coursier:interface
- Outdated: io.undertow:undertow-core
- Outdated: org.scala-lang.modules:scala-xml_2.13
- Outdated: org.slf4j:slf4j-api
- Platform-specific method duplication in the main plugin type. Having separate methods for SSH installation based on OS in the primary API surface forces users to check the OS or import both, rather than having a single cross-platform method or a dedicated platform-specific sub-object.
- Redundant type hierarchy for version configuration. DocusaurusVersion appears to be an abstract type or trait with methods, while V1 and V3 are concrete implementations with properties. This creates a confusing API where users might instantiate V1 or V3 directly, but the base DocusaurusVersion also exposes methods. It is unclear if DocusaurusVersion is meant to be used polymorphically or if V1/V3 are the only valid values.
New (2)
- Dependency hygiene PARTLY measured — sbt declarations read, dependency currency not (Maven Central unreachable)
- Off-boarding risk: anonymized user #1
Changes since last survey
- 7 commits — 7 feature/other, 0 fixes
By area
- (repo) — 3 commits
- mdoc-sbt/src — 2 commits
- (root) — 1 commit
- mdoc-js-worker/src — 1 commit
Notable commits
- change: Give the worker's logger a Java superclass
- change: Merge pull request #1156 from tgodzik/update-lts33
- change: Merge pull request #1162 from tgodzik/update-3.10.1
- change: Merge pull request #1163 from Quafadas/js-worker-scala3-linker
- change: Test the Scala 3 worker with the Scala 3 linker
- change: chore: Test On scala 3.3.9
- change: chore: Test mdoc with Scala 3.10.1
Architecture
- Unchanged — 0 containers · 1 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
scalameta/mdoc 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 d35d359b57c76bd1223c4bed540ac36f6cb59bee — 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-60d1b390edf0.