• Why the rename
• What's still here
• What's new since v7.0.0
• Get started

Why the rename

SuCoS — "Tastiest C# Static Site Generator of the World" — was a personal project from day one, built to get better at C# and to stop fighting Hugo's templating. Over nine major versions it grew Markdown extensions, sections and taxonomies, multi-language support with full i18n, ref/relref shortcodes, and a validate-links command that understands local versus production URLs. Somewhere along the way it quietly became the tool every other project reached for, MASS4's sites included. Fanstatic — for Fans of a Fantastic Static Site Generator — is that same tool, renamed to match what it actually is now: shared infrastructure, not a side project. New source home at github.com/MASS4ORG/fanstatic, still MIT licensed.

What's still here

Nothing was left behind in the move. Fanstatic v7.0.0 is the direct continuation of SuCoS v6.9.0, with the same CLI surface:

fanstatic new-site <YOUR_SITE_PATH>             # To create your site
fanstatic <YOUR_SITE_PATH>                      # To build your site
fanstatic serve <YOUR_SITE_PATH>                # To build and run locally
fanstatic validate-links <YOUR_SITE_PATH>       # To check all links
fanstatic api <YOUR_CODE_PATH> <YOUR_SITE_PATH> # To generate API reference

That includes Liquid templating, Hugo-style shortcodes, full i18n with per-language sections and translation strings, smart validate-links local-baseurl resolution, and — as of the last SuCoS release before the rename — a native Windows installer.

What's new since v7.0.0

The rename shipped alongside the work already in flight: v7.0.1 fixed the Windows installer placing fanstatic correctly on the user PATH, and v7.0.2 added a winget manifest, so Windows users can now install with:

winget install MASS4ORG.Fanstatic

Get started

Grab a release from github.com/MASS4ORG/fanstatic for Linux or Windows, or install via winget on Windows. Everything you already know from SuCoS applies — the docs on this site are the same docs, just living at a new address.

• Hugo-Style Shortcodes
• Smarter Link Validation

Hugo-Style Shortcodes

We've added native support for ref and relref shortcodes directly within your Markdown content. This allows you to resolve page permalinks dynamically without hardcoding URLs.

Check out our [About Page]({{< ref "path/to/page.md" >} }) for absolute links, 
or link relatively using [this section]({{< relref "path/to/page.md#anchor" >} }).

By default, the shortcodes automatically resolve using the calling page's language and output format context. However, you can explicitly override these when needed by appending lang="..." or outputFormat="..." parameters. It also fully supports #anchor fragment resolution out of the box.

Smarter Link Validation

The validate-links engine received a robust intelligence upgrade focused on local testing workflow and edge-case handling:

