scalameta/mdoc

Mdoc is a Scala documentation tool that executes embedded Scala code within Markdown files to generate static HTML sites. It supports multiple Scala versions (2.11–3) and platforms (JVM, Scala.js, Native), offering features like live-reload, worksheet evaluation, and integration with Docusaurus. The system provides a public API for programmatic use, an sbt plugin for build automation, and a language server for IDE integration.

23 changes.

This period focused on modernizing the mdoc codebase by migrating the build to sbt 2.0 with Scala 3 support and refactoring the internal architecture into modular components. Key developments included introducing a public programmatic API, implementing a live-reload server, and launching the initial mdoc language server infrastructure. The work also encompassed comprehensive testing, documentation website deployment, and tooling improvements for release workflows and dependency management.

18 changes.

This period focused on adding initial Scala 3 support and establishing a public programmatic API for evaluating Markdown documents and worksheets. The work involved implementing version-specific compatibility layers for Scala 2.11, 2.12, and 2.13, alongside significant refactoring of the compilation engine and test infrastructure to ensure stability across multiple Scala and Java versions.

14 changes.

This period focused on expanding mdoc's extensibility by exposing a public API for modifiers and context, while introducing support for embedding interactive Scastie snippets. Significant architectural work involved isolating the Scala.js linker in a separate classloader via new Java interfaces and worker modules to improve stability. The effort was complemented by extensive test infrastructure updates, including CLI and markdown testing utilities, alongside compatibility fixes for Docusaurus v3 and Scala.js 1.20.

The mdoc-docs module now includes several custom mdoc modifiers to enhance documentation capabilities. These include an EvilplotModifier for rendering charts, a FileModifier for embedding file contents, a FooModifier for testing, an MdocModifier for processing markdown with link hygiene checks, and an SbtModifier for displaying SBT task information. Additionally, a Docs.scala entry point has been added to orchestrate the documentation build process, supporting both general docs and blog generation with configurable site variables and output paths.

mdoc-docs · high confidence

Users can now execute Scala.js code directly within markdown documents using the \mdoc:js\ code fence modifier. This feature compiles Scala.js snippets, links them into JavaScript, and injects the output into the generated HTML site. It supports both ES modules and CommonJS/no-module script loading strategies, with the appropriate runtime loader (\mdoc\_esmodule.js\ or \mdoc\_nomodule.js\) automatically included in the output. The implementation includes a dedicated \JsModifier\ class, Scala 2 and Scala 3 compiler compatibility layers, and an isolated classloader for the Scala.js linker to ensure stable execution.

mdoc-js · high confidence

New shell scripts are added to the bin directory to support release workflows and code migration. The test-release.sh script fetches specific mdoc artifacts (including JVM and Scala.js variants for Scala 2.12, 2.13, and 3) via Coursier to verify release integrity. The migrate-tut.sh script provides a utility to migrate legacy 'tut' code block syntax to 'scala mdoc' in Markdown files.

bin · high confidence

mdoc now supports Scala 3, enabling users to run code blocks and worksheets in Scala 3 projects. This release introduces a dedicated Scala 3 implementation layer (in mdoc/src/main/scala-3) that includes a custom class loader for in-memory compilation, a new code instrumentation engine for generating executable scripts from markdown, and a compiler driver based on the standard Dotty driver. While this initial support focuses on basic code evaluation and worksheet functionality, it lays the groundwork for full Scala 3 compatibility in mdoc.

mdoc/src/main/scala-3 · high confidence

This change adds the core infrastructure for the mdoc language server, including the main entry point (LspMain), the server implementation (MdocLanguageServer), and supporting components like diagnostics reporting (DiagnosticsReporter) and logging (LspLogger). It enables the server to initialize, load mdoc.properties configurations, and process markdown documents by compiling them into HTML previews with syntax highlighting and a table of contents, while also publishing diagnostics to the connected client.

mdoc-lsp · high confidence

Added a new live-reload server component that enables automatic browser refreshes when source files change, along with an improved HTML preview layout featuring a sidebar table of contents and integrated syntax highlighting. This change introduces the internal infrastructure (LiveReload trait, resource loading, and HTML generation) required to support the \--watch\ mode and the \mdoc:js\ modifier for Scala.js integration.

mdoc/src/main/scala/mdoc/internal/livereload · high confidence

A new ParserSettings trait has been added to the parser/shared module, defining a boolean setting allowCodeFenceIndented. This change introduces the configuration option for handling indented code fences within the parser, laying the groundwork for this specific parsing behavior.

parser/shared · high confidence

The mdoc documentation site is now live, built with Docusaurus. Users can access installation guides, documentation on JVM and Scala.js modifiers, and migration notes from tut. The site features Algolia search, a blog, and community links to Discord and GitHub, with a custom theme using orange/brown colors and specific styling for Scala.js code blocks.

website · high confidence

