LithoSharp

English | 日本語

A type-safe static site and documentation generator for .NET with C#, Markdown, MDX, React and incremental builds. Build documentation alongside your .NET code, validate content and links during generation, and deploy ordinary static files.

The current release is 2.0.0. The installation examples below use this version. For an existing site, follow the upgrade guide.

• Typed C# content collections, routes and references, with strict schema validation and optional Roslyn source generators and build diagnostics.
• Markdown and optional MDX 3 with React, build-time HTML, page hydration and selective hydration with explicit islands.
• Docs, Blog and independent pages, multiple Docs collections, versions, locales, sidebars and local search.
• Dependency graphs, persistent caches, invalidation reasons and artifact ownership for inspectable incremental builds.
• Staged output transactions and rollback before publication, with route and ownership validation.
• Structured link, anchor, canonical, redirect and SEO diagnostics.
• XML .NET API documentation, OpenAPI 3 JSON, exact xrefs and checked examples.
• .NET testing APIs for sites, routes, artifacts, DOM, components and layouts.
• Fingerprinted assets, responsive images and explicit extension points for C# rendering and trusted MDX plugins.

With the .NET 10 SDK installed:

dotnet new install LithoSharp.ProjectTemplates::2.0.0
dotnet tool install LithoSharp.Tool --version 2.0.0 --tool-path .tools
.tools/lithosharp new docs MyDocs -o MyDocs
.tools/lithosharp build MyDocs -c Release
.tools/lithosharp serve MyDocs -c Release

On Windows the executable is .tools/lithosharp.exe. Edit MyDocs/content and configure DocsSiteFactory.cs. Deploy MyDocs/dist to a static HTTP host. For isolated installation, Markdown authoring, MDX and an interactive component, follow the complete Quick Start.

Existing applications can use dotnet add package LithoSharp --version 2.0.0 and call the library directly; a CLI host is not required.

Generated from the included factories. Both built-in templates support light/dark switching, responsive menus and keyboard navigation. Set SiteThemeOptions.EnableThemeSwitching = false to disable switching; see theme configuration.

Docs — light	Blog — dark

.NET 10 is required. The minimum supported SDK is 10.0.300. The CLI development server also uses the ASP.NET Core shared framework provided with the SDK. Markdown-only sites do not need Node.js or React. MDX requires Node.js 24.13.0 and explicit worker restore; the lockfile pins MDX 3.1.1, React 19.2.4 and esbuild 0.28.2. Production output needs only a static HTTP host.

Install LithoSharp for VS Code for Markdown/MDX diagnostics, heading navigation, build commands and site preview. See the extension guide.

• CLI and site factories, MDX and documentation sites
• Typed Markdown collections, typed YAML, source generators
• Build graph, incremental builds
• Assets and images, site quality
• Testing, HTML/CSS contract, compatibility contract

Update the LithoSharp packages, CLI and templates you use together to 2.0.0. Follow the 2.0 upgrade guide, including the breaking Testing API change from Document to Snapshot. Rebuild your site and check content warnings, links and custom CSS. MDX remains optional; see the supported Markdown syntax.

Notes for migrations between older releases are preserved in the upgrade history.

MDX and C# site code execute as trusted build code. HTML safety is not a code sandbox. Large MDX rebuilds can still bundle many interactive entries; arbitrary Docusaurus plugins, trimming and Native AOT are unsupported. Read Known limitations before choosing an execution environment.

In the static-page fixture measured with 0.3.0, selective hydration reduced JS from 449,585 to 15,817 bytes and hydration roots from one to zero. This does not represent all island or fallback pages. The 10,000-page MDX corpus took 274.30 s cold and 105.13 s for a no-op. A 100/1,000-page competitor comparison is summarized alongside the Markdown results remeasured with the 1.0.0 candidate. See conditions, limits and reproduction.

See CONTRIBUTING for build and verification commands. MIT licensed; see LICENSE and third-party notices.