ScissorHands.Web

ScissorHands.Web

ScissorHands.Web is the static site generation engine for ScissorHands.NET. It turns Markdown documents with YAML frontmatter into static HTML using Razor themes and optional content plugins.

Features

• Markdown posts/pages with frontmatter, tags, and hierarchical navigation
• Filename-based page reading order and automatic previous/next links
• Razor themes and optional content-processing plugins
• Configurable routes and static output for subpath hosting
• Local preview and a built-in light/dark theme

ScissorHands.NET currently targets .NET 10.

Quickstart

Create an empty ASP.NET Core application:

dotnet new web -n MyScissorHandsApp
cd MyScissorHandsApp
dotnet add package ScissorHands.Web --prerelease

Replace Program.cs with:

using ScissorHands.Web;

var app = new ScissorHandsApplicationBuilder(args).Build();
await app.RunAsync();

No theme component types need to be registered in Program.cs. The built-in theme is used when Site:Theme is default.

Add these sections to appsettings.json:

{
  "Site": {
    "Title": "My site",
    "Theme": "default",
    "SiteUrl": "https://example.com",
    "BaseUrl": "/"
  },
  "Plugins": []
}

Create contents/posts/hello.md:

---
title: Hello, ScissorHands
published: 2026-09-11
tags:
  - static-site
---

# Hello, ScissorHands

Write the post in Markdown.

Place pages under contents/pages/. Page navigation is opt-in through show_in_navigation: true; hiding a navigation link is not access control.

Page reading order

File-backed pages use filename order, with index.md first in each directory. The built-in theme renders automatic previous/next links for eligible pages; navigation grouping still follows slugs.

Renaming sources can change inferred URLs, so use explicit slugs to preserve existing addresses. See the reading order and navigation guide for traversal, eligibility, custom-loader behavior, and plugin snapshots.

Preview and build

Run from the application directory. Start the local preview server:

dotnet run -- --preview

Generate the static site into dist/:

dotnet run -- --build

Refresh the browser after preview regeneration. Razor/C# changes require recompilation. Use BaseUrl for subpath hosting.

vNext includes breaking plugin identity, theme-component, and page-route changes. Review the migration reference before upgrading.

Learn more

• vNext guides and reference (website handoff)
• vNext migration reference
• Documentation
• Source code
• Theme template
• Official plugins
• Issue tracker

License

ScissorHands.NET is licensed under the MIT License.

The built-in theme is adapted from PlainPage. See the third-party notices.