A static website generator powered by NUKE, Markdig, and Pico CSS. Write content in Markdown with YAML front-matter, and StaticWGen generates a complete static website with SEO metadata, syntax highlighting, diagrams, feeds, and more.

• Markdown to HTML — Convert .md files to styled HTML pages using Markdig
• YAML Front-Matter — Define page metadata (title, description, author, date, keywords, image)
• Prism.js Syntax Highlighting — Automatic code block highlighting for 200+ languages
• Mermaid Diagrams — Embed flowcharts, sequence diagrams, and more using fenced code blocks
• Emoji Support — Use :emoji: shortcodes in your content
• LaTeX Mathematics — Inline \( ... \) and display \[ ... \] math expressions
• Table of Contents — Auto-generated TOC for pages with 3+ headings, configurable depth
• SEO Generation — Open Graph, Twitter Cards, sitemap.xml, robots.txt, JSON-LD schema
• Atom Feed — Automatic feed.xml generation for blog content
• Blog Index — Paginated blog listing with configurable posts per page
• Tagging System — Tag index and per-tag pages from keywords metadata
• Search Index — Client-side search via generated search-index.json
• Content Lifecycle — Draft, scheduled, and archived content support
• Internationalization — Multi-language pages with hreflang links
• Image Optimization — Automatic resizing, WebP generation, lazy loading
• HTML Minification — Minify output HTML and fingerprint CSS/JS assets
• Output Validation — HTML structure, accessibility (WCAG), SEO, and link checking
• Analytics Integration — Plausible, Google Analytics (GA4), or custom scripts
• Theme System — Multiple themes with fallback to legacy template
• Development Server — Live-reload dev server with file watching
• Scaffolding — Quick-start commands for new posts, pages, and project init
• Theme Switching — Built-in light/dark/auto theme toggle
• Docker Deployment — One-command deployment with nginx
• CI/CD — GitHub Actions workflows for build, release, and GitHub Pages deployment

