Components

MDU is one solution, Mdu.sln, with one executable project and several libraries. All projects target .NET 10, and each library has a matching .Test project with xUnit tests.

Overview

Project dependencies

This diagram shows how the solution projects depend on one another. Select a project to jump to its description.

mdu

The packaged .NET tool mdu with the command name mdu.

• Program.cs defines all commands, aliases, and options with System.CommandLine and registers the services with Microsoft.Extensions.DependencyInjection.
• Commands/ holds one class per command: LintCommand, FixCommand, PrintTreeCommand, RenderCommand, PdfCommand, ServeCommand, and PageCommand.
• GraphBuilder and the visitors in Service/Visitors build and walk the page tree.
• PreviewServer serves the rendered site for mdu serve and pushes reload events to the browser.
• MarkdownLinks finds and rewrites relative Markdown links. mdu fix, mdu page move (through PageMover), and mdu page links share it.
• MarkdownCompatibility detects MkDocs Material syntax and converts it for mdu fix.
• SiteConfigurationReader reads mdu.yml, GitLastModified reads page dates from git, and LintResultRenderer prints lint results as text, JSON, or GitHub annotations.

Markdown.Document

Reads what MDU needs to know about a page without rendering it: the YAML front matter, the level-one title, and the links. Links include images, reference definitions, and node links in Mermaid, context, and PlantUML diagrams, so the linter checks them all.

Markdown.Linter

Contains the rule codes MDU001–MDU018 and the validators that need only one page and the file system:

The validators use FluentValidation. Rules that need the whole page tree, such as duplicate pages, navigation placement, and MkDocs migration issues, are checked by the LinterVisitor in mdu. See the rules reference for every rule.

Markdown.Renderer

Turns Markdown into pages. HtmlRenderer holds the Markdig pipeline and the embedded HTML template, stylesheet, and scripts; OpenApiMarkdownRenderer reads referenced JSON or YAML specifications and appends their API reference as Markdown; PdfRenderer lays out the same content on A4 pages. Rendering describes both in detail.

Markdown.Search

SearchIndexBuilder splits every page into sections at its headings and writes their plain text to search-index.json. SearchClientAsset writes js/search.js, which searches that index in the browser and links to the matching section.

StaticCode.Highlighter

A small lexer with lightweight grammars for C#, JavaScript, Swift, TypeScript, Python, Kotlin, JSON, SQL, HTML, CSS, Java, Rust, Go, YAML, shell, and Markdown. HtmlFormatter wraps the tokens in span elements whose classes the stylesheet colors. Other languages stay readable as plain code.

StaticCode.Diagrams

Parses diagram sources and writes SVG. DiagramRenderer.TryRenderSvg handles Mermaid flowcharts, sequence and class diagrams, PlantUML component diagrams, and MDU's own context diagrams.

• Flowcharts use their own layered (Sugiyama) layout in Layout/LayeredLayout.cs.
• PlantUML containers are laid out from the inside out, so nested packages size to their content.
• Context diagrams place the central system in the middle and its neighbors around it.
• The SVG carries only CSS classes and no colors; the site stylesheet themes it for light and dark mode.

When a source uses unsupported syntax, TryRenderSvg returns false and the block stays a code block.

StaticCode.Icons

Embeds the icon sets behind the icon shortcodes as gzip-compressed, reduced Iconify JSON. IconCatalog resolves a shortcode such as :material-rocket: to its SVG. The script update-icon-sets.sh regenerates the sets with npm, and dashboard-icons.mjs sanitizes the colored Dashboard Icons with SVGO.

Core.Collections.NodeGraph

A general tree: every node has an optional parent and any number of children. IVisitor<T> and the Visit extension walk the tree depth-first or breadth-first. Each command is a set of visitors over the page tree.

SuperiorIO

Parses paths into elements so the linter can compare a link target with the file-system entry, including its casing.

Third-party libraries