pauldangerkile/blazorstatic

Embrace the capabilities of Blazor on .NET 8 to craft static websites.

Blazor Static

Transform your Blazor app into a static site generator.

Embrace the capabilities of Blazor on .NET 8 to craft static websites.

How to start:

BlazorStatic is a small library designed for integration into Blazor applications. Here are a few straightforward methods to get started:

Fork or clone BlazorStaticMinimalBlog

RECOMMENDED STARTING POINT: BlazorStaticMinimalBlog offers a quick and convenient way to deploy your site within minutes.

Build from Scratch

Begin by creating a Blazor application, then proceed to add content and integrate BlazorStatic. Comprehensive instructions are available here. This approach will help you build a project akin to BlazorStaticMinimalBlog and is beneficial for understanding the inner workings of BlazorStatic.

Using dotnet new blazorStatic

Ideally, this command would set up your project automatically. However, this feature is currently a significant TODO awaiting implementation.

How it works? What it does?

BlazorStatic:

• Generates static HTML files by running the app and fetching page HTML with HttpClient

  • Use the following in your app::

  app.UseBlog<FrontMatter>(); //processes markdown files, adds blog and tags pages
  app.UseBlazorStaticGenerator(shutdownApp: !app.Environment.IsDevelopment());

  • shutdownApp is essential for CI/CD pipelines to prevent indefinite running.

• Automates the discovery of pages to generate by scanning for the @page directive in Razor files. It targets only non-parametrized pages (e.g., @page "/mypage", not @page "/mypage/{param}").

• Enables adding additional pages for generation using

  builder.Services.AddBlazorStaticService(opt => {
    opt.PagesToGenerate.Add(new($"/mypage/paramValue", "paramValue.html"))
  }); 

  Example here for adding docs pages.

• Simplifies blog post generation from markdown files, respecting a specified folder structure:

  builder.Services.AddBlogService<FrontMatter>(opt => {
      opt.BlogPageUrl = "blog"; //default value
      opt.PostFilePattern = "*.md"; //default value
      opt.ContentPath = Path.Combine("Content", "Blog"); //default path
      opt.MediaFolderRelativeToContentPath = "media"; //default folder
  });

• Provides FrontMatter class for parsing blog post metadata.

• Allows for custom IFrontMatter implementations to suit various markdown (front matter) formats.

• Facilitates copying necessary files to the output folder:

  builder.Services.AddBlazorStaticService(opt => {
     opt.OutputFolderPath = "output";//root of the output 
     //wwwroot and _content are copied by default
     opt.IgnoredPathsOnContentCopy.AddRange(new[] { "app.css" }); //don't copy app.css
  }); 

• Offers flexibility in CSS frameworks and themes, without locking you into a specific choice. TailwindCSS is used in the default theme, but it's fully customizable. Open to suggestions and contributions for design improvements (do it, I am not the right person).

• Easy deployment: run your app in a CI/CD pipeline and deploy the generated files to platforms like GitHub Pages, Azure Static Web Apps, Netlify, etc. See the pipline for a minimal blog setup or check the deployment guide for more details

Samples

Description	Source	Live
Page about BlazorStatic (this repo contains the code itself)	source	live
Minimal blog	source	live
Zodoc - image processing and deep learning sample	source	live
❓ Add your page here!!!

Contributions

Contributions are highly encouraged and appreciated. If you find something missing, unclear, or encounter an issue with the code, I warmly welcome your input. Feel free to:

• Create a new issue or submit a PR.
• Contact me directly for any queries or suggestions.
• Ask questions or start a discussion on the Blazor Community Discord server.