Add hreflang attribute to metaLinks.alternates for multilingual SEO

[Nicogugu]

Context

We run a GitBook help center with two variants (FR + EN) under the same site. Each article exists in both languages with native slugs (/fr/mon-article ↔ /en/my-article).

Current behavior

Setting a per-page Alternate via Page options → Metadata (or git frontmatter metaLinks.alternates) renders this in the HTML head:

<link rel="alternate" type="" href="https://site.com/en/my-article" />

The type="" attribute is empty. No hreflang.

Problem

Google's multilingual SEO guidelines require:

<link rel="alternate" hreflang="fr" href="https://site.com/fr/mon-article" />
<link rel="alternate" hreflang="en" href="https://site.com/en/my-article" />
<link rel="alternate" hreflang="x-default" href="https://site.com/en/my-article" />

Without hreflang, crawlers can't identify these pages as language variants of the same content. Each variant competes in isolation in its respective language market, duplicate-content penalties are possible, and users landing in the wrong-language variant aren't routed back by search engines.

This is critical for any multilingual knowledge base targeting SEO — which is most customer-facing help centers.

Desired behavior

1. Add an optional hreflang field on metaLinks.alternates[] entries — accepting standard values like en, fr, de, x-default.
2. Emit hreflang="..." in the rendered <link rel="alternate"> tag when set.
3. Ideally: auto-populate hreflang from the target page's variant language when the alternate is set through the UI picker (since variants already have a language field).

Workaround attempted

Tried the object form in frontmatter:

metaLinks:
  alternates:
    - hreflang: en
      url: https://site.com/en/my-article

Result: GitBook couldn't parse it and rendered <link rel="alternate" type="" href=".../[object Object]/README.md" /> — three broken links on the page.

Impact

Critical for multilingual help centers that depend on SEO for discovery. Without this, every multilingual GitBook customer needs to either:

• Accept degraded SEO (current state)
• Inject hreflang via advancedCustomization JS (works for rendering but Googlebot coverage is less reliable than HTML-static tags)
• Move away from GitBook for the public site

Thanks!