Blazorade.StaticPages 1.0.0

Blazorade Static Pages

Blazorade Static Pages is a library for generating crawler-visible static HTML from ordinary Blazor WebAssembly applications at build time. It works with standard Blazor routing, layouts, navigation, and components, allowing the generated static output to be enhanced with normal Blazor interactivity at runtime.

The application remains the source of truth. Static pages are declared with a source-analysis attribute and marker components:

Read Adding static page generation to Blazor WebAssembly for an introduction to using the library.

• StaticPageAttribute identifies a static page and controls sitemap and RSS inclusion.
• StaticMetadata defines the page metadata used for generated HTML, optional JSON-LD structured data, and optional live browser rendering.
• StaticContent exposes a safe static representation from a reusable component.
• InteractiveContent excludes runtime-only content from generated HTML while leaving it available to the running application.

The package also integrates the static-page generator into the consuming application's build and publish process. Generated output can include static HTML pages, canonical metadata, sitemap entries, RSS feeds, and static-hosting route configuration.

Static pages are generated by analyzing the consuming application's Razor source at build time. The generator does not execute the application, use HtmlRenderer, or depend on runtime render markers. StaticMetadata.RenderInBrowser controls whether metadata is emitted during live browser rendering; static analysis includes metadata regardless of that setting.

Getting started

Add the Blazorade.StaticPages package to a Blazor WebAssembly application. Declare static content in a routable component:

@page "/products"

@attribute [StaticPage]

<StaticMetadata Title="Products" Description="Explore our products." />

<StaticContent>
    <h1>Products</h1>
    <p>Browse our product catalogue.</p>

    <InteractiveContent>
        <ProductConfigurator />
    </InteractiveContent>
</StaticContent>

The optional DatePublished parameter accepts a value parseable as a DateTimeOffset:

<StaticMetadata Title="Products" DatePublished="2026-05-10T14:30:00+02:00" />

<StaticContent>
  <h1>Products</h1>
</StaticContent>

Values without a time-zone offset are interpreted as UTC. The generated page contains a concise article:published_time value and a date-only <meta name="date"> value. Invalid date values produce a build warning and are omitted from the generated metadata.

The optional DateModified parameter accepts a value parseable as a DateTimeOffset and represents the genuine modification date of the page:

<StaticMetadata
  Title="Products"
  DatePublished="2026-05-10T14:30:00+02:00"
  DateModified="2026-09-13T10:15:00+02:00" />

When supplied, the modification date is emitted as article:modified_time, dateModified in Article JSON-LD, sitemap <lastmod>, and RSS Atom <atom:updated> metadata. Invalid values produce a build warning and are omitted. The original publication date remains in DatePublished and RSS pubDate.

Set SchemaType to WebPage or Article to generate equivalent JSON-LD in live and static output. SchemaType="Article" also produces og:type="article"; other pages produce og:type="website". Page and author entities receive stable, host-independent @id values based on their URL paths so structured-data consumers can identify the same entities across staging, production, and other hosting environments. The optional AuthorUrl, Keywords, and CopyrightNotice parameters populate the corresponding Schema.org properties. CopyrightNotice can contain the copyright year and holder:

<StaticMetadata
  Title="Products"
  Description="Explore our products."
  SchemaType="WebPage"
  Author="Mika Berglund"
  AuthorUrl="https://www.example.com/about"
  Keywords="products, catalogue"
  CopyrightNotice="Copyright 2026 Example" />

Relative author and image URLs require staticPages.siteUrl so the generated JSON-LD can use absolute URLs. Article additionally emits headline from Title.

For reusable components, place the static representation inside StaticContent. Runtime-only descendants should be placed inside InteractiveContent.

To configure the public site URL used for canonical URLs, sitemap generation, and RSS links, add blazorade.config.json next to the consuming application's project file:

{
  "staticPages": {
    "siteUrl": "https://www.example.com"
  }
}

Configuration-specific overrides are supported using the active MSBuild configuration. For example, blazorade.config.Release.json overrides blazorade.config.json for Release builds, and custom configurations such as Pre-Prod use blazorade.config.Pre-Prod.json. The files are merged recursively, with values from the configuration-specific file taking precedence.

