influxdata / influxdata/docs-v2
JSON-LD TechArticle description emits raw Hugo shortcodes (structured-data/SEO bug, ~264 pages)
- 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