2023-10-19
After some weeks of development hiatus after the sad passing of my dog Mage Merlin, I'm back developing my juice. 2.2.0 was supposed to be 3.0.0 due the disrupting changes for the page resources. I hope anyone using the system found their way.
Anyway, let's try to summarize:
2.2.0 Mage Merlin
2.2.1
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 bellow).
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 it's 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:
| Resource file |
Name |
Title |
| checklist.pdf |
"pdf-file-1.pdf |
"checklist.pdf" |
| guide.pdf |
"pdf-file-2.pdf |
"guide.pdf" |
| other_specs.pdf |
"pdf-file-3.pdf |
"Specification #1" |
| photo_specs.pdf |
"pdf-file-4.pdf |
"Specification #2" |
| my-photo.jpg |
"posttitle-5.jpg |
"posttitle-5.jpg" |
| my-kids.jpg |
"posttitle-5.jpg |
"posttitle-5.jpg" |
Chore: Removing deprecated Microsoft.AspNetCore
We're replacing the outdated Microsoft.AspNetCore, that is going to be deprecated, with System.Net for the live server.
Chore: Update packages
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
Fix: Force unix path style
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.
2023-07-20
New version live. Simple but it's moving forward! That what matters.
Here are some of the highlights:
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!
2023-07-13
We're absolutely ecstatic to present to you the fresh-off-the-software-press v2.0.0 release of our platform! This isn't just a bump in the version number or some behind-the-scenes tinkering. No, my friends, this is a revolution for writers and website creators alike, ready to charge up your creative engines!
Let's dive right in and explore these thrilling additions and enhancements:
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!
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.
2023-07-13
We're absolutely ecstatic to present to you the fresh-off-the-software-press v2.0.0 release of our platform! This isn't just a bump in the version number or some behind-the-scenes tinkering. No, my friends, this is a revolution for writers and website creators alike, ready to charge up your creative engines!
Let's dive right in and explore these thrilling additions and enhancements:
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!
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.
2023-07-06
Hello, tech enthusiasts and loyal users! We're beyond thrilled to unveil the latest sensation in our feature lineup - the v1.3.0 release. Buckle up, because we're about to embark on a journey through some impressive upgrades that are sure to spark your curiosity and streamline your user experience. We've focused on your feedback, rolled up our sleeves, and delivered functionalities that add finesse and flexibility to your tech endeavors.
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
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%.
2023-06-29
Welcome to our latest production, the v1.2.0 release! We've been busy squashing some bugs and fine-tuning the gears beneath the surface.
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
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!
2023-06-22
We are thrilled to announce the latest release of SuCoS, v1.1.0. The first automated weekly release. This version comes chock-full of new features that will significantly improve your user experience and streamline your content management process. The primary features introduced include:
Let's take a closer look at these updates!
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:
| Header 1 |
Header 2 |
| Row 1 |
Row 2 |
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.
Important: SuCoS now ignore content that have Date or PublishDate set in the future, as well ExpiryDate that is earlier than the current time. Use the Future command to include them
-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 https://example.com/blog to get a list of all blog posts, by default.
2023-06-15
Greetings, fellow web enthusiasts and explorers of the digital frontier! Today, we have the great pleasure of unveiling an extraordinary tool that will leave you spellbound and filled with wonder. Allow us to introduce SuCoS!
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.
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!