• Local BaseUrl Mapping: Absolute links containing your production domain (e.g., hardcoded production URLs) are now smart-resolved against your local site pages during testing instead of initiating actual external HTTP requests. If you prefer the legacy behavior, you can append the -b or --strict-baseurl flags to enforce exact domain-matching.
• Hash-Routed URL Fix: Fixed a routing bug where root-path external URLs using hashes (such as Matrix links like [https://matrix.to/#/!room:matrix.org](https://matrix.to/#/!room:matrix.org)) were mistakenly flagged as internal page hits. This previously triggered frustrating, false-positive fragmentNotFound errors on the home page.

Download It Now

View Changelog

• Hugo-Style Shortcodes
• Smarter Link Validation

Hugo-Style Shortcodes

We've added native support for ref and relref shortcodes directly within your Markdown content. This allows you to resolve page permalinks dynamically without hardcoding URLs.

Check out our [About Page]({{< ref "path/to/page.md" >} }) for absolute links, 
or link relatively using [this section]({{< relref "path/to/page.md#anchor" >} }).

By default, the shortcodes automatically resolve using the calling page's language and output format context. However, you can explicitly override these when needed by appending lang="..." or outputFormat="..." parameters. It also fully supports #anchor fragment resolution out of the box.

Smarter Link Validation

The validate-links engine received a robust intelligence upgrade focused on local testing workflow and edge-case handling:

• Local BaseUrl Mapping: Absolute links containing your production domain (e.g., hardcoded production URLs) are now smart-resolved against your local site pages during testing instead of initiating actual external HTTP requests. If you prefer the legacy behavior, you can append the -b or --strict-baseurl flags to enforce exact domain-matching.
• Hash-Routed URL Fix: Fixed a routing bug where root-path external URLs using hashes (such as Matrix links like [https://matrix.to/#/!room:matrix.org](https://matrix.to/#/!room:matrix.org)) were mistakenly flagged as internal page hits. This previously triggered frustrating, false-positive fragmentNotFound errors on the home page.

Download It Now

View Changelog

• Multi-Language Support
• Internationalization (i18n)
• Translation-Aware Templates
• Bug Fixes

Multi-Language Support

SuCoS now supports building sites in multiple languages. Configure your languages in the site settings:

languages:
  en:
    LanguageName: English
    Weight: 1
    Title: "My Site"
    IsDefault: true
  pt-br:
    LanguageName: "Português (Brasil)"
    Weight: 2
    Title: "Meu Site"

Content is mapped to languages through filename suffixes. Simply name your files with the language code (e.g., hello.pt-br.md) and SuCoS automatically associates them with the correct language. Non-default languages get language-prefixed URLs (/pt-br/hello/), while the default language keeps clean URLs by default. Set DefaultContentLanguageInSubdir: true to prefix all languages uniformly.

Auto-generated section and taxonomy pages are now created for every configured language, not just the default. If a directory has an _index.md only in English, SuCoS automatically synthesizes stubs for the other languages — no manual duplication required.

Internationalization (i18n)

Bring your templates to life in any language with the new i18n system. Create translation files in i18n/ directory:

# i18n/en.yaml
read_more:
  one: "Read more"
  other: "Read more"

posts:
  one: "{{ count }} post"
  other: "{{ count }} posts"

# i18n/pt-br.yaml
read_more:
  one: "Leia mais"
  other: "Leia mais"

posts:
  one: "{{ count }} post"
  other: "{{ count }} posts"

Use the i18n filter in your Liquid templates:

<a href="{{ page.RelPermalink }}">
  {{ "read_more" | i18n }}
</a>

Pluralization is fully supported via Hugo-compatible one/other keys. The value inside the translation uses {{ count }} as the placeholder:

{% assign count = site.RegularPages.size %}
<p>{{ "posts" | i18n: count }}</p>

If there is a single page, this renders 1 post; with ten pages, it renders 10 posts.

When a translation key is missing in the current language, SuCoS falls back to the default language automatically — so you can roll out translations incrementally.

Translation-Aware Templates

Building language switchers and cross-language navigation is now straightforward with new page properties:

• page.Translations — same-page content in other languages, perfect for language switchers
• page.AllTranslations — all translations including self, sorted by language weight
• page.TranslationsByLanguage — translations keyed by language code
• page.Variants — every representation across all languages and output formats
• page.AlternativeOutputFormats — output formats (HTML, RSS, JSON) for the same language
• page.IsDefaultLanguage — check if page is in the site's default language
• site.Languages — list of all configured language settings
• site.Language — the current language context for this output

Here's a complete language switcher:

{% if page.Translations.size > 0 %}
  <nav class="language-switcher">
    {% for t in page.Translations %}
      <a href="{{ t.RelPermalink }}" lang="{{ t.Language }}">
        {{ t.LanguageName }}
      </a>
    {% endfor %}
  </nav>
{% endif %}

Bug Fixes

This release also fixes several important issues:

• Section page parent references: Auto-generated section pages (directories without _index.md) now correctly inherit the section as parent instead of home, preventing URL collisions between identically-named files across directories.
• Resource URL generation: Fixed when RelPermalinkDir lacks a trailing slash (e.g., root /).
• Resource Name/Title rendering: Liquid template rendering now uses SiteInternal instead of the SiteOutput facade.
• Debian publishing: The .deb package is now correctly published to the generic package registry and attached as a release link.

Download It Now

View Changelog

• Binary Compression
• Debian/Ubuntu Support

Binary Compression

One of the biggest changes in this release is the introduction of executable compression. By enabling compression in our build pipeline, we've managed to reduce the output size of the SuCoS executable from approximately 100MB down to just 20MB.

This makes downloading and deploying SuCoS much faster, without sacrificing any of the performance you've come to expect.

Debian/Ubuntu Support

We are happy to announce that we are now officially generating .deb packages for every release! If you are on Debian, Ubuntu, or any derivative distribution, you can now install SuCoS using your favorite package manager.

This ensures that SuCoS is properly integrated into your system, making it easier to manage updates and dependencies.

Download It Now

View Changelog

• Template-Driven Pagination
• Built-in Sitemap Support
• Massive Performance Gains
• Improved Stability

Template-Driven Pagination

We've introduced a new, flexible way to handle pagination directly in your Liquid templates. With the new paginate filter, you can now decide exactly how and when to split your content.

{% assign sortedPages = site.AllRegularPages | sort: "Date" | reverse %}
{% assign pager = sortedPages | paginate: 10 %}

{% for page in pager.PageItems %}
  <h2><a href="{{ page.RelPermalink }}">{{ page.Title }}</a></h2>
{% endfor %}

{% render "partials/pagination.html", pager: pager %}

The new Pager record exposes everything you need: Count, Current, First, Last, Prev, Next, and more. Plus, we've included a built-in partials/pagination.html so you can get started instantly without writing a single line of pagination UI logic.

Built-in Sitemap Support

Keeping search engines happy is now easier than ever. SuCoS now includes a built-in sitemap.xml generator. By default, the home page will now also generate a sitemap using a built-in Liquid template.

To support this and other cross-format needs, we've added site.AllRegularPages, which provides a complete list of all HTML regular pages across all output formats. This is perfect for generating sitemaps, RSS feeds, or custom search indexes.

The template lookup has also been improved to be more specific, checking for format-specific paths like _default/sitemap.xml before falling back to generic templates. This ensures your sitemap looks exactly like a sitemap should, without interference from your standard list templates.

Massive Performance Gains

Performance is at the core of SuCoS, and v6.5.0 takes it to the next level. We've identified and eliminated several bottlenecks:

• Template Caching: Compiled Fluid templates are now cached, eliminating the biggest single overhead in the rendering pipeline.
• Content Caching: Markdig HTML rendering is now cached per page, preventing redundant processing during pagination.
• Optimized Internals: Core path handling and URL sanitization have been rewritten to avoid unnecessary allocations, and we've adopted FrozenDictionary for lightning-fast lookups.

These changes result in a much snappier experience, especially for sites with hundreds or thousands of pages.

Improved Stability

This release also fixes a long-standing issue in serve mode where certain file system events could trigger infinite site recreation. By reimplementing our file provider, we've made the development loop more reliable and responsive.

Download It Now

View Changelog

This release also includes a major version bump due to the upgrade to .NET 10.

• Embedded Pagination Footer
• Changelog Improvements
• Platform Update

Embedded Pagination Footer

Pagination footer is now embedded by default.

Previously, templates needed to explicitly include footer logic when working with paginated content. With this change, SuCoS provides a built-in default, reducing duplication and simplifying template setup.

This behavior is handled internally by the template engine, making pagination easier to use out of the box while still allowing customization when needed.

Changelog Improvements

The project now follows the Keep a Changelog 1.1.0 format.

This change standardizes how releases are documented, making it easier to track changes over time and compare versions.

Platform Update

SuCoS now targets .NET 10.

This update brings the usual performance improvements and ensures compatibility with the latest .NET ecosystem. As a result, this release is marked with a minor version bump.

Download It Now

View Changelog

• Pagination Fix

Pagination Fix

Pagination now slices content per page correctly.

In previous versions, paginated collections could end up duplicating or leaking items between pages due to incorrect slicing logic. This made navigation inconsistent and, in some cases, confusing for readers.

With this fix, each page receives its exact subset of content, preserving order and ensuring predictable behavior across the entire pagination pipeline.

This improvement touches core components such as Page, Pager, and Site, reinforcing the overall stability of paginated builds.

Download It Now

View Changelog

• Introducing API Documentation Generation
• Dependency Updates

Introducing API Documentation Generation

We're thrilled to introduce the brand new sucos api command - a game-changing feature that scans your C# projects and generates beautiful, comprehensive API documentation automatically. Say goodbye to complex DocFx configurations and hello to documentation that just works!

With a simple command:

sucos api --project <PATH>

SuCoS will analyze your C# project and create ready-to-publish documentation for all your public classes, records, enums, interfaces, and more. Every public member gets properly documented with clear, navigable output that integrates seamlessly with SuCoS's proven template system.

The sucos api command leverages the power of Roslyn analyzers to deeply understand your C# code structure. It automatically extracts:

• Classes and Records: Complete documentation including constructors, properties, and methods
• Interfaces: All method signatures and their purposes
• Enums: Every value with descriptions when available
• Namespaces: Organized hierarchically for easy navigation
• XML Documentation: Integrates seamlessly with your existing XML doc comments

The generated documentation follows SuCoS's familiar, easy-to-understand concepts. No need to learn complex new markup or configuration files - if you know SuCoS, you already know how to customize your API documentation.

Why Choose SuCoS API Over DocFx

While DocFx is powerful, it can be overwhelming with its complex configuration requirements and steep learning curve. SuCoS API takes a different approach:

• Zero Configuration: Point it at your project and go
• Familiar Templates: Use the same templating system you already know
• Consistent Styling: Matches your existing SuCoS site perfectly
• Simple Customization: Modify output using standard SuCoS concepts
• Fast Generation: Optimized for speed and efficiency

Want to see it in action? Check out our own API documentation at fanstatic.mass4.org/api - generated entirely with this new feature!

Dependency Updates

As part of our commitment to staying current with the .NET ecosystem, we've updated all dependencies to their latest versions as of June 5, 2025. These updates ensure optimal performance, security, and compatibility with the latest development tools and frameworks.

This comprehensive update includes improvements to our Liquid templating engine, YAML processing capabilities, and core .NET runtime optimizations that benefit every aspect of SuCoS operation.

The new API documentation feature represents a significant step forward in making developer documentation accessible and beautiful. Whether you're documenting a small library or a complex enterprise application, SuCoS v6.2.0 gives you the tools to create professional, navigable API documentation without the hassle.

Download It Now

View Changelog

• URL Handling Improvements
• Windows Path Fixes
• Code Quality Updates
• Dependency Updates

URL Handling Improvements

Following our URL handling overhaul in v6.0.0, we've made permalinks even more robust by using Uri internally. This change strengthens URL validation and manipulation, making the system more reliable across different deployment scenarios.

Windows Path Fixes

We've resolved several path handling issues on Windows systems. This fix ensures consistent behavior across all operating systems, particularly when dealing with path separators and absolute paths.

Code Quality Updates

We've made several internal improvements to enhance code maintainability:

• Increased code wrap width from 80 to 120 characters for better readability
• Refactored several methods to reduce cognitive complexity
• Improved internal documentation

These changes might not be immediately visible to users but contribute to a more maintainable codebase, making future feature development smoother.

Dependency Updates

As part of our ongoing commitment to security and performance, we've updated all dependencies to their latest versions as of January 22, 2025.

Download It Now

View Changelog

• Permalink Changes

Permalink Changes

The major change in this release is the inclusion of BaseURL in permalinks. This change provides more consistent URL handling across your site, especially when deploying to subdirectories or custom domains.

Previously, Permalink would return a URL relative to your site root. Now, it includes the BaseURL, giving you absolute URLs out of the box. For those who need the old behavior, we've kept it accessible via RelPermalink.

This change makes it easier to:

• Generate absolute URLs for social media cards
• Create proper RSS feeds
• Handle subdirectory deployments seamlessly

Migration Guide

If you're upgrading from v5, here's what you need to know:

1. Replace Permalink with RelPermalink where you need URLs relative to your site root
2. Keep using Permalink where you want absolute URLs (recommended for RSS feeds and social media cards)

Remember our previous URL handling improvements mentioned in v5.0.0? This change builds upon that foundation to provide even more robust URL management.

Download It Now

View Changelog

• .NET 9 Upgrade
• Output Formats
• Front Matter Separation
• Parsing Phase Optimization
• Dependency Updates

.NET 9 Upgrade

The most significant change in this release is our upgrade to .NET 9. The upgrade necessitated a bit of internal changes and is the primary reason for the major version increment.

Unlike many other project's strategy of waiting for Long-Term Support (LTS) releases, we're committed to using the latest .NET release. Why? Because Microsoft provides the same level of robustness and stability across all .NET versions. This approach ensures we're always leveraging the most recent performance improvements, language features, and runtime optimizations.

Output Formats

Remember when SuCoS could only generate HTML? Those days are gone!

We're introducing a game-changing feature: multiple output formats! Now, each content type can generate various file types beyond HTML. This means you can easily create:

• RSS Feeds
• Robot.txt files
• Sitemap XML

The templating system is now incredibly smart. You can create format-specific templates:

• single.html.liquid: HTML-only template
• single.xml.liquid: XML-only template
• single.liquid: A universal fallback

Imagine generating a blog RSS feed with just a few configuration lines. Pure magic!

Front Matter Separation

The old Front Matter was getting complex, so we split it up following the Single Responsibility Principle. Meet ContentClass – our new comprehensive content representation that combines:

• Front Matter (metadata)
• Actual Content
• File Metadata

Parsing Phase Optimization

Content Front Matter is now generated in a separate loop before page generation. This lays the groundwork for future enhancements, potentially allowing parsing without full page generation.

Dependency Updates

We've updated all dependencies to their latest versions as of December 2024. Notable updates include:

• Fluid.Core: 2.11.1 → 2.14.0
• YamlDotNet: 16.1.0 → 16.2.1
• Markdig: 0.37.0 → 0.38.0
• Microsoft Extensions packages: Updated to .NET 9 versions

A Note on CI/CD

Remember the trimming improvements we mentioned in v4.3.0? We've finally implemented the full build process optimization. GitLab CI/CD now creates even smaller, more efficient executables.

Breaking Changes

• Requires .NET 9 SDK (for devs only)
• Changes in Front Matter handling
• Most content will generate RSS by default

Let's keep evolving!

Download It Now

View Changelog

• Trimmed Executable: Smaller Footprint
• Updated Dependencies: Staying Current

Trimmed Executable: Smaller Footprint

One of the most exciting changes in this release is the significant reduction in the size of the SuCoS executable. We've managed to trim it down from about 80 MB to just 40 MB - that's a 50% reduction!

This impressive size reduction was achieved using dotnet publish trimming in partial mode. We opted for partial mode to keep some dependencies that can't work with full trimming untouched, which is why Native AOT is currently not possible for SuCoS. Interestingly, full trimming mode or Native AOT would have reduced the even more, but neither option was viable due to compatibility issues.

The smaller executable brings several benefits: faster downloads, quicker startup times, more efficient memory usage, and faster CI/CD executions. This optimization ensures you get all the power of SuCoS in a more compact and efficient package.

Updated Dependencies: Staying Current

To ensure that SuCoS continues to leverage the latest improvements and security updates from its underlying technologies, we've updated all dependencies to their latest versions as of August 2, 2024. Here's a quick overview of some key updates:

• Fluid.Core: 2.10.0 → 2.11.1
• FolkerKinzel.MimeTypes: 5.2.1 → 5.3.0
• Microsoft.NET.Build.Containers: 8.0.302 → 8.0.401
• Microsoft.NET.Test.Sdk: 17.10.0 → 17.11.0
• Serilog: 4.0.0 → 4.0.1
• Vecc.YamlDotNet.Analyzers.StaticGenerator: 15.1.2 → 16.0.0
• xunit.runner.visualstudio: 2.8.1 → 2.8.2
• YamlDotNet: 15.3.0 → 16.1.0

These updates include the latest .NET runtime improvements, an updated Liquid templating engine, and other third-party libraries used in SuCoS. By keeping our dependencies current, we ensure that SuCoS remains secure, efficient, and compatible with the broader ecosystem.

Happy site generating!

Download It Now

View Changelog

• Cascading Front Matter
• New sucos Variable for Templates

Cascading Front Matter

In an effort to make site configuration more efficient, we've introduced the cascade feature in the front matter. This new feature allows you to propagate settings to the content's children, reducing the need for repetitive configuration.

Here's an example of how to use the cascade feature:

---
Title: Blog
Cascade:
    Weight: 1
    Draft: true
    Params:
        subtitle: "article"
---

In this example, the Weight, Draft, and subtitle properties will be inherited by all children of the "Blog" section. This feature is particularly useful when you want to apply consistent settings across multiple pages without having to define them individually.

New sucos Variable for Templates

We've added a new sucos variable for templates, which contains useful information about your site and the SuCoS. The sucos variable includes the following properties:

• IsServer: Indicates whether the site is being served by the SuCoS server.
• DotNetVersion: The version of the .NET runtime being used by SuCoS.
• Version: The version of the SuCoS.
• BuildDate: The build date of the SuCoS.

You can use these properties in your templates to display relevant information or conditionally render content based on the environment.

For example, you can display the SuCoS version in the footer of your site using the following Liquid code:

Powered by SuCoS {{ sucos.Version }}

Download It Now

Commits

• Extended Theming with New Liquid Templates
• Case-Insensitive YAML Front Matter and Site Settings

Extended Theming with New Liquid Templates

We've added two new Liquid templates, term.liquid and taxonomy.liquid, to further extend the list of available templates for theming. If these templates are missing, they will default to list.liquid. These new templates provide you with more flexibility and control when customizing the look and feel of your taxonomy and term pages.

term.liquid is used to customize the appearance of a single term page, such as a tag or category. You can now access term-specific data and tailor the layout to better suit the content.

taxonomy.liquid is used to customize the appearance of a taxonomy listing page, such as a list of all tags or categories. This template allows you to create a unique layout for each taxonomy type, making it easier for users to navigate and find the content they're looking for.

Case-Insensitive YAML Front Matter and Site Settings

In our ongoing efforts to improve usability, we've made YAML front matter and site settings case-insensitive. This change will make it easier for you to configure your site and reduce the potential for errors.

Previously, the YAML front matter and site settings were only valid if they used CamelCase to match the C# class properties counterparts. For example, to set the site title, you would need to use Title in your YAML configuration:

---
Title: My Page
---

With the new case-insensitive feature, you can now use any case when defining your YAML front matter and site settings. The following examples are now all valid and will correctly set the site title:

---
title: My Page 1
---

---
TITLE: My Page 1
---

---
tiTle: My Page 1
---

This change applies to all properties in the sucos.yaml and any content page.

Notice: in case of repeating values, the last one will prevail.

---
title: My Page 1
TITLE: My Page 2
tiTle: My Page 3 # This one will be used since it's the last
---

Download It Now

Commits

• JetBrains Rider and Qodana Optimizations
• Server Crash on Constant File Changes

JetBrains Rider and Qodana Optimizations

We are excited to announce that JetBrains has kindly provided us with a license for their powerful C# IDE, Rider, and their static code analyzer, Qodana. This has allowed us to dive deep into our codebase and optimize it for even better performance.

Server Crash on Constant File Changes

Ever noticed that the app would sometimes crash when you were rapidly making changes to a content file? We've tracked down the issue and it turns out that each file change was triggering a duplicate server reload, eventually overwhelming the app. But worry no more - we've fixed this bug, and your rapid-fire edits should now be smooth sailing.

Stay tuned for more exciting updates in the near future!

Download It Now

• Human-Friendly Changelog

Human-Friendly Changelog

We understand that reading through raw git logs can be a daunting task, so we've taken the time to create a changelog that's both human and machine-readable. This new changelog is handcrafted by our team to provide you with a clear and concise overview of each update. We hope you find it helpful!

Download It Now

• Breaking Changes
• ReadyToRun
• Multiple themes
• new theme terminal command
• Fixes
• Internal Organization

Breaking Changes

Due to the ReadyToRun and Multiple themes features, there are some changes that users must be aware when upgrading their sites. More on that later.

Features

ReadyToRun

Recent DotNet versions allow a hybrid approach between compiled vs JIT compilation. It is called ReadyToRun. It tries to optimize the code converting some into native code and also make some inferences about the JIT optimizations.

The main advantage is speed. It will probably be about 2 times faster. It will also pave the way to further attempt to complete AOT compilation #35 , which would bring even more speed and smaller size. However, it required some changes, specially in the YAML parser, because it needed to avoid Reflection.

BREAKING CHANGE: all page and site settings (YAML) that are not de default variables will be ignored. Only custom data present under Params: will be kept into your pages. Before, unknown values were automatically placed under Params, even if placed elsewhere.

Multiple themes

SuCoS now allow sites to install multiple themes (but still only use one). They will be placed inside a themes/ folder (or overwriting it using ThemeDir variable in the site settings sucus.yaml). It will also allow using nested git repositories and splitting the theme into other remote repositories.

BREAKING CHANGE: until now, the theme data was supposed to be placed in theme/ folder. Now, one must create a themes/ folder and put the theme data into a folder within it, like themes/my-theme

new theme terminal command

You can now scaffold the theme structure using the new SuCoS new theme command. It will -still- not populate with any generic theme, but it's the plan for the future.

CODE_OF_CONDUCT and CONTRIBUTING

The source code now has CODE_OF_CONDUCT and CONTRIBUTING documents. The first state the expected conduct for everything in the project, from users or maintainers. Respect, tolerance and a bit o humor are a must. The second contains instructions on ways to start contributing and making changes for yourself. Further instructions are in developer section of this site.

Fixes

404 page Exception

When using live server, if the 404 page is hit (non-existing page), the server was raising an exception and crashing.

Return 0 (success) for help and version

when calling SuCoS version or SuCoS help terminal commands, it was crashing.

Internal Organization

Some changes in the code that do not change the behavior of the app.

• Nuke build project is now merged inside .nuke
• All app commands are placed in Commands folder
• Updated dependencies and libraries
• Fixes and enhancements in code comments and code style

Download It Now

• Version Bump 3
• Create a Site via Terminal
• Lighter Container Images
• Check Your Links

Version Bump 3

As I've mentioned in the v2.2.0 post, I forgot to mark the release as breaking change. It was so impactful that I was not able to even update this very site. Now I've decided to mark as a new version, signalling the need of changes of any client site.

Create a Site via Terminal

SuCoS newsite -o <PATH> will create a simple blank site.

Lighter Container Images

Using containers to build your site is one of many usages of the program. GitLab, GitHub, Netlify and Cloudflare allow specifying the site builder.

The base image will impact in the speed that the provider will download it to build your site. It was never a big size but it exposes the software to potential vulnerabilities.

The new images (now using both Microsoft modified Ubuntu and Alpine) are smaller and have less stuff into them. Win-win. For those that are using the latest, nothing changes.

Check Your Links (Beta)

It's now possible to check all the links of your site using the checklinks command. There are flags to check only internal or external links and to skip any given URL that are problematic. It's useful for the build process, making sure that your site is all valid.

Download It Now

Hold onto your hats, folks! It's time to celebrate a major milestone - our very own Static Site Generator (SSG) built with C# has officially turned one! As we blow out the candles and sing "Happy Birthday," let's take a moment to reflect on the wild ride that our SSG has been on since its inception on April 1st, 2023.

Our SSG was born out of a desire to test and improve my C# skills, as well as a growing frustration with the template system used by Hugo, a popular SSG built with Golang. I wanted to create a solution that addressed a problem that I was personally facing. And so, the idea of our SSG was conceived!

Present

When it came to choosing a template system for our SSG, I opted for Liquid templates. Their popularity and user-friendly nature made them an ideal choice for our SSG. They provided the flexibility and ease of use that I was looking for, making it a perfect fit for our SSG.

As for performance, DotNet (6, 7, and now, 8) has been instrumental in making our SSG the powerhouse that it is today. The C# team's continued efforts to enhance the performance of DotNet have made it a viable option for performance-critical programs. This has significantly improved the speed and efficiency of our SSG, making it a reliable choice for developers.

As mostly a one-man project, the use of AI was a very important motivator for diving into unknown territory. ChatGPT, Copilot, Bard, Gemini, and Mistral were mainly used to generate test suites, analyze and suggest optimizations in the code, and suggest libraries that might help.

Future

While our SSG has come a long way in its first year, there's still work to be done. In the coming months, I plan to implement key features such as pagination, multi-language, and image manipulation and conversion. My "ultimate" goal is to port my personal blog to our SSG, and I'm confident that these improvements will make that possible.

My wife thought it was an April Fool's joke when I started our SSG. But here we are, a year later, celebrating the first birthday of a project that has grown beyond my wildest dreams. It's been a year of learning, growth, and innovation, and I can't wait to see what the future holds for our SSG.

Here are some of the highlights:

• Build Command as Default and Source as Argument
• Elegant Crashes

Build Command as Default and Source as Argument

Now the build command is implicit. Also, the --source option is now an argument, so one can call either build or serve and then the path directly. As before, the default is to assume the current path (./). The usage of --source or -s is still possible and will take precedent, for compatibility’s sake.

Now you can build a site just by calling SuCoS.

Elegant Crashes

When something goes wrong in the build or serve processes (and it most definitively, will), the program crashes. Well, we are not fixing anything here, but at least print the sh*t in a very delicate manner!

Download It Now

Download It Now

Anyway, let's try to summarize:

2.2.1

• Bundle pages
• Other 2.2.1 changes

Bundle pages

You have three bundle types:

• Branch (also called page bundles): content with filenames as index.md or _image.md. They are the hub and all other files in the folder will be considered as its resources.
• Leaf: other markdown content in a folder

content/
├── post/
    ├── my-article/
        ├── index.md          // Leaf bundle
        ├── image1.png        // Page resources
    ├──  articles-list/
        ├── _index.md         // Branch bundle
        ├── content2.md       // Page resources
        ├── another-article/
            ├── index.md      // Leaf bundle
            ├── image2.png    // Page resources

Resources

Resources can be accessed and printed in the templates:

<li>
{% for resource in page.Resources %}
  <ul><a href="{{ resource.Permalink }}">{{ resource.Title }} (FileName: {{ resource.FileName }})</a></ul>
{% endfor %}
</li>

Resources Definition

You can set the title of the resources and rename the assets directly on the front matter metadata.

ResourceDefinitions:
- src: '*specs.pdf'
  title: 'Specification #{{counter}}'
- src: '*.pdf'
  name: "pdf-file-{{counter}}"
- src: '*.jpg'
  name: "{{title}}-{{counter}}"
  title: "{{title}}-{{counter}}"

The results would be:

Other 2.2.1 changes

• We're replacing the outdated Microsoft.AspNetCore, that is going to be deprecated, with System.Net for the live server.
• We've updated some key packages:
  • Fluid.Core* from 2.4.0 to 2.5.0
  • Markdig* from 0.31.0 to 0.33.0
  • Microsoft.NET.Test.Sdk* from to 17.7.2
  • Nuke.Common* from 7.0.2 to 7.0.6
  • Serilog* from 3.0.0 to 3.0.1
  • YamlDotNet* from 13.1.0 to 13.7.1
• For smoother unit testing and URL generation, we're making sure everything uses Unix path style, especially when dealing with code that relies on paths.

Warning

Despite not being marked as a BREAKING CHANGE, it includes a breaking change.

Despite not being marked as a BREAKING CHANGE, it includes a breaking change.

Intro

Due to a familiar problem, the death of (from 3) my dog Mage Merlin, I've basically stopped everything I was developing for weeks. I'm still managing to resume all the stuff. I was working in a feature of Page Resources (embed pictures, PDFs, videos, etc.) into pages. It was incomplete, but I decided to publish the WIP, so users might get any potential new feature.

• Feature: Page Bundles
• Version Merlin

Feature: Page Bundles

Each page can have extra content, like image files, video, audio, PDF, and even other markdown pages. They are called page Resources. It's available on Bundle pages (see the 2.2.1 post).

Version Merlin

I dedicate this release to my 4-pawns son, Mago Merlin Harigaya Massa 🐕. RIP my boy.

Here are some of the highlights:

• Page Drafts
• Site is now a top variable

Page Drafts

Pages now have a Draft variable that can be used to signal content that is still under development. This can be useful for keeping track of work in progress, or for sharing drafts with others for feedback.

To create a draft page, simply add the Draft variable to the front matter of the page. For example:

---
Title: My Draft Page
Draft: true
---

Still writing...

You can then use the --draft or -d command line argument to serve the draft page.

Site is now a top variable

The site variable is now exposed as a top-level variable, so you can access it directly in your templates. This makes it easier to access site-wide variables, such as the title or description.

For example, you could use the site.Title variable to display the site title in your header.

<div>
  <h1>{{ site.Title }}</h1>
</div>

We hope you enjoy the new features in v2.1.0!

Let's dive right in and explore these thrilling additions and enhancements:

• Redefining the 'Pages' and 'Front Matter' Concept
• Discover the Power of Plain Content and Word Count
• Boost Your SEO with Site Description and Copyright
• Taking Control with Forced Expired Pages
• Shifting Gears: Everything is Now Internal
• Power-Packed Performance Enhancements
• Raising the Bar with Improved Test Coverage

Redefining the 'Pages' and 'Front Matter' Concept

Our vision has always been a website abundant with vibrant pages. Previously, these pages sprung from markdown with front matter. But we've realized that our code's class Frontmatter was donning many hats, including handling content metadata and calculated properties.

Time for a paradigm shift! Let's call a spade a spade. Front matter will solely parse from content, while Page ascends as the principal entity. We've cleared the clutter by removing an internal "page-lite" class in favor of front matter. Yes, even the system-generated pages like tags now employ front matter to shape the full page.

This reinvention might disrupt compatibility from previous ABI, thus flagged as Breaking Changes and boosting the major version to the groundbreaking 2.

Discover the Power of Plain Content and Word Count

In a nod to all future literary prodigies, our Pages now can bare it all – outputting the text in its raw, untarnished form, free from the confines of HTML and markdown tags. To bask in this authenticity in your template, simply use {{ page.Plain }}.

Also, say hello to the new word count functionality, powered by {{ page.WordCount }}.

As like any other page variable, they are case-sensitive.

Boost Your SEO with Site Description and Copyright

Fine-tune your sucos.yaml to include Description and Copyright information, making your website even more enticing to SEO algorithms. Implement these in your templates with {{ page.Site.Description }} and {{ page.Site.Copyright }}.

Taking Control with Forced Expired Pages

By default, SuCoS smartly sidesteps pages marked with a past ExpiredDate yaml tag. However, we believe in giving you control. Override this feature by simply setting the -e or -expired flag in the command line.

Shifting Gears: Everything is Now Internal

In our relentless quest to maximize security and performance, we've transitioned most of the code from public to internal. In the C# universe, this means that while our code remains internally visible, it isn't exposed to the public. The only outlier here is our testing suite, which needs access to do its thing – testing!

Power-Packed Performance Enhancements

We've introduced a multitude of optimizations, mainly avoiding thread locking, to serve you a robust, performance-oriented system. Enjoy a smoother, faster experience!

Raising the Bar with Improved Test Coverage

We've pushed the test coverage envelope to now encompass 63%+ of the code, ensuring it stands strong even in rare scenarios. A slew of testing sites has been set up to simulate a wide variety of these scenarios. But wait, there's more to come! Stay tuned.

In this blog post, we're giving you the full tour of what's new, what's enhanced, and what's completely reimagined. Let's dive right in and see what v1.3.0 has in store!

Thrilling Changes on Deck:

• Page Weight
• Page IsHome IsPage IsSection
• Page Parent
• Theme Static Folder
• Build Default Output Folder
• Test Coverage Report

Page Weight

You've asked and we've listened. Pages are now empowering users to set a Weight value for a finer degree of sorting control. Keep things light with the default zero, or ramp it up to sort your pages just how you like.

Page IsHome IsPage IsSection

To make your templates that much more intuitive, we're offering extra calculated values:

{{ page.IsHome }} is your trusty indicator for the home page.

{{ page.IsPage }} stands tall when the page is of the Kind.single variety.

{{ page.IsSection }} raises its flag for Section type pages.

Feel the pulse of your page with these new identity markers!

Page Parent

Family ties matter, even for pages. While scanning for content files, we now set the previously created page as the Parent. This allows templates to roam freely through parsed content, just as they wish.

Witness this new feature in action with the new URL default, pairing the title of the parent page with the current page title.

Theme Static Folder

Themes just got a shiny new toy - a folder labeled static! Now, you can stow away unique files like logos and CSS files directly within the theme. And don't worry, the site's own static files will take precedence if available.

Build Default Output Folder

When usingSuCoS build -s /path/of/site, the default output, sans -output/-o was nestled in ./public. But we know you deserve better. Now, it will default to /path/of/site/public, a more intuitive and logical choice.

Test Coverage Report

As we ramp up our unit testing efforts, the desire for a coverage report becomes more pressing. Rejoice, because both internal GitLab and external reports are now automatically whipped up after each test. Stay on top of your game with these up-to-the-minute updates! For now, the coverage is about 40%.

By a twist of citrusy fate, we're using a zesty fruit-inspired font: Lemon Milk, a refreshing creation by the incredibly talented MARSNEV. This font was just the ripe pick for us, with its perfectly round 'O' that snugly nestles our badge, like a berry in a basket! The only tiny sour note? It doesn't offer lowercase, but hey, it's all about embracing the charm of uppercase, isn't it?

Gone are the days of the faded outer ring color. We've injected a fresh squeeze of the vivid yellow from the inside, creating a sunlit aura as if a burst of tropical juice is splashing out!

Our SuCoS project now sports a full logo and badge, holding within it the essence of a refreshing cup of assorted fruit juices.

Curious about the secret juice blend our logo symbolizes? Brace yourself for a delightful cocktail of flavors we've just stirred up:

• Succulent kiwis
• Unforgettable berries
• Crisp grapes
• Opulent oranges
• Spectacular tangerines

Isn't this a feast for your senses?

Experience the taste of SuCoS in this fresh new logo that promises to make your visual journey with us a joyful ride!

A minor misstep led us to inadvertently christen one of the internal tweaks as a new feature, thus birthing the latest minor version, instead of 1.1.1. Just a slip on the dance floor, nothing to lose sleep over.

Here's the latest playbill:

• Automated Tests
• Lazy Pages List
• Code Reorganization

Automated Tests

Your trusted assistant, SuCoS, is now harnessing the power of automated tests, acting upon every commit and release. With an eye for both the everyday and the peculiar, these tests aim to scour every nook and cranny of the code.

Although we're just dipping our toes in the world of testing, we're already executing around 60 tests, covering roughly 30% of SuCoS's labyrinthine code. We've christened this proportion of the code eventually executed during testing as Coverage.

Our ambitions soar to:

• A legion of hundreds, billions of tests
• Ensuring at least 75% of the code is under the protective umbrella of Coverage
• Embracing the Test-Driven Development ethos

TDD

TDD or Test-Driven Development, is a fine art of code crafting. It's akin to crafting a treasure map, where the tests that the new feature must conquer are delineated before even a single line of actual code is written.

Although, it's not always the star of the show during early stages due to the dynamic dance of prototyping. And I must confess, this method and I have an ongoing love-hate relationship.

Lazy Pages List

A pivotal shift occurred in the site and page .Pages list in the previous versions - they morphed into a dictionary indexed by URL. This evolutionary step wielded a significant edge during site parsing as it could quickly summon a given content using its permalink.

However, the flip side of using dictionaries within the Liquid template presented a hefty challenge, leading us to use the dictionary covertly and only conjure a list when the situation calls for it. This tactical switch ensured a swift process while preserving the simplicity of use.

Code Reorganization

Once upon a time, we had a factory class (BaseGeneratorCommand) for creating Site and Front Matter that had a bit of a growth spurt. When the Automated Tests spotlight hit this class, it was clear: it was juggling too many roles.

Our fix? We moved parts of Site and FrontMatter creation into their own hands. This meant a slight growth spurt for these classes, the BaseGeneratorCommand class underwent a pleasing slimming-down procedure.

Our next act? More tests and a return to the wonderland of new features!

• Markdown Extras
• Params
• URL with Liquid tokens
• Content URL Aliases
• Content Date, PublishDate, ExpiryDate and LastMod
• Section Pages

Let's take a closer look at these updates!

Markdown Extras

The power of Markdig, our reliable Markdown parser, just got an upgrade! Now, its default setting includes all built-in extensions. This means you can now create tables, citations, figures, mathematical formulas, auto-links, and more with ease and precision.

For example, to create a simple table, use the following format:

| Header 1 | Header 2 |
| -------- | -------- |
| Row 1    | Row 2    |

will become:

Params

The Params feature allows all site and page YAML values without matching attributes in the FrontMatter or Site classes to be placed in a dictionary Params. This opens the door for using custom fields in your templates. Here's how you can do it:

Create your content as shown below:

---
Title: My Page
MyCustomValue: HELLO
---

This is the *Markdown* content.

And use the custom value in your template:

<!-- It will create <span>HELLO</span> -->
<span>{{ page.Params.MyCustomValue }}</span>

URL with Liquid tokens

We've added a feature that enables Content URL fields to be parsed as a mini Liquid template. This means you can now use other content values, like title, path, or tags, to generate unique URLs. This feature provides a more efficient and dynamic URL creation process.

---
Title: My Page
Type: page
URL: "{{ page.Type }}/{{ page.Title }}" # it will become "/page/my-page"
---

This is the *Markdown* content.

Content URL Aliases

This feature allows content to have multiple URLs pointing to the same page. It's particularly useful when you're transitioning from legacy or old URLs or when you're generating small bitly-like alternatives. Like regular URLs, aliases can also use tokens.

For example, define your aliases in the content file:

---
Title: My Page
Aliases:
  - /legacy-url
  - /short-url
  - "{{ page.Type }}/{{ page.Title }}"
---

This is the *Markdown* content.

Content Date, PublishDate, ExpiryDate and LastMod

We've added support for these four date fields in the content front matter. Now, you can easily manage your content's publish and expiry dates, as well as track their last modification.

-f/--Future command line option

We have introduced a new build and serve command line option to include posts from the future (Date or PublishDate values later than the current time). This is particularly handy when you want to preview posts that will be displayed at a later time.

As we continue to improve SuCoS, we appreciate your feedback on these new features. Please feel free to share your thoughts and experiences as you explore SuCoS

Section pages

The very first folder inside content defines each content's Section. Pages, blog, tags... Now SuCoS automatically creates a page for each section. So you can now use ht<span>tp://</span>example.com /blog to get a list of all blog posts, by default.

SuCoS, crafted entirely in C# like its spirited sibling Docfx, is lovingly crafted entirely in C#. It aspires to be a feature-rich wonderland, drawing inspiration from the ever-popular Hugo. This charming tool is poised to help developers and users alike embark on a whimsical journey of content creation and website building.

Now, dear readers, let's address the number we've bestowed upon this pre-release version. SuCoS v1.0.0 is but a humble number, not to be confused with production readiness. We pledge to embrace semantic versioning, with new releases shimmering into existence every week. Our commitment to progress and improvement knows no bounds!

Now, let's take a moment to soak in the majesty of SuCoS, as we delve into some of its captivating features:

• Astonishing Performance: With SuCoS, even when handling a whopping 100k pages, it takes less than a millisecond per page. Blink, and you'll miss it! Who knew that website load times could be this electrifying?
• Dynamic Live Server: Say goodbye to manual refreshing! With the "SuCoS serve" feature, you gain a real-time server for easy prototyping and content writing. Making edits has never felt this invigorating!
• Theming: Want your website to dazzle with personality? SuCoS uses the super easy-to-use Liquid template system, allowing you to paint your sites with your personal style.
• Never-ending Updates: We believe in sharing our progress with you! There's no holding back on features and fixes - we bring them to you on a weekly basis.

Though SuCoS may still be polishing its armor for the grand showdown of production readiness, it is already a welcoming haven for adventurous souls ready to embark on this pre-release exploration. Developers and users, join forces! Let's voyage through the depths of this evolving tool together, unveiling its hidden gems and endless potential.

We warmly invite you to accompany us on this magical journey, where sparks of imagination ignite and static websites burst into life. As we continue to perfect SuCoS, turning it into a commanding knight of the web, we're eager to hear your feedback, suggestions, and tales of victory.

• GitLab: https://gitlab.com/sucos/sucos
• Mastodon @SuCoS
• Twitter @SuCoS_SSG (similar to Mastodon, but not free)
• Matrix #SuCoS:matrix.org
• Discord SuCoS Channel (similar to Matrix, but not free)

So, dear readers, buckle up and prepare for a magical ride with SuCoS that's on the brink of greatness. Together, we'll illuminate the web and create digital wonders that will leave a lasting impression.

Squeeze Your Ideas, Sweeten the Web!