OutWit.Docs.Generator 2.4.2

dotnet tool install --global OutWit.Docs.Generator --version 2.4.2
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local OutWit.Docs.Generator --version 2.4.2
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=OutWit.Docs.Generator&version=2.4.2
                    
nuke :add-package OutWit.Docs.Generator --version 2.4.2
                    

OutWit.Docs.Generator

Part of WitDocs — a .NET CLI tool that generates static content for WitDocs sites: content/navigation/metadata indices, sitemap, robots.txt, RSS feed, search index, pre-rendered (syntax-highlighted) static HTML pages, OG images, and hosting-provider config.

Installation

dotnet tool install -g OutWit.Docs.Generator

Usage

When using OutWit.Docs.Framework, content generation runs automatically on Release builds:

  1. Install the Generator tool globally
  2. In Visual Studio, switch to Release configuration
  3. Build your project (Ctrl+Shift+B)
  4. Generation runs automatically after build!

Manual CLI Usage

# --site points at the project dir; --output defaults to <site>/wwwroot
witdocs-generate --site ./MySite --url https://mysite.com --hosting cloudflare

CLI Options

Option Description Default
-s, --site Path to the site project directory Required
-o, --output Output directory <site>/wwwroot
-u, --url Site URL (read from site.config.json if omitted) (from config)
-h, --hosting Hosting provider (cloudflare/netlify/vercel/github/none) cloudflare
--skip-sitemap Skip sitemap.xml + robots.txt false
--skip-search Skip search index false
--skip-rss Skip RSS feed false
--skip-static Skip static HTML pages false
--og-images Generate OG images (requires Playwright) false
--force-og Force regenerate OG images false
--search-content-max-length Max content length per search entry 10000

MSBuild Properties

When using the Framework, configure generation via MSBuild properties in your .csproj:

<PropertyGroup>
  
  <OutWitSiteUrl>https://example.com</OutWitSiteUrl>
  
  
  <OutWitSiteName>My Site</OutWitSiteName>
  
  
  <OutWitHostingProvider>cloudflare</OutWitHostingProvider>
  
  
  <OutWitGenerateStaticPages>true</OutWitGenerateStaticPages>
  <OutWitGenerateSearchIndex>true</OutWitGenerateSearchIndex>
  <OutWitGenerateRssFeed>true</OutWitGenerateRssFeed>
  <OutWitGenerateOgImages>false</OutWitGenerateOgImages>
  
  
  <OutWitGenerateContent>true</OutWitGenerateContent>
  
  
  <OutWitGenerateInDebug>true</OutWitGenerateInDebug>
</PropertyGroup>

Generated Files

File Description
content/index.json Content manifest listing all files
navigation-index.json Pre-built navigation menu data
content-metadata.json Pre-built content metadata for fast list rendering
sitemap.xml SEO sitemap
robots.txt Crawler rules
search-index.json Pre-built search index
feed.xml RSS feed for blog
*/index.html Static HTML pages

Hosting Provider Files

Provider Files Generated
Cloudflare _headers, _routes.json
Netlify _headers, _redirects
Vercel vercel.json
GitHub Pages .nojekyll, 404.html

Features

Content Index

Generates index.json listing all content files by category (blog, projects, docs, articles, features) and dynamic sections.

Generates navigation-index.json for instant menu rendering without parsing markdown files.

Content Metadata Index (v1.2.0+)

Generates content-metadata.json for fast list page rendering (BlogListPage, HomePage) without parsing all markdown files.

Sitemap

Creates sitemap.xml and robots.txt with proper lastmod dates.

Search Index

Generates search-index.json for client-side search functionality.

RSS Feed

Creates feed.xml for blog posts with proper formatting.

Static HTML

Pre-renders HTML pages for SEO and faster initial load.

OG Images

Generates Open Graph images for social sharing using Playwright.

# Install Playwright before using OG images
npx playwright install chromium

Dynamic Content Sections

Define custom content sections in site.config.json:

{
  "contentSections": [
    { "folder": "solutions", "route": "solutions", "menuTitle": "Solutions" }
  ]
}

GitHub Actions

Example workflow step:

- name: Install Generator
  run: dotnet tool install -g OutWit.Docs.Generator

- name: Publish + generate
  run: |
    dotnet publish MySite/MySite.csproj -c Release -o publish -p:OutWitGenerateContent=false
    witdocs-generate --site MySite --output publish/wwwroot --url https://example.com --hosting cloudflare

What's New

v1.4.x

  • Syntax-highlighted static pages: the SSG output (and the live app) highlight fenced code via the framework's build-time highlighter (ColorCode) — no client JS.
  • Trailing-slash canonical consistency: sitemap.xml <loc>, RSS <link>/<guid> and pre-rendered internal links use the final 200 URL (trailing slash).
  • No-JS-readable static pages: pre-rendered content is visible without JS; the spinner is shown only when JS is available (no "JavaScript required" dead-end).
  • Hosting headers: the Blazor boot loaders (dotnet.js, blazor.webassembly.js) are emitted with no-cache (content-hashed assets stay immutable), so deploys are never pinned to a stale build.

v1.3.x

  • Cloudflare _routes.json for SPA routing; navigation + content-metadata indices; markdown rendering fixes for Description/Summary.

License

Licensed under the Apache License, Version 2.0. See LICENSE.

Attribution (optional)

If you use WitDocs in a product, a mention is appreciated (but not required), for example: "Built with WitDocs".

Trademark / Project name

"WitDocs" and "OutWit" are used to identify the official project by Dmitry Ratner.

You may:

  • refer to the project name in a factual way (e.g., "built with WitDocs");
  • use the name to indicate compatibility (e.g., "WitDocs-compatible").

You may not:

  • use "WitDocs" as the name of a fork or a derived product in a way that implies it is the official project;
  • use the WitDocs logo to promote forks or derived products without permission.
Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
2.4.2 104 11/13/2026
2.4.1 188 8/18/2026
2.4.0 125 8/18/2026
2.3.2 144 8/6/2026
2.3.1 142 8/6/2026
2.3.0 155 7/24/2026
2.2.2 160 7/1/2026
2.2.1 149 7/1/2026
2.2.0 151 6/24/2026
2.1.0 159 6/21/2026
2.0.0 252 6/17/2026