rudironsoni dotnet-documentation-strategy
Documentation tooling recommendation for .NET projects: decision tree for selecting Starlight (Astro-based, modern default), Docusaurus (React-based, plugin-rich), or DocFX (community-maintained, .NET-native XML doc integration). Covers MarkdownSnippets for verified code inclusion from source files, Mermaid rendering support across all platforms, migration paths between tools, and project-context-driven recommendation based on team size, project type, and existing ecosystem.
Version assumptions: Starlight v0.x+ (Astro 4+). Docusaurus v3.x (React 18+). DocFX v2.x (community-maintained).
MarkdownSnippets as dotnet tool (.NET 8.0+ baseline). Mermaid v10+ (GitHub, Starlight, Docusaurus render natively).
Scope
- Decision tree for selecting Starlight, Docusaurus, or DocFX
- Initial setup and configuration for each platform
- MarkdownSnippets for verified code inclusion
- Mermaid rendering support across platforms
- Migration paths between documentation tools
Out of scope
- CI/CD deployment pipelines for doc sites -- see [skill:dotnet-gha-deploy]
- API documentation generation (DocFX API reference, OpenAPI-as-docs) -- see [skill:dotnet-api-docs]
- XML documentation comment authoring -- see [skill:dotnet-xml-docs]
- Mermaid diagram syntax and .NET-specific patterns -- see [skill:dotnet-mermaid-diagrams]
Cross-references: [skill:dotnet-gha-deploy] for doc site deployment pipelines, [skill:dotnet-api-docs] for API reference generation, [skill:dotnet-xml-docs] for XML doc comment authoring, [skill:dotnet-mermaid-diagrams] for .NET-specific Mermaid diagrams.
Documentation Tooling Decision Tree
Choose documentation tooling based on project context, team capabilities, and existing ecosystem investments.
Quick Decision Matrix
| Factor | Starlight | Docusaurus | DocFX |
|---|---|---|---|
| Best for | New projects, static docs | React teams, blog + docs | Existing .NET projects with XML docs |
| Learning curve | Low (Markdown + MDX) | Medium (React + MDX) | Medium (.NET toolchain) |
| Built-in search | Yes (Pagefind) | Yes (Algolia plugin) | Yes (Lunr.js) |
| Versioned docs | Yes (manual setup) | Yes (built-in) | Yes (built-in) |
| i18n support | Yes (built-in) | Yes (built-in) | Limited |
| Mermaid support | Native (remark plugin) | Native (MDX plugin) | Plugin required |
| API reference from XML | Manual integration | Manual integration | Native (docfx metadata) |
| Hosting | Any static host | Any static host | Any static host |
| Build speed | Fast (Astro) | Moderate (Webpack/Rspack) | Moderate (.NET toolchain) |
Decision Flowchart
Start: New documentation site for .NET project
|
+-- Do you have existing DocFX content?
| |
| +-- Yes --> Do you need XML doc API reference integration?
| | |
| | +-- Yes --> Stay with DocFX (lowest migration cost)
| | |
| | +-- No --> Migrate to Starlight (see Migration Paths below)
| |
| +-- No --> Is your team heavily invested in React?
| |
| +-- Yes --> Docusaurus (leverage React skills, plugin ecosystem)
| |
| +-- No --> Starlight (modern default, best DX)
```text
### Project Context Factors
**Library vs Application:**
- Libraries benefit from API reference integration -- DocFX excels here with `docfx metadata` generating API docs
directly from XML comments
- Applications typically need guides, tutorials, and architectural docs -- Starlight or Docusaurus are better fits
- Hybrid (library + app docs) -- consider Starlight with separate API reference section linking to DocFX-generated
content
**Team Size:**
- Solo / small team (1-3): Starlight -- minimal configuration, fast iteration
- Medium team (4-10): Starlight or Docusaurus -- both handle multiple contributors well with built-in versioning
- Large team (10+): Docusaurus -- plugin ecosystem handles complex multi-author workflows, custom review integrations
**Existing Ecosystem:**
- React ecosystem: Docusaurus integrates naturally with existing React component libraries and storybook
- .NET-only toolchain: DocFX avoids JavaScript build dependencies entirely
- Polyglot / modern: Starlight works with any tech stack, minimal JavaScript knowledge required
---
## Starlight (Astro-Based) -- Modern Default
Starlight is an Astro-based documentation framework. It is the recommended default for new .NET documentation sites due
to fast build times, built-in search (Pagefind), i18n, and native Mermaid support.
### Initial Setup
```bash
# Create a new Starlight project
npm create astro@latest -- --template starlight my-docs
cd my-docs
npm install
npm run dev
```text
### Project Structure
```text
my-docs/
astro.config.mjs # Starlight configuration
src/
content/
docs/ # Markdown/MDX documentation pages
index.mdx # Landing page
getting-started/
installation.md
quick-start.md
guides/
configuration.md
architecture.md
reference/
api.md
cli.md
assets/ # Images, diagrams
public/ # Static assets (favicon, robots.txt)
```markdown
### Configuration
```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
integrations: [
starlight({
title: 'My .NET Library',
social: {
github: 'https://github.com/mycompany/my-library',
},
sidebar: [
{
label: 'Getting Started',
items: [
{ label: 'Installation', slug: 'getting-started/installation' },
{ label: 'Quick Start', slug: 'getting-started/quick-start' },
],
},
{
label: 'Guides',
autogenerate: { directory: 'guides' },
},
{
label: 'Reference',
autogenerate: { directory: 'reference' },
},
],
}),
],
});
```text
### Mermaid Support in Starlight
```bash
# Install Mermaid remark plugin
npm install remark-mermaidjs
```bash
```javascript
// astro.config.mjs
import remarkMermaid from 'remark-mermaidjs';
export default defineConfig({
markdown: {
remarkPlugins: [remarkMermaid],
},
integrations: [
starlight({
/* ... */
}),
],
});
```text
After configuration, use standard Mermaid fenced code blocks in any Markdown file. See [skill:dotnet-mermaid-diagrams]
for .NET-specific diagram patterns.
### Versioned Documentation
Use the `@lorenzo_lewis/starlight-utils` plugin for version dropdown navigation -- this is the recommended approach for
Starlight versioned docs.
Alternatively, use directory-based versioning with explicit routing in `astro.config.mjs`:
```text
src/content/docs/
v1/
getting-started.md
api-reference.md
v2/
getting-started.md
api-reference.md
```markdown
Configure the sidebar to point to the current version directory and add a version selector via the plugin or custom
Astro component.
---
## Docusaurus (React-Based)
Docusaurus is a React-based documentation framework maintained by Meta. It is a strong choice for teams already invested
in the React ecosystem, offering a rich plugin system, built-in blog, and versioned docs.
### Initial Setup
```bash
npx create-docusaurus@latest my-docs classic
cd my-docs
npm install
npm start
```text
### Project Structure
```text
my-docs/
docusaurus.config.js # Docusaurus configuration
docs/ # Markdown/MDX documentation
intro.md
getting-started/
installation.md
guides/
configuration.md
blog/ # Optional blog posts
src/
components/ # Custom React components
pages/ # Custom pages
static/ # Static assets
sidebars.js # Sidebar configuration
```javascript
### Configuration
```javascript
// docusaurus.config.js
/** @type {import('@docusaurus/types').Config} */
const config = {
title: 'My .NET Library',
tagline: 'High-performance widgets for .NET',
url: 'https://mycompany.github.io',
baseUrl: '/my-library/',
organizationName: 'mycompany',
projectName: 'my-library',
presets: [
[
'classic',
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
sidebarPath: require.resolve('./sidebars.js'),
editUrl: 'https://github.com/mycompany/my-library/tree/main/docs/',
},
blog: {
showReadingTime: true,
},
theme: {
customCss: require.resolve('./src/css/custom.css'),
},
}),
],
],
};
module.exports = config;
```text
### Mermaid Support in Docusaurus
```bash
npm install @docusaurus/theme-mermaid
```bash
```javascript
// docusaurus.config.js
const config = {
markdown: {
mermaid: true,
},
themes: ['@docusaurus/theme-mermaid'],
// ...
};
```text
### Versioned Documentation
Docusaurus has first-class versioning support:
```bash
# Snapshot current docs as a version
npx docusaurus docs:version 1.0
# Creates versioned_docs/version-1.0/ and versions.json
```json
This creates a snapshot of the current `docs/` directory. The `docs/` directory continues to represent the "next"
unreleased version.
---
## DocFX (Community-Maintained, .NET-Native)
DocFX is a .NET-native documentation generator that integrates directly with XML documentation comments. Microsoft
dropped official support in November 2022, and the project is now community-maintained. It remains widely used in the
.NET ecosystem, particularly for projects with heavy API reference documentation needs.
### Initial Setup
```bash
# Install DocFX as a .NET tool
dotnet tool install -g docfx
# Initialize a new DocFX project
docfx init
# Build the documentation
docfx build
# Serve locally
docfx serve _site
```text
### Project Structure
```text
docs/
docfx.json # DocFX configuration
toc.yml # Table of contents
index.md # Landing page
articles/ # Conceptual documentation
getting-started.md
configuration.md
api/ # Auto-generated API reference
.gitignore # Generated files excluded from source control
images/ # Static assets
templates/ # Custom templates (optional)
```text
### Configuration
```json
{
"metadata": [
{
"src": [
{
"files": ["src/MyLibrary/MyLibrary.csproj"],
"src": ".."
}
],
"dest": "api",
"properties": {
"TargetFramework": "net8.0"
}
}
],
"build": {
"content": [
{
"files": ["api/**.yml", "api/index.md"]
},
{
"files": ["articles/**.md", "toc.yml", "*.md"]
}
],
"resource": [
{
"files": ["images/**"]
}
],
"dest": "_site",
"globalMetadata": {
"_appTitle": "My .NET Library",
"_enableSearch": true
}
}
}
```text
### XML Doc Integration
DocFX's primary advantage is native API reference generation from XML documentation comments:
```bash
# Generate API metadata from project XML docs
docfx metadata docfx.json
# This creates YAML files in the api/ directory
# representing all public types, methods, and properties
```json
The generated API reference automatically links to conceptual articles via `uid` cross-references. See
[skill:dotnet-xml-docs] for XML documentation comment authoring best practices.
### Mermaid Support in DocFX
DocFX requires a template plugin for Mermaid rendering:
```json
{
"build": {
"globalMetadata": {
"_enableMermaid": true
},
"template": ["default", "modern"],
"postProcessors": ["ExtractSearchIndex"]
}
}
```text
The `modern` template includes Mermaid support since DocFX v2.75+. Earlier versions require a custom template extension.
Note that `_enableMermaid` is a template-specific convention, not an officially documented DocFX property. For the
`default` template, add the Mermaid JavaScript library via a custom template extension.
---
## MarkdownSnippets -- Verified Code Inclusion
MarkdownSnippets is a `dotnet tool` that includes verified code snippets from actual source files into Markdown
documentation. This eliminates stale code examples by keeping documentation in sync with compilable source code.
### Installation
```bash
# Install as a local dotnet tool
dotnet new tool-manifest
dotnet tool install MarkdownSnippets.Tool
# Or install globally
dotnet tool install -g MarkdownSnippets.Tool
```markdown
### Usage
**1. Mark code regions in source files with `#region` directives:**
```csharp
// src/MyLibrary/WidgetService.cs
public class WidgetService
{
#region CreateWidget
public async Task<Widget> CreateWidgetAsync(string name, CancellationToken ct = default)
{
ArgumentException.ThrowIfNullOrWhiteSpace(name);
var widget = new Widget { Name = name, CreatedAt = DateTimeOffset.UtcNow };
await _repository.AddAsync(widget, ct);
return widget;
}
#endregion
}
```text
**2. Reference snippets in Markdown:**
```markdown
## Creating a Widget
To create a widget, use the `CreateWidgetAsync` method:
<!-- snippet: CreateWidget -->
<!-- endSnippet -->
```text
**3. Run MarkdownSnippets to inject the code:**
```bash
dotnet tool run mdsnippets
```bash
This replaces the snippet placeholder with the actual code from the source file, keeping the documentation in sync with
the implementation.
### Configuration
```json
// mdsnippets.json (project root)
{
"Convention": "InPlaceOverwrite",
"ReadOnly": false,
"LinkFormat": "GitHub",
"UrlPrefix": "https://github.com/mycompany/my-library/blob/main",
"TocExcludes": ["**/obj/**", "**/bin/**"],
"ExcludeDirectories": ["node_modules", ".git"]
}
```text
### Integration with Doc Platforms
MarkdownSnippets works with all three documentation platforms since it operates on standard Markdown files before the
platform build step:
```bash
# In your build script or CI pipeline:
dotnet tool run mdsnippets # 1. Inject verified snippets
npm run build # 2. Build Starlight/Docusaurus site
# For DocFX:
dotnet tool run mdsnippets # 1. Inject verified snippets
docfx build # 2. Build DocFX site
```text
---
## Mermaid Rendering Across Platforms
All three recommended documentation platforms support Mermaid diagrams, and GitHub renders Mermaid natively in Markdown
files.
| Platform | Mermaid Support | Setup Required |
| ---------- | --------------- | -------------------------------------------------- |
| GitHub | Native | None -- fenced code blocks with `mermaid` language |
| Starlight | Plugin | `remark-mermaidjs` npm package |
| Docusaurus | Plugin | `@docusaurus/theme-mermaid` + config flag |
| DocFX | Template | `modern` template or custom template extension |
Use standard fenced code blocks with the `mermaid` language identifier across all platforms:
````markdown
```mermaid
graph LR
A[Client] --> B[API Gateway]
B --> C[Service A]
B --> D[Service B]
```text
See [skill:dotnet-mermaid-diagrams] for .NET-specific diagram types (C4 architecture, async patterns, EF Core models, DI graphs).
Migration Paths
DocFX to Starlight
DocFX-to-Starlight migration is the most common path for .NET projects modernizing their documentation.
Content migration:
- Copy
articles/Markdown files tosrc/content/docs/ - Convert
toc.ymlentries to Starlight sidebar configuration inastro.config.mjs - Replace DocFX-specific metadata YAML headers with Starlight frontmatter
- Convert
xrefcross-references to standard Markdown links - Replace
> [!NOTE]/> [!WARNING]callout syntax with Starlight<Aside>components (or keep GitHub-compatible blockquote syntax)
API reference migration:
- DocFX
docfx metadataoutput (YAML files) has no direct Starlight equivalent - Option A: Continue running
docfx metadataand host API reference as a separate subsite - Option B: Use TypeDoc-style API extraction tools and convert to Markdown pages
- Option C: Link to hosted API reference on a separate URL
Checklist:
# Find all DocFX-specific syntax to convert
grep -rn "xref:" articles/ # Cross-references
grep -rn "\[!NOTE\]" articles/ # Callout syntax
grep -rn "\[!WARNING\]" articles/ # Callout syntax
grep -rn "^\s*uid:" articles/ # UID metadata
```text
### Docusaurus to Starlight
**Content migration:**
1. Copy `docs/` Markdown files to `src/content/docs/`
2. Convert `sidebars.js` to Starlight sidebar configuration
3. Replace Docusaurus-specific MDX components (`<Tabs>`, `<TabItem>`) with Starlight equivalents
4. Convert `docusaurus.config.js` navigation to Starlight config
5. Migrate custom React components if used in MDX (Starlight supports Astro components and limited React via
`@astrojs/react`)
**Blog migration:**
- Starlight does not have a built-in blog -- use the `starlight-blog` community plugin or maintain a separate Astro blog
section
---
## Code Navigation (Serena MCP)
**Primary approach:** Use Serena symbol operations for efficient code navigation:
1. **Find definitions**: `serena_find_symbol` instead of text search
2. **Understand structure**: `serena_get_symbols_overview` for file organization
3. **Track references**: `serena_find_referencing_symbols` for impact analysis
4. **Precise edits**: `serena_replace_symbol_body` for clean modifications
**When to use Serena vs traditional tools:**
- ✅ **Use Serena**: Navigation, refactoring, dependency analysis, precise edits
- ✅ **Use Read/Grep**: Reading full files, pattern matching, simple text operations
- ✅ **Fallback**: If Serena unavailable, traditional tools work fine
**Example workflow:**
```text
# Instead of:
Read: src/Services/OrderService.cs
Grep: "public void ProcessOrder"
# Use:
serena_find_symbol: "OrderService/ProcessOrder"
serena_get_symbols_overview: "src/Services/OrderService.cs"
```
## Agent Gotchas
1. **Recommend Starlight as the modern default** -- unless the project has an existing DocFX site with heavy XML doc
integration or the team is deeply invested in React (Docusaurus). Do not recommend DocFX for new projects without XML
doc API reference needs.
1. **DocFX is community-maintained since November 2022** -- Microsoft transferred the repository to the community. It is
still actively maintained and widely used, but new projects should evaluate Starlight or Docusaurus first.
1. **MarkdownSnippets runs BEFORE the doc platform build** -- it is a pre-processing step that modifies Markdown files
in place. Always run `dotnet tool run mdsnippets` before `npm run build` (Starlight/Docusaurus) or `docfx build`
(DocFX).
1. **Do not generate CI deployment YAML** -- doc site deployment workflows belong to [skill:dotnet-gha-deploy]. This
skill covers tooling selection and local authoring setup only.
1. **Do not generate API reference configuration** -- DocFX API reference setup, OpenAPI-as-documentation patterns, and
doc-code sync belong to [skill:dotnet-api-docs]. This skill helps choose the platform, not configure API reference
generation.
1. **Mermaid fenced code blocks work identically across GitHub, Starlight, and Docusaurus** -- use the same `mermaid`
language identifier everywhere. Only DocFX requires additional template configuration.
1. **MarkdownSnippets `#region` names must be unique across the entire solution** -- duplicate region names cause
ambiguous snippet resolution. Use descriptive names like `CreateWidgetAsync` not generic names like `Example1`.
1. **Starlight versioning is directory-based, not command-based** -- unlike Docusaurus (`npx docusaurus docs:version`),
Starlight uses directory structure or community plugins for versioning. Do not suggest Docusaurus versioning commands
for Starlight projects.