graph LR A[input/*.md] --> B[GenerateHtml] B --> C[output/*.html] B --> D[GenerateTagPages] B --> E[GenerateSitemap] B --> F[GenerateRobotsTxt] B --> G[GenerateFeed] B --> H[GenerateBlogIndex] D --> I[output/tags/*.html] E --> J[output/sitemap.xml] F --> K[output/robots.txt] G --> L[output/feed.xml] H --> M[output/blog.html] C & I & J & K & L & M --> N[BuildWebsite] N --> O[OptimizeImages] O --> P[OptimizeOutput] P --> Q[Validate] P --> R[CompressOutput] N --> S[BuildDockerImage] S --> T[DeployDockerImage] N --> U[GenerateBuildReport] N --> V[GenerateSearchIndex] 

• .NET 10 SDK (or later)

git clone https://github.com/Atypical-Consulting/StaticWGen.git cd StaticWGen

./build.sh BuildWebsite \ --site-base-url "http://localhost:8080" \ --site-title "My Site"

The generated site is in the output/ directory.

./build.sh Watch \ --site-base-url "http://localhost:3000" \ --site-title "My Site"

Open http://localhost:3000 in your browser. Changes to input/ and template/ are automatically rebuilt with live reload.

cd output && python3 -m http.server 8080

./build.sh DeployDockerImage \ --site-base-url "http://localhost:8080" \ --site-title "My Site" \ --image-name my-site \ --version-tag latest \ --container-name my-site \ --host-port 8080 \ --container-port 80

All parameters can be set via command-line flags, .nuke/parameters.json, .env file, or NUKE_* environment variables.

Example .nuke/parameters.json:

{ "$schema": "build.schema.json", "SiteTitle": "My Static Website", "SiteBaseUrl": "http://localhost:8080", "ImageName": "my-static-website", "VersionTag": "latest", "ContainerName": "my-static-website", "HostPort": 8080, "ContainerPort": 80 }

Add Markdown files to the input/ directory. Each .md file becomes an HTML page.

# Create a new blog post (dated) ./build.sh NewPost --title "My First Post" --tags "blog, intro" --author "Jane Doe" # Create a new page ./build.sh NewPage --title "About Us" # Initialize a fresh project structure ./build.sh Init

Add metadata at the top of your Markdown files:

--- title: "My Page Title" description: "A brief description for SEO and social sharing" author: "Your Name" date: "2024-09-13" keywords: "tag1, tag2, tag3" image: "./assets/my-image.webp" --- # Your Content Here

• Published — Default state; included in all builds
• Draft — Set draft: true; excluded unless --include-drafts is passed
• Scheduled — Set publishDate to a future date; excluded until that date
• Archived — Older content; built but excluded from navigation

Create translation files with a language suffix (e.g., about.fr.md):

--- title: "À propos" lang: "fr" translationOf: "about" --- Contenu en français...

Translations are output to output/{lang}/ subdirectories with automatic hreflang link generation.

Emoji — Use shortcodes like :smile:, :rocket:, :wave:

Mathematics — Inline: \( E = mc^2 \), Display: \[ x = \frac{-b \pm \sqrt{b^2-4ac}}{2a} \]

Code blocks — Use fenced code blocks with a language identifier:

```csharp Console.WriteLine("Hello!"); ```

Mermaid diagrams — Use mermaid as the language:

```mermaid graph TD;  A-->B;  A-->C; ```

Place images and other assets in input/assets/. They are copied to output/assets/ during build.

Run any target with:

./build.sh <TargetName> --site-base-url "..." --site-title "..."

The HTML template uses Scriban syntax. The active template is resolved from themes/{Theme}/template.html if a theme is set, otherwise template/template.html.

Themes are stored in themes/ with this structure:

themes/ ├── default/ # Default theme │ ├── template.html │ ├── theme.yaml │ ├── css/ │ └── js/ ├── docs/ # Documentation theme │ ├── template.html │ └── theme.yaml └── minimal/ # Minimal theme ├── template.html └── theme.yaml 

Select a theme with --theme <name>. If the theme directory doesn't exist, it falls back to template/.

• template/template.html — Main HTML template
• template/js/ — JavaScript files (theme switcher, Prism.js, modal)
• template/css/ — CSS files (Prism.js theme)

StaticWGen uses a lightweight nginx Alpine image to serve the generated static files.

# Build and deploy in one step ./build.sh DeployDockerImage \ --site-base-url "https://example.com" \ --site-title "My Site" \ --image-name my-site \ --version-tag 1.0.0 \ --container-name my-site \ --host-port 8080 \ --container-port 80

Or build the Docker image manually:

# Generate the site first ./build.sh BuildWebsite --site-base-url "https://example.com" --site-title "My Site" # Build and run docker build -t my-site . docker run -d -p 8080:80 --name my-site my-site

1. Fork the repository
2. Create a feature branch from dev
3. Make your changes
4. Ensure the build passes: ./build.sh BuildWebsite --site-base-url "http://localhost:8080" --site-title "Test"
5. Submit a pull request to dev

StaticWGen/ ├── build/ # NUKE build targets (C# interfaces) │ ├── Build.cs # Main build class │ ├── IHasWebsitePaths.cs # Shared paths and core parameters │ ├── IClean.cs # Clean target │ ├── IGenerateWebsite.cs # HTML generation │ ├── IGenerateBlogIndex.cs # Paginated blog index │ ├── IGenerateFeed.cs # Atom feed generation │ ├── IGenerateTagPages.cs # Tag page generation │ ├── IGenerateSearchIndex.cs # Search index generation │ ├── IGenerateBuildReport.cs # Build report generation │ ├── ISitemap.cs # Sitemap generation │ ├── IRobotsTxt.cs # robots.txt generation │ ├── IOptimizeImages.cs # Image optimization │ ├── IOptimizeOutput.cs # HTML minification & asset fingerprinting │ ├── IValidateConfig.cs # Configuration validation │ ├── IValidateOutput.cs # Output validation (HTML, a11y, SEO) │ ├── IWatch.cs # Development server with live reload │ ├── IScaffold.cs # Content scaffolding (NewPost, NewPage, Init) │ ├── ICompressOutput.cs # Output compression │ ├── IDockerOperations.cs # Docker build & deploy │ └── Helpers/ # Shared utilities ├── input/ # Markdown source files │ ├── assets/ # Static assets (images, etc.) │ └── *.md # Content pages ├── template/ # Legacy HTML template and assets │ ├── template.html # Scriban template │ ├── js/ # JavaScript files │ └── css/ # CSS files ├── themes/ # Theme variants │ ├── default/ # Default theme │ ├── docs/ # Documentation theme │ └── minimal/ # Minimal theme ├── src/ # Core library source code ├── tests/ # Test files ├── output/ # Generated site (git-ignored) ├── .github/workflows/ # CI/CD pipelines ├── .env.example # Environment variables template ├── Dockerfile # nginx deployment ├── nginx.conf # nginx configuration └── build.sh # Build entry point 

This project is licensed under the MIT License — see the LICENSE file for details.