👁 Image
OutWit.Web.Framework 1.4.1

OutWit.Web.Framework

Part of WitDocs � a Blazor WebAssembly framework for building content-driven static websites with markdown-based content management, SEO optimization, and automatic content generation.

Features

• Reusable Page Components - HomePage, BlogListPage, ProjectPage, ArticlePage, DocsPage, etc.
• Markdown Content - Write content in markdown with YAML frontmatter
• SEO Optimized - Built-in SeoHead component with Open Graph, Twitter Cards, JSON-LD structured data
• Static Site Generation (SSG) - Pre-rendered HTML pages for search engines
• Open Graph Images - Auto-generated social media preview images
• RSS Feed - Automatic RSS feed generation for blog posts
• Pre-built Search Index - Client-side full-text search with pre-generated index
• Fast Navigation - Pre-built navigation index for instant menu rendering
• Fast List Pages - Pre-built content metadata for instant list rendering (NEW in v1.3.0)
• Theme Support - Light/dark mode with CSS variables from theme.css
• Responsive Design - Mobile-first CSS framework
• Multiple Hosting Providers - Cloudflare Pages, Netlify, Vercel, GitHub Pages

Installation

From NuGet

dotnet add package OutWit.Web.Framework

From Source

<ProjectReference Include="path/to/OutWit.Web.Framework.csproj" />

Quick Start

1. Project Structure

your-site/
 Pages/ # Thin page wrappers
 wwwroot/
 content/ # Markdown content
 blog/
 projects/
 articles/
 docs/
 css/
 theme.css # Your color scheme
 site.css # Site-specific styles
 images/
 site.config.json
 Program.cs
 YourSite.csproj

2. Configure Your Site

Create wwwroot/site.config.json:

{
 "siteName": "My Site",
 "baseUrl": "https://example.com",
 "logo": "/images/logo.svg",
 "defaultTheme": "dark",
 "navigation": [
 { "title": "Home", "href": "/" },
 { "title": "Blog", "href": "/blog" },
 { "title": "Contact", "href": "/contact" }
 ],
 "footer": {
 "copyright": "Your Name",
 "socialLinks": [
 { "platform": "github", "url": "https://github.com/you" }
 ]
 },
 "seo": {
 "defaultImage": "/images/social-card.png",
 "twitterHandle": "@yourhandle"
 }
}

3. Create Theme Colors

Create wwwroot/css/theme.css:

:root {
 --color-background: #ffffff;
 --color-text-primary: #333333;
 --color-accent: #007CF0;
 /* ... other variables */
}

[data-theme="dark"] {
 --color-background: #1f1f1f;
 --color-text-primary: #d1d1d1;
 --color-accent: #00a3ff;
}

4. Create Pages

@* Pages/Index.razor *@
@page "/"
@using OutWit.Web.Framework.Components.Pages

<HomePage />

@* Pages/Blog.razor *@
@page "/blog"
@using OutWit.Web.Framework.Components.Pages

<BlogListPage />

@* Pages/BlogPost.razor *@
@page "/blog/{Slug}"
@using OutWit.Web.Framework.Components.Pages

<BlogPostPage Slug="@Slug" />

@code {
 [Parameter] public string Slug { get; set; } = "";
}

Content Structure

Markdown with Frontmatter

---
title: 'My Blog Post'
description: 'Short description for SEO'
summary: |
 Longer summary with **markdown** support
tags: [blazor, dotnet, web]
publishDate: 2024-01-15
menuTitle: 'Short Title' # Optional: short title for navigation menus
showInMenu: true # Show in dropdown menus (default: true)
showInHeader: false # Show as top-level nav item (projects only)
---

# Content starts here

Your markdown content...

Content Folders

wwwroot/content/
 index.json # Auto-generated manifest
 blog/
 2024-01-15-post-title.md
 projects/
 01-project-name/
 index.md
 image.png
 articles/
 my-article.md
 docs/
 getting-started.md

Page Components

Custom Markdown Components

You can embed components directly in markdown content using [[Name ...]] syntax. The framework ships built-in components (YouTube, Svg, FloatingImage), and you can register your own without modifying the framework.

1. Create a Blazor component that takes its values as [Parameter]s (parameters are supplied as strings from the markdown attributes; block components also receive InnerContent and BasePath):

@* PricingTable.razor *@
<div class="pricing pricing--@Plan">...</div>

@code {
 [Parameter] public string Plan { get; set; } = "free";
}

2. Register it in Program.cs after AddOutWitWebFramework():

