LithoSharp 1.0.0

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.

Version: 1.0.0.

Features

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

Quick Start

With the .NET 10 SDK installed:

dotnet new install LithoSharp.ProjectTemplates::1.0.0
dotnet tool install LithoSharp.Tool --version 1.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 1.0.0 and call the library directly; a CLI host is not required.

Sample sites

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

Examples

Requirements

.NET 10 is required; release preparation uses SDK 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.25.12. Production output needs only a static HTTP host.

Documentation

• 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

Upgrade to 1.0.0

Update the LithoSharp packages and CLI together to 1.0.0, then rebuild your site and check content warnings, links and custom CSS. Existing public signatures are retained, but the Markdown compiler has changed: footnotes, definition lists and some other Markdig extensions are unsupported. Review the Markdown limitations and 1.0.0 changes before upgrading.

See the API compatibility contract and 1.x tooling policy. Sites upgrading from 0.2.0 should also follow the 0.3 migration guide. MDX remains optional.

Known limitations

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.

Performance

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.

Contribute and license

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