v0.18.0 - Tag Page Generation

This release introduces tag page generation, an experimental feature that automatically generates archive pages for blog posts organized by tag.

What's New

Tag Page Generation (Experimental)

vss can now automatically generate tag pages that list all posts with a specific tag. This is useful for organizing content by topic or category.

Note: This feature is experimental and may undergo breaking changes in future releases.

Getting Started

1. Enable Tags in Configuration

Add the tag configuration to your vss.toml:

[build.tags]
enable = true
template = "tags/default.html"
url_pattern = "/tags/{tag}/"

enable: Set to true to enable tag page generation
template: Path to the template file (relative to layouts/)
url_pattern: URL pattern for generated tag pages (use {tag} as placeholder)

2. Add Tags to Posts

Add tags to your post's front matter:

---
title: "My Post"
description: "Post description"
tags: ["python", "tutorial"]
---

3. Create Tag Template

Create a template at layouts/tags/default.html to control how tag pages are rendered:

<!DOCTYPE html>
<html>
<head>
    <title>Posts tagged "{{tag_name}}"</title>
</head>
<body>
    <h1>Posts tagged "{{tag_name}}"</h1>
    <ul>
        {{#posts}}
        <li><a href="{{url}}">{{title}}</a></li>
        {{/posts}}
    </ul>
</body>
</html>

Template Variables

The tag template has access to the following variables:

site_title: Your site title
site_description: Your site description
tag_name: The current tag name
posts: Array of posts with this tag
- {{#posts}}...{{/posts}}: Loop through posts
- {{title}}: Post title
- {{description}}: Post description
- {{url}}: Post URL
- {{pub_datetime}}: Publication date
- {{author}}: Post author (if set)
has_tags: Boolean indicating if tags are enabled

Example

If you have posts tagged with "rust", vss will automatically generate a page at /tags/rust/ listing all posts with that tag.

Files Generated

For each unique tag used in your posts, vss generates:

dist/tags/{tag}/index.html

Limitations and Notes

Tag pages are generated at build time
Tag names are case-sensitive
Empty tags or tags on unpublished posts are not included
Tag URLs are generated based on the url_pattern setting

Future Changes

This feature is marked as experimental. Future versions may introduce:

Tag cloud or weighted tag display
Tag filtering and combination
Custom tag ordering
Tag metadata and descriptions

For more information, see the CHANGELOG.