About

This page collects common use cases that people will encounter while creating a Zine site.

As time passes new use cases will emerge as common enough to be listed here, so you might want to check back from time to time when wondering how to implement something in Zine.

Table of Contents

RSS feed

Zine doesn’t have direct knowledge of RSS feeds but by combining a handful of its features you can add support for the most syndication formats commonly used.

In this example we’ll assume that we want to generate an RSS feed for a blog.

1. Define an alternative for the post listing page

Your blog should have a page that lists all posts. We’ll generate the RSS feed as an alternative version of it.

If you think about it, this is the semantically correct thing to do, since an RSS feed is an alternative version of a page that lists your posts.

posts.smd (in the frontmatter)

---
.alternatives = [{
  .name = "rss",
  .type = "application/rss+xml",
  .layout = "rss.xml",
  .output = "index.xml",
}],
---

2. Create the XML layout

SuperHTML doesn’t support XML officially yet, but there is enough support to generate correct feeds.

This is a RSS2.0 example but you can also do the same with Atom, if you prefer.

rss.xml

<rss version="2.0">
 <channel>
  <title>My blog</title>
  <link>https://site.com/</link>
  <description>Recent content</description>
  <generator>Zine -- https://zine-ssg.io</generator>
  <language>en-us</language>
  <lastBuildDate :text="$build.generated.formatHTTP()"></lastBuildDate>
  <ctx :loop="$page.subpages()">
   <item>
    <title :text="$loop.it.title"></title>
    <link :text="$site.host_url.addPath($loop.it.link())"></link>
    <pubDate :text="$loop.it.date.formatHTTP()"></pubDate>
    <guid :text="$site.host_url.addPath($loop.it.link())"></guid>
   </item>
  </ctx>
 </channel>
</rss>

3. Link to your RSS feed

In SuperMD

Same page:

[Follow my RSS feed]($link.alternative('rss'))

Different page (see the reference docs for more variations):

[Follow my RSS feed]($link.page('other/page').alternative('rss'))

In SuperHTML

<ctx alt="$page.alternative('rss')">
  <a href="$ctx.alt.link()" type="$ctx.alt.type">
    RSS feed
  </a>
</ctx>

Preserve old links

You’re porting your website to Zine but still want to make sure old links don’t break?

Use the aliases field in the page’s frontmatter to define a second copy (or more) of the page that can be placed at any location you’d like.

If your old site used so-called ugly URLs (i.e. foo.md would become foo.html instead of foo/index.html), then this is your only option since Zine has no support for ugly URLs at the moment.

Inline generated HTML content in a SuperMD document

The SuperMD docs show that you can inline HTML content in a SuperMD document by creating a =html code block:

```=hml
<h1>Hello</h1>
```

The SuperMD reference shows that among the assets that can be embedded in a document there’s also $code, which allows you to embed a source file like so:

[]($code.asset("foo.zig"))	

You can also specify the language of this code block by adding a call to language():

[]($code.asset("foo.zig").language("zig"))	

This SuperMD directive is the equivalent of embedding the contents of foo.zig into a codeblock in the document:

```zig
std.debug.print("hello world", .{});
```

You might see where we’re going with this: if you specify =html as the language, you can inline an HTML asset into your page.

[]($code.asset("my-generated-snippet.html").language("=html"))