The mdoc position module now includes new internal utilities to support accurate code editing and worksheet interactions. DiffUtils provides unified diff generation for comparing code snippets, while TokenEditDistance enables mapping positions between original and revised code versions (such as an editor buffer versus a semantic snapshot) using Myers' diff algorithm. PositionSyntax adds extension methods to format error messages with line content and carets, and to convert between mdoc's RangePosition and scala.meta's Position types.

mdoc/src/main/scala/mdoc/internal/pos · high confidence

The \mdoc-interfaces\ module now exposes a public API for programmatically evaluating Markdown documents and Scala worksheets. Consumers can use the \Mdoc\ interface to evaluate content via \evaluateMarkdownDocument\ and \evaluateWorksheet\ (with optional modifiers), configuring execution through methods like \withClasspath\, \withScalacOptions\, and \withWorkingDirectory\. The API returns structured results: \EvaluatedMarkdownDocument\ provides diagnostics and rendered content, while \EvaluatedWorksheet\ exposes detailed statement summaries, diagnostic information, and metadata about imported script files, Scalac options, and resolved dependencies/repositories.

mdoc-interfaces · high confidence

mdoc now exposes a public API via the \Main\ and \MainSettings\ classes, allowing external tools like sbt to invoke mdoc programmatically without causing the JVM to exit on errors. \MainSettings\ provides a fluent builder interface to configure inputs, outputs, classpaths, and other options, while \SbtMain\ offers a variant that throws exceptions instead of calling \sys.exit\, ensuring better integration with host environments.

mdoc/src/main/scala/mdoc · high confidence

Added static resources to support enhanced preview and editing experiences: custom CSS for layout and theming, GitHub-style syntax highlighting via highlight.js (v9.12.0) with support for multiple languages, a LiveReload client for automatic browser refreshes during development, and preview-specific CSS. Additionally, ServiceLoader configuration files were created to register the ScatieModifier and the internal Mdoc worksheet interface, enabling Scastie integration and worksheet evaluation capabilities.

mdoc/src/main/resources · high confidence

Introduces a new public \Mdoc\ interface that allows external programs to programmatically evaluate Scala worksheets and Markdown documents. Users can now configure the evaluation environment via methods such as \withClasspath\, \withScalacOptions\, and \withWorkingDirectory\, and retrieve results including diagnostics through \evaluateWorksheet\ and \evaluateMarkdownDocument\.

mdoc/src/main/scala/mdoc/internal/worksheets · high confidence

The mdoc CLI now exposes a public API for extension authors, including traits for PreModifier, PostModifier, and StringModifier, along with their respective context classes (OnLoadContext, PreModifierContext, PostModifierContext, PostModifierContext) and a Variable class for capturing code-fence variables. These additions allow third-party plugins to hook into the markdown processing lifecycle and access execution context details.

cli/src/main/scala/mdoc · high confidence

The repository has been initialized with essential configuration files and documentation. This includes a \.scalafmt.conf\ (version 3.11.5) to enforce code formatting, a \.mergify.yml\ to automate pull request merging, and a \.scala-steward.conf\ to manage dependency updates. Project setup is supported by \.jvmopts\ for JVM tuning, \.gitattributes\ for line-ending consistency, and a \.gitignore\ updated to exclude IDE and build artifacts. Documentation is provided via \AGENTS.md\, \CLAUDE.md\, \CONTRIBUTING.md\, \LICENCE.md\, and \NOTICE\, while \readme.md\ and \website.md\ offer project overviews and local setup instructions.

(repo-wide) · high confidence

Users can now use the \mdoc:scastie\ modifier to embed interactive Scala code snippets from Scastie directly into their documentation. This new \ScastieModifier\ class handles both inline code blocks and specific snippet IDs, generating the necessary JavaScript to load and display the code on the Scastie platform. The implementation defaults to Scala version 2.12.21 and supports a light theme, allowing for dynamic, executable examples in generated HTML.

mdoc/src/main/scala/mdoc/internal/modifiers · high confidence

The \scalamd\ module has removed its \Main\ object, which previously served only as a placeholder printing "Hello!". This cleanup eliminates the barebones CLI entry point that was not part of the library's actual functionality.

scalamd · high confidence

The CLI execution logic has been restructured into a set of dedicated internal modules to improve maintainability and separation of concerns. The new \Dependencies\ module now handles dependency resolution and compiler construction using Coursier, while \ScalacOptions\ manages the parsing and serialization of compiler flags. \MainOps\ centralizes the core processing workflow, including file handling, markdown compilation, output writing, and the integration of the LiveReload server and link hygiene checks. Supporting utilities have also been extracted, such as \Timer\ for performance measurement, \FileException\ for specific error reporting, and \Messages\ for standardized output formatting.

mdoc/src/main/scala/mdoc/internal/cli · high confidence

