TASK ARCHIVE: Tag Descriptions on Archive Pages#

SUMMARY#

Added optional per-tag descriptions seeded in _data/tags.yaml, rendered as body blurbs on tag archive pages (blog and garden) and injected as plain-text SEO metadata via a Jekyll :pages, :pre_render hook. Descriptions support Markdown and inline HTML in the body, with plain-text extraction for SEO meta tags.

REQUIREMENTS#

1. Data file: _data/tags.yaml — flat mapping of tag slug to description string (YAML block scalar). Descriptions may contain HTML and/or Markdown.
2. Layout change: _layouts/tag-archive.html and _layouts/garden-tag-archive.html — if a description exists for the current tag, render it between the heading and the post/note list.
3. Conditional: Tags without an entry (or with an empty entry) should render unchanged — no visible change.
4. Rendering: Descriptions processed through Kramdown (| markdownify) so both Markdown and inline HTML are supported in the body.
5. SEO metadata (rework): Tag descriptions must also appear in <meta name="description">, og:description, and JSON-LD description via jekyll-seo-tag.

IMPLEMENTATION#

Files created/modified:

• _data/tags.yaml (new) — Single source of truth for tag descriptions. Keys must exactly match tag strings used in post/page front matter. Values are YAML block scalars (use >- for single-paragraph, | for multi-paragraph).

• _layouts/tag-archive.html — Added conditional Liquid block after <h1> that looks up site.data.tags[page.title] and renders through | markdownify if present.

• _layouts/garden-tag-archive.html — Same conditional block as above. _data/tags.yaml is global — same description applies to blog tags, garden tags, and any future tag archive.

• _plugins/tag_descriptions_seo.rb (new, rework) — :pages, :pre_render hook that:

  • Checks if page layout is tag-archive or garden-tag-archive
  • Looks up tag description in site.data['tags'] using page.title (method, not page.data['title'])
  • Renders description through Kramdown to HTML, strips HTML tags, unescapes HTML entities via CGI.unescapeHTML, normalizes whitespace
  • Sets page.data['description'] so jekyll-seo-tag picks it up for meta tags

Key implementation detail: Jekyll::Archives::Archive objects store the tag name via a title method, not in page.data['title']. The hook must use page.title for the lookup.

TESTING#

Original build verification:

• Built site with bundle exec jekyll build
• Verified 5 behaviors: description rendered in body, no description unchanged, Markdown rendered, HTML passthrough, empty entry ignored
• Checked both blog and garden tag archive pages

Rework verification:

• Built site with SEO plugin
• Verified 6 behaviors: SEO meta tags with description, SEO without description (site default), JSON-LD description, og:description, garden tag SEO, body blurb unchanged
• Confirmed HTML entity unescaping works correctly (em-dash, ampersands, etc.)

QA: Both passes found no issues. Code follows KISS, DRY (acceptable duplication), YAGNI principles.

LESSONS LEARNED#

Technical:

• Jekyll::Archives::Archive stores page metadata (title, tag, type) as instance methods, not in the page.data hash. When writing hooks that target archive pages, always use page.title / page.type rather than page.data['title']. This is a gotcha that arises specifically from the jekyll-archives gem’s class design and is not documented in the gem’s README.
• Liquid’s != blank idiom handles nil, empty string, and whitespace-only uniformly — preferable to chaining and conditions for Jekyll data file lookups where a key may be absent, empty, or whitespace.
• Kramdown escapes reserved characters into HTML entities. When converting Markdown → HTML → plain text for SEO, must call CGI.unescapeHTML after tag-stripping to avoid double-encoding when jekyll-seo-tag applies its own xml_escape filter.

Process:

• When planning a hook that targets pages from a third-party generator, investigate the generated page class’s data model before writing the implementation plan. A quick Jekyll.logger.debug pass listing available attributes would have caught the page.data['title'] issue at plan time rather than build time.

PROCESS IMPROVEMENTS#

None — clean execution with one debugging iteration during rework build to discover the Archive class data model difference.

TECHNICAL IMPROVEMENTS#

If tag descriptions had been a foundational assumption, the ideal design would be the same — _data/tags.yaml as the single source, with a pre-render hook injecting into page.data['description'] for SEO and Liquid markdownify for the body. The only improvement would be to extract the tag lookup into a shared utility if more consumers emerge (e.g., a tags index page showing descriptions). For now, two independent access paths (Liquid and Ruby) is the right level of coupling.

NEXT STEPS#

None.