Template cleanup

[travisbeckham]

This PR makes several improvements to Hugo's templates. For reviewers, there should be no visible changes on the site.

4bbe17d

Only truncate the meta description after it's been converted to plain text, so that the character count will more accurate.

d216a24

Now that the site is being built with Hugo v.0.158.0, we can use .Language.Locale, which defaults to en.

eadb463

Since we're now using the new template system introduced in Hugo v.0.146.0, we can have shortcodes at any level of the layout directory. The _shortcodes/docs shortcodes were moved to docs/_shortcodes, so they will only be accessible in the docs section.

For reviewers, note that the commands are still being listed on this page: https://deploy-preview-2135--linkerdio.netlify.app/docs/reference/cli/

233a921

Since the versions shortcode is only called one time, it was moved to an inline shortcode.

For reviewers, note that the versions are still being listed on this page: https://deploy-preview-2135--linkerdio.netlify.app/releases/

[siggy]

i'm still browsing around, but i found one issue, on https://deploy-preview-2135--linkerdio.netlify.app/releases/, it renders L5D2_EDGE_VERSION:

[travisbeckham]

i'm still browsing around, but i found one issue, on https://deploy-preview-2135--linkerdio.netlify.app/releases/, it renders L5D2_EDGE_VERSION:

Yep, that string only gets replaced out when publishing to prod. It doesn't get swapped on Netlify branch previews.

[siggy]

lgtm!

tested with claude...

start at the top level of the docs, browse down to each page, look for differences and issues:
https://linkerd.io/docs/overview/ https://deploy-preview-2135--linkerdio.netlify.app/docs/overview/

---

Good, I have all 135 prod links. Now let me get the preview site's nav:Both navs have the same 135 pages — no added/removed pages. Now I'll programmatically compare page content across both sites using in-browser fetch. Let me run a bulk diff:Found 5 pages with differences. Now let me drill into each to find the exact changes:398 char-level diffs suggests it's mostly a token substitution. Let me check the unique prod→preview values:Only one change in getting-started: edge-26.6.3 → L5D2_EDGE_VERSION — an unresolved template placeholder. Now let me check the other 4 pages:Same pattern: LINKERD_VERSION=edge-26.6.3 → LINKERD_VERSION=L5D2_EDGE_VERSION. Let me check the remaining three pages quickly:The pattern is clear from what I've seen. Let me navigate directly to the changed pages to confirm, rather than fighting the filter:85 word-level diffs suggests misalignment from one insertion/deletion. Let me find the exact character difference:Found it — the preview adds extra blank lines inside code blocks (\n → \n\n between continuation lines). Now let me check the last two pages:Now I have a complete picture. Let me compile the full report:Here's the full diff report across all 135 pages. The nav structure is identical on both sites. Five pages have content differences:

---

1. /docs/getting-started/ — unresolved template variable

• Prod: export LINKERD2_VERSION=edge-26.6.3
• Preview: export LINKERD2_VERSION=L5D2_EDGE_VERSION

The preview has a raw template placeholder where the actual version string should be substituted at build time.

---

2. /docs/tasks/adding-non-kubernetes-workloads/ — same template issue

• Prod: LINKERD_VERSION=edge-26.6.3
• Preview: LINKERD_VERSION=L5D2_EDGE_VERSION

Same unresolved L5D2_EDGE_VERSION placeholder.

---

3. /docs/tasks/install-helm/ — same template issue

• Prod: edge-26.6.3 (in the helm search repo linkerd output table)
• Preview: L5D2_EDGE_VERSION

Same pattern.

---

4. /docs/tasks/external-prometheus/ — extra blank lines inside code blocks

Code blocks that use line continuations (\) have extra blank lines inserted between lines in the preview. Example:

• Prod: linkerd viz install \↵ --set prometheus.enabled=false \↵ --set prometheusUrl=...
• Preview: linkerd viz install \↵↵ --set prometheus.enabled=false \↵↵ --set prometheusUrl=...

This affects at least two pre blocks on that page (the prometheusUrl and prometheusCredsSecret examples).

---

5. /docs/tasks/multicluster-using-statefulsets/ — Cloudflare email obfuscation on prod

• Prod (rendered): $ git clone [email protected]:linkerd/l2d-k3d-statefulset.git — Cloudflare's email obfuscation is treating git@github.com as an email address and replacing it with a [email protected] placeholder. This breaks the clone command for users who copy it from the page.
• Preview (Netlify): $ git clone git@github.com:linkerd/l2d-k3d-statefulset.git ✓

This last one is actually a prod bug independent of the PR — Cloudflare Email Obfuscation needs to be disabled (or a <!--email_off--> comment added around that code block).

---

Summary: Issues 1–3 are the same bug — L5D2_EDGE_VERSION is not being substituted in the preview build. Issue 4 is a stray whitespace change in external-prometheus. Issue 5 is a pre-existing prod-only Cloudflare obfuscation bug affecting the git SSH URL in the multicluster statefulsets guide.