builder.Services.AddOutWitWebFramework();
builder.Services.AddContentComponent<PricingTable>("Pricing");

3. Use it in any markdown file:

Here are our plans:

[[Pricing plan="pro"]]

Block (wrapper) syntax with inner content is also supported:

[[Note type="warning"]]
This is important.
[[/Note]]

Static site generation: embedded components can't be rendered to static HTML at build time, so the generator degrades them gracefully for crawlers — block components keep their inner content (still indexed), self-closing components are omitted. The live Blazor app renders the real component after hydration.

Build Configuration

MSBuild Properties

<PropertyGroup>
 
 <OutWitGenerateContent>true</OutWitGenerateContent>
 
 
 <OutWitGenerateInDebug>true</OutWitGenerateInDebug>
 
 
 <OutWitGenerateStaticPages>true</OutWitGenerateStaticPages>
 <OutWitGenerateSearchIndex>true</OutWitGenerateSearchIndex>
 <OutWitGenerateRssFeed>true</OutWitGenerateRssFeed>
 <OutWitGenerateOgImages>false</OutWitGenerateOgImages>
 
 
 <OutWitHostingProvider>cloudflare</OutWitHostingProvider>
</PropertyGroup>

Development Mode

For faster development experience, enable content generation in Debug mode:

<PropertyGroup>
 <OutWitGenerateInDebug>true</OutWitGenerateInDebug>
</PropertyGroup>

This generates navigation and metadata indices during Debug builds, providing:

• Instant menu rendering (no markdown parsing)
• Fast list pages (BlogListPage, HomePage)
• Static HTML pages are NOT generated in Debug mode by default

Without this option, the framework falls back to loading content directly (slower but works).

Automatic Generation

On Release build, the framework automatically runs the tool to generate:

• content/index.json - Content manifest
• navigation-index.json - Pre-built navigation menu data (v1.2.0+)
• content-metadata.json - Pre-built content metadata for lists (NEW in v1.3.0)
• 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 for SEO
• _headers, _redirects - Hosting provider config

Prerequisite: Install the Generator tool globally:

dotnet tool install -g OutWit.Web.Generator

Then simply build in Release mode:

dotnet build -c Release

Manual Generation

outwit-generate \
 --content-path ./wwwroot/content \
 --output-path ./wwwroot \
 --site-url https://example.com \
 --site-name "My Site"

For OG images (requires Playwright):

npx playwright install chromium
outwit-generate --content-path ./wwwroot/content --output-path ./wwwroot

Performance Optimization

Navigation Index (v1.2.0+)

The framework generates a navigation-index.json file containing pre-built menu data. This eliminates the need to parse all markdown files when loading the header navigation, resulting in significantly faster page loads for sites with many content items.

Content Metadata Index (v1.3.0+)

The framework now generates a content-metadata.json file containing lightweight metadata for all content items. This allows list pages (HomePage, BlogListPage) to render instantly without parsing individual markdown files.

Before v1.3.0: List pages loaded and parsed ALL markdown files to display titles, descriptions, and tags

After v1.3.0: List pages load a single small JSON file with pre-extracted metadata

The content metadata index includes:

• Blog posts: slug, title, description, summary, tags, publishDate, author, readingTime, featuredImage
• Projects: slug, title, description, summary, order, tags, url
• Articles: slug, title, description, order, tags, publishDate
• Docs: slug, title, description, order, parentSlug
• Features: slug, title, description, order, icon, iconSvg
• Dynamic sections support

During development (when the metadata index is not available), the framework falls back to loading content directly.

Open Graph Images

The framework can generate social media preview images (1200x630 PNG) for each content page.

Colors are automatically read from your theme.css:

• --color-accent - Accent color for highlights
• --color-background - Background color

To enable in build:

<OutWitGenerateOgImages>true</OutWitGenerateOgImages>

Requires Playwright:

npm install -D playwright
npx playwright install chromium

Services

Deployment

Cloudflare Pages

- name: Build
 run: dotnet publish -c Release

- name: Deploy
 uses: cloudflare/pages-action@v1
 with:
 directory: publish/wwwroot

GitHub Actions Example

name: Build and Deploy

on:
 push:
 branches: [main]

jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 
 - name: Setup .NET
 uses: actions/setup-dotnet@v4
 with:
 dotnet-version: '10.0.x'
 
 - name: Build
 run: dotnet publish -c Release -o publish
 
 - name: Deploy to Cloudflare Pages
 uses: cloudflare/pages-action@v1
 with:
 apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
 projectName: your-site
 directory: publish/wwwroot

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.