Examples of static site generation

[gortok]

I’ve been looking through the source of statiqdev.github.io and am trying to wrap my head around how it all comes together; the documentation is great from an API perspective, but I am missing the connection to turn those API calls into something I can use.

In my case, I have a blog-like need for static generation and was looking for a way to have an autogenerated index.html that includes links to all the output files I’ve generated with a title and a blurb.

How do I do thAt using statiq.web?

[daveaglick]

The key here is to understand a little about the way Statiq builds on itself:

• Statiq Framework is a collection of simple building blocks like modules, think of it like a bunch of individual LEGO bricks.
• Statiq Web adds some more exotic LEGO bricks and includes a few neat components (like archives) built with the bricks from Framework, but still isn't an entire thing.

We're missing a critical part at the level above both Statiq Framework and Statiq Web. We need to be able to take those bricks and turn them into an actual structure. We're missing the instructions. We're missing a theme.

The idea here is that while Statiq Web is designed to build your site, it's totally unopinionated about what your site actually is. It doesn't inherently know the first thing about blogs, documentation, shopping carts, or any kind of other site. It needs instructions on how to compose the various parts provided in Statiq Web into a site. That's what a theme does: provide some conventions (where the files go, what metadata to set) and instructions (archives, feeds, etc.) that glue together the content and data you provide with a layout and the capabilities of Statiq Web.

Now it's entirely possible to do all this yourself, that's kind of the whole point of an unopinionated static site generator. You don't have to use a theme, but it's a whole lot easier if you do. Or at a minimum if you have a theme that does roughly what you're trying to do to use as a reference.

Which is where the work I'm doing right this second comes in! My current Statiq work has been focused on shipping two initial themes, both focused on blogging:

• CleanBlog which is an adaptation of https://github.com/StartBootstrap/startbootstrap-clean-blog (a similar theme existed in Wyam).
• Canvas which will incorporate blogging conventions and Statiq Web features like archives and feeds without any of the layout or style assets so you can use it as a starting point for your own theme or add your assets and layouts directly.

CleanBlog is coming along well, though I'm finding little nits with Statiq Web and Statiq Framework as I go (you can see these in my most recent commits to those two repos). My best advise right now is to sit tight for like 2 more days while I get CleanBlog to a decent state and then use it as an example: https://github.com/statiqdev/CleanBlog.

[stijnherreman]

I've been keeping an eye on Wyam/Statiq for a couple years now, waiting for it to mature, especially on the documentation side.
Have you been able to make any progress on that?

Personally I'm looking for something between the API documentation, and a full-fledged blog theme. Just a few content pages with dummy text, a straight-forward navigation menu, and some basic styling. That would be ideal for getting started, and then people can accustomed to the API on their own pace.

[mattsmith13815]

I've only been playing with Statiq for about a week (So awesome! @daveaglick ) but this was my approach to autogenerate an index.html file that includes links to all the subfiles. I'm not super great with C# and there may be other ways but this worked for me.

• Create a new folder, name it whatever, I used "News" as an example.
• Copy your content files into this folder, I have multiple markdown files - each file needs to have Title: & Summary:
• Create two files: _news-item.cshtml & index.cshtml
• Copy the below code into the index.cshtml
• Run the program and check the output/News folder for your html files

---
Title: My News Page
Summary:  Read our latest stories.
Meta Description: Read our latest stories.
---
@model IDocument

@foreach (IDocument post in Model.GetChildren())
{
    /*blank file but this function generates sub-pages*/
    @Html.Partial("_news-item.cshtml", post)
    
    /*get strings from .md files*/
    string title = post.GetString("Title"); 
    string summary = post.GetString("Summary");

    /*get file details to build url*/
    string baseFile = post.GetLink();
    string url = baseFile + ".html";

    /*output list with title, summary and links*/
    <li><a href="@url">@title</a>
        <p>@summary ...<a href="@url">Read More</a></p>
    </li>
}

[mattsmith13815]

This code sample has stopped working starting with 1.0.0-beta.3+. Reverting back to beta.2 produces the page as expected. Newer versions, the page loop is rendered empty.

[daveaglick]

Thanks for catching that - it's a result of breaking changes to the way GetChildren() works (see https://github.com/statiqdev/Statiq.Framework/releases/tag/v1.0.0-beta.20). I'm trying hard to keep breaks to a minimum knowing more and more folks are onboarding, but I felt this one was necessary to reduce a huge bit of confusion around the concept of "children" and how they relate to the output document hierarchy.

The sample should now be something like:

---
Title: My News Page
Summary:  Read our latest stories.
Meta Description: Read our latest stories.
---
@model IDocument

@foreach (IDocument post in Outputs.GetChildrenOf(Model))
{
    /*blank file but this function generates sub-pages*/
    @Html.Partial("_news-item.cshtml", post)
    
    /*get strings from .md files*/
    string title = post.GetString("Title"); 
    string summary = post.GetString("Summary");

    /*get file details to build url*/
    string baseFile = post.GetLink();
    string url = baseFile + ".html";

    /*output list with title, summary and links*/
    <li><a href="@url">@title</a>
        <p>@summary ...<a href="@url">Read More</a></p>
    </li>
}

Notice the change from Model.GetChildren() to Outputs.GetChildrenOf(Model). The idea here is that "children" in the file tree sense aren't really children of the document itself - they're children as it relates to the overall Output collection. Documents can themselves have children that are different than this, so you can see where it would be confusing if sometimes IDocumentGetChildren() were based on file tree but sometimes not.

Anyway, hopefully that works - let me know if it doesn't, I just fixed it up from memory so might have gotten some little detail wrong.

[mattsmith13815]

@daveaglick - thank you for the super quick response, that resolved the issue within the foreach loop however it also appears that the GetLink() function now returns differently? Actually I feel like it returns the exact file name from input but this does invalidate the sample above. Here's what I am seeing:

• input/News/news item name.md (spaces are contained in file name)
• output/news-item-name.html (replaces space with -) - good!
• Link Result: news item name.md.html (GetLink() returns the exact input file name but doesn't point to or match the output file)

Philosophically a GetLink() function sounds like it should "get the link to the file as its intended to be, in its final location". Another part of me though sees the value in passing the exact file name... Do we have a GetFile() function or concept verses a GetLink()?