Static Site Generation Pipeline

The static site generation pipeline in MyLittleContentEngine transforms your Blazor application into a collection of pre-rendered HTML files. This process is orchestrated by the OutputGenerationService.GenerateStaticPages method, which coordinates multiple subsystems to produce a complete static website.

Overview of the Generation Process

The static generation pipeline follows a carefully orchestrated sequence of operations:

  1. 1

    Page Collection and Discovery

    The pipeline begins by collecting all pages that need to be generated from multiple sources:

    Content Service Pages

    Each registered IContentService (such as MarkdownContentService or ApiReferenceContentService) contributes pages based on their content sources. For example:

    • Markdown files become individual pages
    • API documentation generates namespace and type pages
    • Custom content services can add specialized pages

    Route Discovery

    The system automatically discovers routes from two sources:

    Blazor Component Routes

    When AddPagesWithoutParameters is enabled, the RoutesHelperService scans assemblies for Blazor components with @page directives. This discovers routes like:

    • @page "/about" becomes /about/index.html
    • @page "/contact" becomes /contact/index.html

    Only non-parameterized routes are included (routes without {parameter} segments).

    MapGet Endpoints

    The system also discovers HTTP GET endpoints registered via app.MapGet(). These are assigned Priority.MustBeLast because they often include dynamically generated content like CSS files that depend on other pages being processed first. This includes generating the MonorailCSS stylesheet if it's been registered.

    Explicit Pages

    Additionally, pages can be explicitly defined in configuration through the PagesToGenerate option.

  2. 2

    Output Directory Preparation

    Before generation begins, the output directory is completely cleared and recreated. This ensures a clean slate for each generation run, preventing stale files from previous builds.

  3. 3

    Static Asset Collection and Copying

    The pipeline collects and copies all static assets from multiple sources:

    Web Root Assets

    Standard wwwroot files from the main application are automatically included.

    Razor Class Library Assets

    Static assets from referenced Razor Class Libraries are automatically included. This includes scripts.js from the MyLittleContentEngine.UI library, which is essential for the UI functionality.

    Content Engine Assets

    Custom content directories registered via MapContentEngineStaticAssets are included with their assets mapped to specific request paths.

    Content Service Assets

    Individual content services can contribute their own static assets through the GetContentToCopyAsync method.

    All collected assets are then copied to the output directory, respecting the IgnoredPathsOnContentCopy configuration.

  4. 4

    Page Generation with Priority Ordering

    Pages are generated in priority order to handle dependencies correctly. The system uses three priority levels:

    • MustBeFirst (0): Pages that other pages might depend on
    • Normal (50): Standard content pages
    • MustBeLast (100): Pages that depend on other pages (like CSS files that need to scan generated HTML)

    Within each priority level, pages are generated in parallel for optimal performance.

    Page Rendering Process

    Each page is rendered by making an HTTP request to the running Blazor application. The rendered HTML is then saved to the appropriate location in the output directory, with directories created as needed.

Previous
Next