The markdown processing logic has been reorganized into the \mdoc.internal.markdown\ package, introducing dedicated components for code generation (\CodeBuilder\, \Gensym\), document building (\MarkdownBuilder\), and rendering (\Renderer\). This change includes a new \Processor\ to orchestrate document processing, \MdocExtensions\ to configure the Flexmark parser, and \VariableRegex\ to handle site variable substitution, effectively restructuring how mdoc parses, instruments, and renders Scala code within Markdown files.

mdoc/src/main/scala/mdoc/internal/markdown · high confidence

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

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

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

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

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

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

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

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

The mdoc-js-worker module now uses a dedicated ScalaJSWorkerProvider implementation to instantiate the Scala.js worker. This change introduces a new service provider configuration and a provider class that maps Scala.js logging levels to mdoc's internal log levels and wraps the logger before creating the worker instance, effectively isolating the linker and its dependencies in a separate classloader context.

mdoc-js-worker · high confidence

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

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

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

The Scala 2-specific markdown processing logic has been restructured to improve how code blocks are instrumented and compiled. A new \FailInstrumenter\ class now handles the generation of code for sections expected to fail or warn, separating this logic from the main \Instrumenter\. The main \Instrumenter\ has been updated to explicitly call \SourceStatement\ for binders, addressing deprecated-usage warnings and ensuring correct behavior in newer environments. Additionally, the \MarkdownCompiler\ now explicitly enables the empty package (\exposeEmptyPackage\), allowing users to write code without an explicit package declaration, and includes fixes for compilation issues on newer JDKs.

mdoc/src/main/scala-2 · high confidence

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

The CLI now accepts multiple \--in\ and \--out\ arguments to process several input sources and write to corresponding output locations in a single run. The \Settings\ class has been updated to handle these paired lists, and the \Context\ validation logic enforces that the number of input and output paths matches. Additionally, the system now prevents the \--out\ path from being a subdirectory of the \--in\ path to avoid accidental overwrites, and automatically infers the output filename when an input is a single file and the output is a directory.

repository · high confidence

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

mdoc now correctly resolves classloader URLs on Java 16 and newer versions. A new internal \CompatClassloader\ utility handles the change in JDK internals where the \ucp\ field moved from \AppClassLoader\ to \BuiltinClassLoader\, ensuring that worksheet dependency resolution and other classpath-dependent features work reliably on modern Java versions.

mdoc/src/main/scala/mdoc/internal · high confidence

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 demo documentation test file; Added markdown test infrastructure; Added sbt test for Docusaurus v3 integration; Added scripted test source file; Added test coverage for worksheet evaluation and markdown processing; Added test for scalac options deduplication in Scala 3; Added test for scalacOptions with spaces; Added test input file for CLI classpath functionality; Added tests for HTML path relativization in the Docusaurus plugin; Added tests for sbt-mdoc extra arguments; Added unit tests for CLI argument validation, markdown modifiers, and import directives; Added unit tests for JavaScript code generation and ES module import remapping; Updated Scala.js scripted test to version 1.20.

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 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 60.

• Code Health 96
• Architecture 100
• Maturity 46
• Readiness 61
• Security 74

• 300 commits — 282 feature/other, 18 fixes

• (root) — 105 commits
• (repo) — 89 commits
• mdoc-sbt/src — 39 commits
• project/plugins.sbt — 18 commits
• .github/workflows — 16 commits
• mdoc/src — 12 commits
• tests/unit — 7 commits
• cli/src — 3 commits
• docs/docusaurus.md — 3 commits
• tests/unit-js — 3 commits
• docs/directives.md — 1 commit
• docs/installation.md — 1 commit
• project/Extensions.scala — 1 commit
• project/build.properties — 1 commit
• tests/tests — 1 commit

• fix: Fix maven central badge
• fix: Merge pull request #1069 from tgodzik/fix-whitespace-issues
• fix: Merge pull request #1101 from scalameta/copilot/fix-publish-job
• fix: Merge pull request #1104 from tgodzik/fix-publish
• fix: Merge pull request #1114 from chris-huang-s/docs/fix-github-secrets-link
• fix: Merge pull request #1127 from tgodzik/fix-3.10
• fix: bugfix: Fix clang issues on windows
• fix: bugfix: Fix duplicate flags detection (#993)
• fix: bugfix: Fix issue with wrongly used test compat
• fix: bugfix: Fix publishing
• fix: bugfix: Ignore repo tests for now (#999)
• fix: bugfix: Make mdoc work with Scala 3.10.x
• fix: bugfix: Prepare for Scala 3.8 release (#1031)
• fix: bugfix: Properly use section pos when input is a slice
• fix: bugfix: Strip line end
• fix: bugfix: Switch to temurin, adopt was renamed
• fix: bugfix: Update repo tests (#1017)
• fix: fix: call SourceStatement explicitly in place of implicit cast
• change: Add AGENTS.md, with CLAUDE.md
• change: Add transient annotation
• …and 280 more

• 0 containers · 1 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.

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.