Support for tags and categories

[atiq-cs]

I know the Statiq.Web supports tags well. I used to think it does not support categories. Supporting that didn't seem necessary to me. However, I saw some example input YAML files in a blog repo source recently where Category is being utilized.

For example,

Category: gaming
Tags:
  - VR

Makes me wonder whether statiq has built in support for categories as well?

[daveaglick]

The fun thing is that Statiq Web will support any classification data you want to add to your documents out of the box. In fact, Statiq Web doesn't actually know about tags either, that name is merely a convention that CleanBlog and future blogging-oriented themes will likely support.

The gotcha here is that because themes like CleanBlog don't necessarily know what to do with extra metadata like category, you're on the hook for rigging up some pages for them and exposing them in some way.

The first tool that will be useful here is Archives. An archive file creates both an index of items and a page-per-item with the documents that contain it. So for example, an archive document for category could render both your list of categories as well as the list of documents under each category. That may even be all you're looking for if you don't need to add category to the actual page for each post.

For example, here's the tags.cshtml file in the CleanBlog theme that powers the entire tags functionality in that theme:

ArchiveSources: => GetString("PostSources")
ArchiveFilter: => GetBool("IsPost")
ArchiveKey: Tags
ArchiveKeyComparer: => StringComparer.OrdinalIgnoreCase.ToConvertingEqualityComparer()
ArchiveDestination: >
  => GetInt("Index") <= 1 ? $"tags/{NormalizedPath.OptimizeFileName(GetString("GroupKey"))}/index.html" : $"tags/{NormalizedPath.OptimizeFileName(GetString("GroupKey"))}/{GetInt("Index")}.html"
ArchivePageSize: 10
ArchiveOrderKey: Published
ArchiveOrderDescending: true
Title: Tags
ArchiveTitle: => GetString("GroupKey")
---
@if (Document.ContainsKey(Keys.GroupKey))
{
    <div class="container-sm-height">
        <div class="row row-sm-height">
            <div class="col-md-6 right-border col-sm-height">
                @Html.Partial("/_posts.cshtml", Document)
            </div>
            <div class="col-md-4 mt-4 mt-md-0 col-sm-height">
                @foreach (IDocument tag in OutputPages.Get("tags.html").GetChildren().OrderByDescending(x => x.GetChildren().Count()))
                {
                    string badgeStyle = Document.GetString(Keys.GroupKey).Equals(tag.GetTitle(), StringComparison.OrdinalIgnoreCase) ? "badge-dark" : "badge-light";
                    string postCount = tag.GetChildren().Count().ToString();
                    <a href="@Context.GetLink(tag)" class="badge @badgeStyle"> @tag.GetTitle() (@postCount)</a>
                }
            </div>
        </div>
    </div>
}
else
{ 
    @foreach (IDocument tag in Document.GetChildren().OrderByDescending(x => x.GetChildren().Count()))
    {
        string postCount = tag.GetChildren().Count().ToString();
        <a role="button" href="@Context.GetLink(tag)" class="badge badge-light"> @tag.GetTitle() (@postCount)</a>
    }
}

As you can see, it's all about the archive metadata at the top of this file. That defines the particular metadata you want to generate archives for (I.e. category) and how those archives are generated, named, etc. Something very similar to this could power categories in your own site. You don't even need a new theme, just copy this into your input directory, name it categories.cshtml and tweak it. Hopefully this gets you on the right track?

[atiq-cs]

I don't really need categories. I am happy with tags. I was asking if it's already in clean blog or something supported out of the box right now that I don't know about. Good to know, @daveaglick Cheers!

[daveaglick]

Gotcha! In that case, hopefully the answer above helps the next person. There's all kinds of use cases for arbitrary, categorizable data like categories, authors, topics, locations, etc. Supporting any kind of categorizable data in any theme with a minimum of effort has been a key design goal. I.e. we can't know all the different ways someone might need to group stuff, so let's make it flexible enough to support anything.

[atiq-cs]

Thanks @daveaglick