tag specific description/data for a tag "series" listing page

[thedamon]

I want some of my tags to have their own homepages, in a sense to make the tag a 'series' with a root homepage that links to the list of pages containing that tag (i am thinking i want to limit this to the tag property so i can easily change my mind about if a tag should constitute a 'series').

I have tag pages automatically set up based on this tip, but I'm not sure how to add content to that page

I'm imagining a 'tags' folder with files named after the tag in question, then import that path directly into my tags.njk page
I'm just not really sure how to grab that data from the page in an elegant way.

I guess I'm also curious about the general idea of providing metadata to "collection list" pages (ie tag#1 is reverse chronological, tag#2 content has different metadata to pull into its listing page etc)

Are there any other patterns for doing something like this?

[pdehaan]

@thedamon Since you said you want "some of my tags to have their own homepages", I randomly went with a global data file which controls which tags are a series and holds their descriptions, etc.

https://github.com/pdehaan/11ty-3033#readme

src/_data/series.js

module.exports = [
  {name: "cat", description: "this is something about a cat."},
  {name: "dog", description: "this is a sentence about how dogs are better than cats."},
  {name: "bird", description: "birds are lousy pets."},
];

src/_tags.njk

Then, in my template, I just paginate over that array if valid series tags and generate the pages:

---
pagination:
  data: series
  size: 1
  alias: tag
permalink: "/tags/{{ tag.name | slugify }}/"
---

<header>
  <h1>{{ tag.name }}</h1>
  <p>{{ tag.description }}</p>
</header>

<section data-count="{{ collections[tag.name] | length }}">
  {% for p in collections[tag.name] %}
  <article>
    <h1>{{ p.data.title }}</h1>
    <a href="{{ p.url }}">More&hellip;</a>
  </article>
  {% endfor %}
</section>

OUTPUT

> eleventy

[11ty] Writing www/tags/cat/index.html from ./src/pages/_tags.njk
[11ty] Writing www/tags/dog/index.html from ./src/pages/_tags.njk
[11ty] Writing www/tags/bird/index.html from ./src/pages/_tags.njk
[11ty] Writing www/pages/six/index.html from ./src/pages/six.njk
[11ty] Writing www/pages/five/index.html from ./src/pages/five.njk
[11ty] Writing www/pages/four/index.html from ./src/pages/four.njk
[11ty] Writing www/pages/three/index.html from ./src/pages/three.njk
[11ty] Writing www/pages/one/index.html from ./src/pages/one.njk
[11ty] Writing www/pages/two/index.html from ./src/pages/two.njk
[11ty] Wrote 9 files in 0.05 seconds (v2.0.1)

And my generated www/tags/cat.html file looks like this (since I had two files which had tags: ["cat", ...]):

<header>
  <h1>cat</h1>
  <p>this is something about a cat.</p>
</header>

<section data-count="2">
  
  <article>
    <h1>Four</h1>
    <a href="/pages/four/">More&hellip;</a>
  </article>
  
  <article>
    <h1>One</h1>
    <a href="/pages/one/">More&hellip;</a>
  </article>
  
</section>

I didn't have anything tagged with "bird", so thats a mostly empty page; although I'm sure it could be tweaked to not generate the page if there are zero posts for that series [using permalink: false or something]:

<header>
  <h1>bird</h1>
  <p>birds are lousy pets.</p>
</header>

<section data-count="0">
</section>

[thedamon]

This helps a lot, thank you! I think a data object like that will give me a great way of controlling a lot of the functionality I'm looking for :). One thing I'm not sure about though, is some of these have much longer "intro" content.. like a short article, maybe with images, or at least several paragraphs. I was thinking of putting those into .md files named after the tag in a specific directory.. but is there a way to import that file into the tags.njk? (or maybe a better way of approaching the problem)

[pdehaan]

Sounds like you want longer and more complex than multiline YAML content... In that case, I might drop a bunch of .md files in your ./src/_includes dir and name them after the tags and then use something like this with the EleventyRenderPlugin plugin:

{%- set pages = collections[tag.name] -%}
{%- set desc = "./src/_includes/" + tag.name + ".md" -%}

<header>
  <h1>{{ tag.name }}</h1>
  <div>{% renderFile desc %}</div>
</header>

And my ./src/_includes/dog.md file looks like this work of genius:

# DOGS

Dogs are rad.

They have fur and sometimes shed, but they poop outside.

![](/imgs/dog.webp)

And my updated eleventy.config.js has these tweaks:

+const { EleventyRenderPlugin } = require("@11ty/eleventy");

/**
 * @param {import("@11ty/eleventy/src/UserConfig")} eleventyConfig
 * @returns {ReturnType<import("@11ty/eleventy/src/defaultConfig")>}
 */
module.exports = function (eleventyConfig) {
+  eleventyConfig.addPlugin(EleventyRenderPlugin);

  return {
    dir: {
      input: "src",
      output: "www",
    }
  };
};

[pdehaan]

Or if you'd rather use a custom async shortcode (if you want some data processing), this might do the job:

const { EleventyRenderPlugin } = require("@11ty/eleventy");

/**
 * @param {import("@11ty/eleventy/src/UserConfig")} eleventyConfig
 * @returns {ReturnType<import("@11ty/eleventy/src/defaultConfig")>}
 */
module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(EleventyRenderPlugin);

  eleventyConfig.addAsyncShortcode("tag_md", function (name, kwargs) {
    return eleventyConfig.javascriptFunctions.renderFile(`./src/_includes/${name}.md`, kwargs);
  });

  ...
};

<section>{%- tag_md tag.name, name="peter", version="1.0.2" -%}</section>

[thedamon]

Yeah that does it! i wasn't sure if i needed or how to source from files like that dynamically, but that does it for sure

[thedamon]

Follow up question as I'm working on this more — how can I check that the file actually exists? It seems to break if i add a tag that doesn't have an equivalent .md file, but i'd like it to fail silently. Is that an option with renderFile? I get that it wants these files to exist but not sure how to tell it it's ok if it doesn't.

[11ty] 1. Having trouble rendering njk template ./tags.njk (via TemplateContentRenderError)
[11ty] 2. (./tags.njk)
[11ty]   EleventyShortcodeError: Error with Nunjucks shortcode `renderFile` (via Template render error)
[11ty] 3. Could not find render plugin file for the `renderFile` shortcode, looking for: ./_meta/tags/fiction.md (via Template render error) 

[pdehaan]

I might do something like the suggestion above:

  eleventyConfig.addAsyncShortcode("tag_md", function (name, kwargs) {
    return eleventyConfig.javascriptFunctions.renderFile(`./src/_includes/${name}.md`, kwargs);
  });

You could add an additional check w/ https://nodejs.org/api/fs.html#fsexistssyncpath that checks if the target file exists and either throw a hard error (and probably break your build), or else fail silently and maybe just return an empty string. Just depends on how loud you want the error.