What I'd like to see in Zine

I’ve used Zine extensively. It’s wonderful, but as a young static site generator I think there are a lot of ways it can improve. The most significant way I can help it improve is by cataloguing my experiences. As a consumer and regular user of Zine, I have pretty intimate knowledge of its strengths and limitations. This page documents any pain points, bugs, or missing features I’ve encountered with Zine.

No one reading this page should take this list as a discouraging sign that they shouldn’t use Zine themselves—anything but! Zine is already leaps and bounds ahead of my expectations for a static site generator, despite being in alpha. If you’re unfamiliar with the tool and want to understand why I’m so enthusastic about it, check Zine out for yourself!

Missing Features

Bugs

Pain Points

Runtime ids

TODO

The contentSection() function

The contentSections() SuperHTML function is currently a

fn contentSection (String) -> String

map. It should instead be a

fn contentSection (String) -> ContentSection

map.

The current fn contentSection (String) -> String signature poses serious problems. The first of these is that, if you ctrl-f the SuperHTML documentation for “contentSection”, you’ll see that there’s only a single way to acquire any object at all of type ContentSection in SuperHTML, and that’s with the contentSections() function. This function has signature fn contentSections () -> [ContentSection], and allows you to iterate over all ContentSections associated with a Page. Therefore, while there are plenty of times where you want to acquire a particular ContentSection, SuperHTML only allows you to either

  1. use contentSection('your-id-here') to get a huge string of auto-generated HTML from SuperMD, or
  2. use contentSections() in a <ctx> loop to find your desired ContentSection, like so:
<ctx :loop="$page.contentSections()">
    <ctx :if="$loop.id.eql('your-id-here')">
        // Do something with the `$loop` variable, which we know is our desired `ContentSection`.
    </ctx>
</ctx>

I think using a :loop like this is extremely bad practice. And this seems like exactly the use case that contentSection('your-id-here') should fill!

The examples show the current contentSection() function being used like this:

<div :html="$page.contentSection('section-id')"></div>
<div :html="$page.contentSection('other-section')"></div>

After this proposed change from a fn contentSection (String) -> String signature to a fn contentSection (String) -> ContentSection signature, the example would change to this:

<div :html="$page.contentSection('section-id').html()"></div>
<div :html="$page.contentSection('other-section').html()"></div>

There is a second (downstream) problem with the contentSection function, which is that I personally never want to use the auto-generated, header-included HTML produced by the html() function defined on a ContentSection type—I prefer much more fine-grained control over my layouts than that, and have exclusively used the htmlNoHeading() function as a result. I discuss this more in section TODO.

Miscellaneous missing documentation

Anything from the above sections that have since been fixed

This section will be filled with prior writeups from the above sections.