feat(seo): add useSeo composable with JSON-LD and canonical

[amondnet]

Summary

Ports upstream docus commit d283f9aa (feat(layer): add more seo optimization) — item #10 from docs/docus-upstream-changes.md.

Follows on from #27 (first docus upstream bundle).

What's in the box

• New packages/layer/app/composables/useSeo.ts (auto-imported)
  • Reactive title / description flowing into useSeoMeta with full OpenGraph + Twitter card meta
  • Canonical <link> resolved from useAppConfig().docs.url (populated by modules/config.ts) with an inferSiteURL() fallback so SSR works in CI environments where app.config isn't pre-populated
  • JSON-LD Article or WebSite schema (chosen by type) plus an optional BreadcrumbList script when the caller supplies a trail
• packages/layer/app/pages/[...slug].vue now calls useSeo with breadcrumbs computed from useNavigation + findPageBreadcrumbs (both already landed in feat(layer): port first docus upstream bundle #27)

Hreflang deferral

Upstream's useSeo also emits <link rel="alternate" hreflang="..."> tags driven by useDocusI18n / runtimeConfig.public.i18n. Our layer doesn't ship @nuxtjs/i18n yet, so the hreflang branch is left as a TODO comment inside useSeo.ts — to be wired up alongside the i18n module work tracked separately in the survey.

Verification

bun lint        # passes
bun typecheck   # passes for new code (pre-existing errors unchanged)
bun dev         # http://localhost:3001/docs/getting-started/introduction shows:
                #   <link rel="canonical" ...>
                #   <meta property="og:*" ...>
                #   <meta name="twitter:*" ...>
                #   <script type="application/ld+json"> Article + BreadcrumbList

Type of change

• New feature (non-breaking change which adds functionality)

---

Summary by cubic

Adds a useSeo composable to set canonical links, OpenGraph/Twitter meta, and JSON-LD (Article/WebSite + Breadcrumbs) for better SEO. Docs pages now use useSeo with computed breadcrumbs.

• New Features

  • Canonical URL resolved from useAppConfig().docs.url with inferSiteURL() fallback.
  • JSON-LD scripts: Article or WebSite, plus BreadcrumbList when breadcrumbs are provided.
  • OpenGraph and Twitter meta from reactive title/description, with optional ogImage, publishedAt, and modifiedAt.
  • [...slug].vue computes breadcrumbs via useNavigation + findPageBreadcrumbs and calls useSeo.
  • Hreflang tags deferred until @nuxtjs/i18n is added.

• Bug Fixes

  • Use textContent (not innerHTML) for JSON-LD scripts to avoid XSS.
  • Allow BreadcrumbList to render even when title is unset.

^{Written for commit a50c22e. Summary will update on new commits.}

[gemini-code-assist]

Code Review

This pull request introduces a new useSeo composable in packages/layer/app/composables/useSeo.ts to handle comprehensive SEO setup for documentation pages, including standard meta tags, canonical links, and JSON-LD structured data. The review feedback highlights a critical security vulnerability regarding potential Cross-Site Scripting (XSS) when injecting unescaped JSON-LD schemas into <script> tags, and suggests a robustness improvement to decouple the breadcrumb schema generation from the page title check.

[cloudflare-workers-and-pages]

Deploying docs-please with    Cloudflare Pages

Latest commit:	a50c22e
Status:	⚡️  Build in progress...

View logs

[cubic-dev-ai]

2 issues found across 2 files

Architecture diagram

sequenceDiagram
    participant Page as [...slug].vue
    participant useSeo as useSeo composable
    participant useNavigation as useNavigation
    participant findBread as findPageBreadcrumbs
    participant route as useRoute
    participant appConfig as useAppConfig
    participant inferURL as inferSiteURL
    participant useSeoMeta as useSeoMeta
    participant useHead as useHead
    participant DOM as DOM
    
    Note over Page,DOM: Page load - docs content route
    
    Page->>useNavigation: get navigation tree
    useNavigation-->>Page: navigation data
    
    Page->>findBread: compute breadcrumbs from navigation + route.path
    findBread-->>Page: BreadcrumbItem[] 
    
    Page->>useSeo: call with title, description, type, publishedAt, modifiedAt, breadcrumbs
    
    useSeo->>route: get current path
    route-->>useSeo: route.path
    
    useSeo->>appConfig: get docs.url
    appConfig-->>useSeo: configured URL or undefined
    
    alt appConfig.docs.url is empty
        useSeo->>inferURL: fallback to env-based inference
        inferURL-->>useSeo: resolved base URL
    end
    
    useSeo->>useSeo: compute baseUrl (without trailing slash)
    useSeo->>useSeo: compute canonicalUrl = joinURL(baseUrl, route.path)
    
    Note over useSeo,useHead: Meta tags (OpenGraph + Twitter)
    useSeo->>useSeoMeta: set ogTitle, ogDescription, ogType, ogUrl, ogImage, twitterCard, twitterTitle, twitterDescription, twitterImage
    useSeoMeta-->>DOM: meta tags inserted
    
    Note over useSeo,useHead: Canonical link
    useSeo->>useHead: set link[rel=canonical] with href=canonicalUrl
    useHead-->>DOM: <link rel="canonical"> inserted
    
    Note over useSeo,useHead: JSON-LD structured data
    
    alt type === 'article'
        useSeo->>useSeo: build Article schema with headline, description, url, mainEntityOfPage
        opt publishedAt provided
            useSeo->>useSeo: add datePublished
        end
        opt modifiedAt provided
            useSeo->>useSeo: add dateModified
        end
        opt siteName available
            useSeo->>useSeo: add publisher Organization
        end
    else type === 'website'
        useSeo->>useSeo: build WebSite schema with name, description, url
    end
    
    opt breadcrumbs length > 0
        useSeo->>useSeo: build BreadcrumbList schema with position, name, item for each breadcrumb
    end
    
    useSeo->>useHead: set script[type=application/ld+json] with innerHTML
    useHead-->>DOM: <script type="application/ld+json"> inserted
    
    Note over useSeo,DOM: Hreflang deferred (TODO until @nuxtjs/i18n wired)

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud