influxdata / influxdata/docs-v2

JSON-LD TechArticle description emits raw Hugo shortcodes (structured-data/SEO bug, ~264 pages)

Open Beginner friendly
#7,565 0 comments 0 reactions 0 assignees View on GitHub
doc-bug
Dominant language
JavaScript
Stars
82
Forks
326
Avg merge
1d 1h
Merged PRs (30d)
82

Description

## Summary

The TechArticle JSON-LD structured data emits the page's frontmatter `description` **without expanding Hugo shortcodes**. On every page whose `description` uses a shortcode (for example `{{< product-name >}}` or `{{% product-name %}}`), the structured data contains the literal, unrendered shortcode.

**~264 built pages** are affected (site-wide: influxdb, telegraf, flux, kapacitor).

Example — rendered `/influxdb3/enterprise/admin/license/` JSON-LD:

```json
"description":"{{< product-name >}} licenses authorize the use of the {{< product-name >}} software…"
```

The same page's `` is **correct** ("InfluxDB 3 Enterprise licenses authorize…"), so this is isolated to the JSON-LD sink.

## Root cause

`layouts/partials/header/techarticle-jsonld.html:30`:

```go-html-template
{{- with or .Description .Summary -}}
{{- $article = merge $article (dict "description" (. | plainify | strings.TrimSpace)) -}}
{{- end -}}
```

`plainify` strips HTML but does **not** expand shortcodes. Only `.RenderString` (or `.Content`) expands them. The meta-description sink gets this right — `layouts/partials/header.html:14` uses `.Description | .RenderString | plainify`.

## Impact

Search engines, rich-result parsers, and LLM crawlers consume the `TechArticle.description` from structured data. Across ~264 pages that field contains literal `{{< product-name >}}` template syntax instead of the product name — degraded SEO/structured-data quality site-wide.

## Fix

Mirror the meta-description sink: render before plainify. Inside the `with`, `.` is the description string, so use the page context (`$`) for `RenderString`:

```go-html-template
{{- with or .Description .Summary -}}
{{- $article = merge $article (dict "description" ($.RenderString . | plainify | strings.TrimSpace)) -}}
{{- end -}}
```

One central template change fixes all affected pages. No content edits required.

## Related (verify separately)

`layouts/partials/header/faq-jsonld.html:21` uses `.answer | markdownify | plainify`. `markdownify` also does not expand shortcodes, so any FAQ answer containing a shortcode would leak the same way. Confirm whether FAQ answer data uses shortcodes.

## Verification

```bash
npx hugo --quiet -d /tmp/pub
grep -rlE '\{\{(%|\\u003c) *product-name' /tmp/pub | wc -l # expect 0 after fix
```

## Priority

High — affects structured-data correctness across the whole site (~264 pages), and no `high-priority` label exists in this repo, so noting it here.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with layouts/partials/header/techarticle-jsonld.html:30 and compare it with layouts/partials/header.html:14, which handles the meta description correctly. Check the related FAQ path in layouts/partials/header/faq-jsonld.html:21 separately. Run npx hugo --quiet -d /tmp/pub and verify the grep check finds no unrendered product-name shortcodes in the generated output.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, web-dev
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
88/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.