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.
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.
SuCoS v6.2.0 is here with an exciting new feature that transforms how you generate API documentation! This release introduces a powerful new command that makes creating comprehensive API docs as simple as running a single command.
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.
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.
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:
Replace Permalink with RelPermalink where you need URLs relative to your site root
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.
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.
We're thrilled to announce the release of SuCoS v4.3.0! This update brings significant improvements in terms of efficiency and performance, making your experience even better.
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!
Method
Size
Before
~80 MB
After
~40 MB
Trimming Full
~30 MB
Native AOT
~25 MB
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:
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.
We're excited to announce the release of SuCoS v4.2.0! This version introduces powerful new features that will streamline your static site generation process and provide more control over your site's configuration.
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:
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:
We're thrilled to announce the release of SuCoS v4.1.0! This version brings exciting new features and improvements that will enhance your static site generation experience.
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
---
From a user's perspective, this might seem like a simple release, but don't be fooled! We've been hard at work behind the scenes to bring you significant improvements in both speed and stability.
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!