OutWit.Docs.Generator 2.2.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

Automatic Generation (Recommended)

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

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

Hosting Provider Files

Features

Content Index

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

Navigation Index (v1.1.0+)

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.