Congelato 1.5.1

Congelato

Razor based static site generator

Requirements

Congelato targets .NET 10 and requires the .NET 10 SDK and the .NET 10 ASP.NET Core shared framework to build or run. The Congelato.Core.Models package remains compatible with netstandard2.0 for extension assemblies.

Build project

Build and pack the tool from the repository root:

dotnet build Congelato.App\Congelato.App.csproj --configuration Release
dotnet pack Congelato.App\Congelato.App.csproj --configuration Release --no-build

The package is written to nupkg. Install it from that local package source using an isolated tool path:

dotnet tool install congelato --tool-path .tools --add-source .\nupkg --version 1.4.0

To remove the isolated installation:

dotnet tool uninstall congelato --tool-path .tools

The tool package targets net10.0 and uses the .NET 10 ASP.NET Core shared framework for Razor runtime types. The tool and dynamically compiled Razor assemblies require the .NET 10 runtime and ASP.NET Core shared framework. The standalone Razor project-engine APIs used to compile templates remain on the latest separately published Razor compiler packages. Extension assemblies should reference Congelato.Core.Models, preferably targeting netstandard2.0 or another framework compatible with .NET 10.

Running the tool

The command-line arguments are:

• -i: input directory
• -o: output directory
• -c: site configuration file
• -a: comma-separated list of assemblies to add to the build

After installing the tool, check the available options or run it with your site directories and configuration:

.\.tools\congelato.exe --help
.\.tools\congelato.exe -i _stevenpearsdev -o stevenpearsdev -c _tshapeddev.yml -a newfeature.dll

When a Razor template reports an error, the message includes the source location and the surrounding lines (when available), with the failing line marked by >.

Site structure

Congelato tries to run similar to other site generators so that it's easy to transfer.

So from the input directory it expects a structure like this

inputDir
  _posts
  _pages
  _layouts

all other files and directories are copied as-is

Site Config

The site configuration is a YAML file inside the input directory. Pass its filename with -c when running Congelato; for example, -i input -c site.yml loads input/site.yml. If -c is omitted, Congelato looks for _config.yml in the input directory.

The config supports url, title, and description fields, plus a data mapping for additional string values:

url: https://example.com
title: Example Site
description: A short description of the site
data:
  owner: Example Author
  theme: light

Page structure

Pages, posts, and layouts can start with a YAML front matter block. Put --- on a line by itself before the YAML fields, then another --- on its own line to end the block. The page's HTML or template content must come after this closing delimiter; anything after it is treated as the page content.

Pages support these front matter fields:

• title: the page title
• description: a description of the page
• layout: the layout to use, matching a layout's name
• data: a mapping of additional string values for the page

For example:

---
title: About
description: A little about this site
layout: default
data:
  section: about
---
<h1>About</h1>
<p>Page content goes here.</p>

Layouts

Layouts can be nested - everything after the yaml block at the top is the .NET template, so using statements go after the yaml, not at the very top.

As a base layout or page - the next piece of content in the chain is always rendered by the statement @await Content()

An example layout:

---
layout: default
---
<%
using AddedAssemblyNamespace;
%>
<div class="container">
    <div class="row">
      <div class="col-lg-8 col-md-10 mx-auto">
        @await Content()
      </div>
    </div>
  </div>

  <hr>

Posts

posts are a similar thing with most popular config options applied, they also have the data element for other information. If posts have a markdown extension they will be converted to HTML for you

example post

---
title: Introducing Alexa.NET - Screencasts
date: 2019-12-30T12:22:00
author: Steven Pears
layout: post
permalink: /2019/12/30/introducing-alexa-net-screencasts
tags:
  - alexa
  - video
  - 'c#'
---
So I got a request on [Twitter](https://twitter.com) from a user ...