RSS generation is enabled by default whenever the staticPages section is present. The generated feed is available at /feed by default, and generated HTML pages advertise it with an RSS discovery link. To disable RSS generation, set staticPages.rss.enabled to false:

{
  "staticPages": {
    "siteUrl": "https://www.example.com",
    "rss": {
      "enabled": false
    }
  }
}

The RSS feed includes dated static pages by default, ordered newest first. Individual pages can be excluded with IncludeInRss = false on StaticPageAttribute. When feed content is included, relative article links and image sources are resolved to absolute URLs using the configured site URL.

Navigation fallback is disabled by default. Set staticPages.navigationFallback to true to rewrite unmatched navigation requests to /index.html. An application-owned static 404 page can be configured with staticPages.notFoundPage, relative to the application's wwwroot; the generated Static Web Apps configuration then serves it with HTTP status 404. Set staticPages.noIndex to true to emit a noindex, nofollow directive in generated HTML; it defaults to false.

Static page selection and compile-time values

Only routable components marked with @attribute [StaticPage] are included in static page generation. Each static routable component must contain exactly one StaticMetadata component. Other routable components remain normal interactive Blazor pages and are ignored by the generator. It is valid for an application to have no static pages.

The Title and other static page metadata values must be resolvable at build time. String constants and string-initialized variables can be declared in the Razor component's @code block or in its matching .razor.cs code-behind file:

@page "/"

@code {
  private const string Title = "My site";
}

@attribute [StaticPage]

<StaticMetadata Title="@Title" />

<StaticContent>
  <PageTitle>@Title</PageTitle>
  <h1>@Title</h1>
</StaticContent>

Compile-time Razor expressions used in HTML attribute values are resolved during static generation.

The generator does not execute application code. Values that depend on services, lifecycle methods, property getters, authentication state, or other runtime data cannot be used as static metadata or content.

Release notes

v1.0.0

• The static-page generation contract has now stabilized after the preview and RC releases. The library provides a predictable build-time path from ordinary Blazor WebAssembly components to crawler-visible static HTML while preserving normal runtime interactivity.
• The stable release consolidates the metadata, structured-data, sitemap, RSS, routing, configuration, and build-integration capabilities developed during the prerelease period into the first supported 1.0.0 API.

Release candidates

• Added <main> and <title> elements when the application template or static content does not provide them.
• Added JSON-LD structured-data generation for live and generated pages, including WebPage and Article schema types, authors, author URLs, keywords, copyright notices, and stable host-independent entity identifiers.
• Added default-enabled RSS 2.0 feed generation with metadata, Atom self-link validation, RSS discovery links, absolute article links and image sources, Static Web Apps routing, and stale feed cleanup.
• Added live metadata cleanup and PageTitle handling to prevent duplicate or stale metadata during client-side navigation.
• Added host-independent JSON-LD identifiers so staging and production resolve to the same page and author entities.
• Added compile-time Razor expression support for static metadata and content, including image URLs in generated HTML and RSS content.
• Added Static Web Apps navigation fallback configuration, application-owned static 404 pages with preserved HTTP 404 responses, and opt-in staticPages.noIndex support.
• Added og:type="article" for pages with SchemaType="Article".
• Added optional StaticMetadata.DateModified support for live and generated metadata, Article JSON-LD, sitemap <lastmod>, and RSS Atom <atom:updated> values.
• Renamed StaticMetadata.Date to DatePublished as the finalized publication-date API for the stable release.

Preview releases

Versions v1.0.0-preview.1 through v1.0.0-preview.13 established the initial static-page generation contract and build integration:

• Added StaticPageAttribute, StaticMetadata, StaticContent, and InteractiveContent for explicitly declaring static page output.
• Added source-only Razor analysis and deterministic compile-time value resolution without executing application code or runtime rendering.
• Added static page discovery and HTML generation for Blazor WebAssembly applications, including metadata, canonical URLs, sitemap generation, and static-hosting route configuration.
• Added support for compile-time constants, variables, qualified references, string concatenation, parenthesized expressions, and supported date values in static content and metadata.
• Added build-configuration-specific configuration files with recursive merging over the default configuration.
• Added optional live metadata rendering through StaticMetadata.RenderInBrowser while keeping generated output independent of browser state.
• Added automatic generator and generator-host rebuilding and NuGet packaging under tools/net10.0.