secondsky/claude-skills / plugins/nuxt-seo/skills/nuxt-seo
nuxt-seo
VerifiedNuxt SEO v5 modules (robots, sitemap, og-image, schema-org, link-checker, seo-utils, site-config). Use when implementing SEO, robots.txt, sitemaps, Schema.org, or meta tags in Nuxt apps.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.6 KB |
| assets/package-versions.json | config | 3.6 KB |
| references/advanced-configuration.md | markdown | 9.0 KB |
| references/advanced-seo-guides.md | markdown | 18.8 KB |
| references/ai-seo-tools.md | markdown | 10.9 KB |
| references/api-reference.md | markdown | 10.2 KB |
| references/best-practices.md | markdown | 5.4 KB |
| references/common-patterns.md | markdown | 12.7 KB |
| references/installation-guide.md | markdown | 7.2 KB |
| references/module-details.md | markdown | 14.2 KB |
| references/modules-overview.md | markdown | 9.6 KB |
| references/nitro-api-reference.md | markdown | 14.2 KB |
| references/nuxt-content-integration.md | markdown | 14.4 KB |
| references/og-image-guide.md | markdown | 13.5 KB |
| references/pro-modules.md | markdown | 6.8 KB |
| references/seo-guides.md | markdown | 24.7 KB |
| references/sitemap-advanced.md | markdown | 16.3 KB |
| references/troubleshooting.md | markdown | 5.7 KB |
| references/v5-migration-guide.md | markdown | 8.5 KB |
| scripts/init-nuxt-seo.shexecutable | script | 7.0 KB |
references/sitemap-advanced.md
View on GitHub# Nuxt Sitemap - Advanced Guide
Comprehensive guide to advanced sitemap features including dynamic URLs, multi-sitemaps, images/videos, i18n, and performance optimization.
---
## Table of Contents
1. [Dynamic URL Endpoints](#dynamic-url-endpoints)
2. [Multi Sitemaps](#multi-sitemaps)
3. [Images, Videos, and News](#images-videos-and-news)
4. [I18n Integration](#i18n-integration)
5. [Prerendering](#prerendering)
6. [Performance Optimization](#performance-optimization)
7. [Caching Strategies](#caching-strategies)
8. [Zero Runtime Mode](#zero-runtime-mode)
---
## Dynamic URL Endpoints
Generate sitemap URLs dynamically from APIs or CMS at runtime.
### External XML Sitemaps
Reference existing XML sitemaps directly:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
sources: [
'https://example.com/sitemap.xml'
]
}
})
```
### API Sources with Authentication
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
sources: [
// Unauthenticated endpoint
'https://api.example.com/pages/urls',
// Authenticated endpoint with headers
[
'https://authenticated-api.example.com/pages/urls',
{ headers: { Authorization: 'Bearer <token>' } }
]
]
}
})
```
### Custom Sitemap Event Handler
Create type-safe sitemap endpoints using `defineSitemapEventHandler`:
```typescript
// server/api/__sitemap__/urls.ts
import { defineSitemapEventHandler } from '#imports'
import type { SitemapUrlInput } from '#sitemap/types'
export default defineSitemapEventHandler(() => {
return [
{
loc: '/about-us',
_sitemap: 'pages', // Assign to specific sitemap
},
] satisfies SitemapUrlInput[]
})
```
### WordPress Integration Example
```typescript
// server/api/__sitemap__/wordpress.ts
import { defineSitemapEventHandler } from '#imports'
export default defineSitemapEventHandler(async () => {
const posts = await $fetch('https://api.example.com/wp-json/wp/v2/posts')
return posts.map(post => ({
// Transform external URL to your domain
loc: `/blog/${post.slug}`, // NOT post.link
lastmod: post.modified,
changefreq: 'weekly',
priority: 0.7,
}))
})
```
### Dynamic i18n URLs
```typescript
// server/api/__sitemap__/urls.ts
import { defineSitemapEventHandler } from '#imports'
import type { SitemapUrl } from '#sitemap/types'
export default defineSitemapEventHandler(async () => {
const config = useRuntimeConfig()
const locales = config.public.i18n.locales.map(locale => locale.code)
const isoLocales = Object.fromEntries(
config.public.i18n.locales.map(locale => ([locale.code, locale.iso]))
)
const apiQueries = locales.map(locale =>
$fetch(`${config.public.apiEndpoint}/sitemap/${locale}/products`)
)
const sitemaps = await Promise.all(apiQueries)
return sitemaps.flat().map(entry => ({
_sitemap: isoLocales[entry.locale],
loc: `${config.public.siteUrl}/${entry.locale}/product/${entry.url}`,
alternatives: entry.alternates?.map(alt => ({
hreflang: isoLocales[alt.locale],
href: `${config.public.siteUrl}/${alt.locale}/product/${alt.url}`
}))
} satisfies SitemapUrl))
})
```
### Pre-Encoded URLs
If your API returns already-encoded URLs:
```typescript
// server/api/__sitemap__/urls.ts
import { defineSitemapEventHandler } from '#imports'
export default defineSitemapEventHandler(async () => {
const urls = await $fetch<{ path: string }[]>('https://api.example.com/pages')
// e.g. [{ path: '/products/%24pecial-offer' }]
return urls.map(url => ({
loc: url.path,
_encoded: true, // Prevent double-encoding
}))
})
```
### Register Custom Endpoint
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
sources: [
'/api/__sitemap__/urls'
]
}
})
```
---
## Multi Sitemaps
Split your sitemap into multiple files for better organization and performance.
### Manual Chunking
Best for sites with clear content types:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
sitemaps: {
posts: {
include: ['/blog/**'],
defaults: { priority: 0.7 },
},
pages: {
exclude: ['/blog/**']
},
},
},
})
```
### Automatic Chunking
Best for sites with 1000+ URLs without clear types:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
sitemaps: true,
defaultSitemapsChunkSize: 2000 // default: 1000
},
})
```
### Custom Sitemap URLs
Remove the `/__sitemap__/` prefix:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
sitemapsPathPrefix: '/', // or false
sitemaps: {
['sitemap-foo']: {
// Available at /sitemap-foo.xml
}
}
}
})
```
### Extending App Sources
Filter existing URLs into different sitemaps:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
sitemaps: {
pages: {
includeAppSources: true,
exclude: ['/blog/**'],
},
posts: {
includeAppSources: true,
include: ['/blog/**'],
},
},
},
})
```
### Using _sitemap Key
Direct URLs to specific sitemaps:
```typescript
// server/api/sitemap-urls.ts
export default defineSitemapEventHandler(() => {
return [
{
loc: '/about-us',
_sitemap: 'pages', // Goes to pages sitemap
}
]
})
```
### Chunking Large Sources
Split large sources automatically:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
sitemaps: {
posts: {
sources: ['/api/posts'], // Returns 10,000 posts
chunks: true, // Default chunk size: 1000
},
products: {
sources: ['/api/products'], // Returns 50,000 products
chunks: 5000, // Custom chunk size
},
}
},
})
```
**Generated files:**
- `/sitemap_index.xml`
- `/posts-0.xml`, `/posts-1.xml`, ...
- `/products-0.xml`, `/products-1.xml`, ...
### External Sitemaps in Index
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
sitemaps: {
posts: { /* ... */ },
pages: { /* ... */ },
// Add external sitemap to index
index: [
{ sitemap: 'https://www.google.com/sitemap-pages.xml' }
]
}
}
})
```
---
## Images, Videos, and News
Add rich media to sitemap entries for enhanced search visibility.
### Sitemap Images
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
urls: [
{
loc: '/blog/my-post',
images: [
{
loc: 'https://example.com/image.jpg',
caption: 'My image caption',
geo_location: 'New York, USA',
title: 'My image title',
license: 'https://example.com/license',
}
]
}
]
}
})
```
### Automatic Image Discovery
Images are discovered automatically when:
- Page is prerendered
- Images are inside `<main>` tag
```typescript
// Disable if not needed
export default defineNuxtConfig({
sitemap: {
discoverImages: false
}
})
```
### Sitemap Videos
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
urls: [
{
loc: '/blog/my-post',
videos: [
{
title: 'My video title',
thumbnail_loc: 'https://example.com/video.jpg',
description: 'My video description',
content_loc: 'https://example.com/video.mp4',
player_loc: 'https://example.com/player',
duration: 600,
expiration_date: '2025-12-31',
rating: 4.2,
view_count: 1000,
publication_date: '2025-01-15',
family_friendly: true,
restriction: {
relationship: 'allow',
country: 'US',
},
platform: {
relationship: 'allow',
platform: 'web',
},
price: [
{
price: 1.99,
currency: 'USD',
type: 'rent',
}
],
requires_subscription: false,
uploader: {
uploader: 'Channel Name',
info: 'https://example.com/channel',
},
live: false,
tag: ['tutorial', 'nuxt'],
}
]
}
]
}
})
```
### Automatic Video Discovery
Videos inside `<main>` with data attributes:
```html
<video
controls
poster="https://example.com/thumb.jpg"
width="620"
data-title="Video Title"
data-description="Video description for sitemap"
data-rating="4.5"
data-view-count="1000"
data-publication-date="2025-01-15"
data-family-friendly="yes"
>
<source src="https://example.com/video.mp4" type="video/mp4" />
</video>
```
### News Sitemaps
For Google News:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
urls: [
{
loc: '/news/nuxt-sitemap-turns-6',
news: [
{
title: 'Nuxt Sitemap Turns 6',
publication_date: '2025-01-15',
publication: {
name: 'Nuxt SEO News',
language: 'en',
},
}
]
}
]
}
})
```
---
## I18n Integration
Automatic integration with @nuxtjs/i18n and nuxt-i18n-micro.
### Automatic Multi Sitemap
Generated automatically when:
- Not using `no_prefix` strategy
- Or using Different Domains
- Haven't manually configured `sitemaps`
```
./sitemap_index.xml
./en-sitemap.xml
./fr-sitemap.xml
```
### _i18nTransform
Automatically generate URLs for all locales:
```typescript
// server/api/__sitemap__/urls.ts
export default defineSitemapEventHandler(() => {
return [
{
loc: '/about-us',
_i18nTransform: true, // Creates /en/about-us, /fr/about-us, etc.
}
]
})
```
### Custom Path Translations
If using i18n pages configuration:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
i18n: {
pages: {
'about': {
en: '/about',
fr: '/a-propos',
es: '/acerca-de',
},
},
},
})
```
With `_i18nTransform: true`:
- `/about` (en)
- `/fr/a-propos` (fr)
- `/es/acerca-de` (es)
### Specific Locale Assignment
```typescript
export default defineSitemapEventHandler(() => {
return [
{
loc: '/about-us',
_sitemap: 'en', // Only in English sitemap
}
]
})
```
### Debug Hreflang
Show hreflang counts in UI:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
xslColumns: [
{ label: 'URL', width: '50%' },
{ label: 'Last Modified', select: 'sitemap:lastmod', width: '25%' },
{ label: 'Hreflangs', select: 'count(xhtml)', width: '25%' },
],
}
})
```
---
## Prerendering
Extract sitemap data from prerendered HTML.
### Extracted Data
When pages are prerendered:
- **images**: From `<img>` tags inside `<main>`
- **videos**: From `<video>` tags inside `<main>`
- **lastmod**: From `article:modified_time` and `article:published_time` meta tags
### Enable Prerendering
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
prerender: {
crawlLinks: true,
routes: ['/']
}
}
})
```
Or with route rules:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
routeRules: {
'/': { prerender: true }
}
})
```
### Prerender Sitemap on Build
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
prerender: {
routes: ['/sitemap.xml']
}
}
})
```
### Custom Prerender Data
Extract YouTube videos from iframes:
```typescript
// nuxt.config.ts
import type { ResolvedSitemapUrl } from '#sitemap/types'
export default defineNuxtConfig({
modules: [
(_, nuxt) => {
nuxt.hooks.hook('nitro:init', async (nitro) => {
nitro.hooks.hook('prerender:generate', async (route) => {
const html = route.contents
const matches = html.match(/<iframe.*?youtube.com\/embed\/(.*?)".*?<\/iframe>/g)
if (matches) {
const sitemap = route._sitemap || {} as ResolvedSitemapUrl
sitemap.videos = sitemap.videos || []
for (const match of matches) {
const videoId = match.match(/youtube.com\/embed\/(.*?)"/)[1]
sitemap.videos.push({
title: 'YouTube Video',
description: 'A video from YouTube',
content_loc: `https://www.youtube.com/watch?v=${videoId}`,
thumbnail_loc: `https://img.youtube.com/vi/${videoId}/0.jpg`,
})
}
route._sitemap = sitemap
}
})
})
},
],
})
```
---
## Performance Optimization
Optimize sitemap generation for large sites.
### Named Sitemap Chunks
Split by content type for parallel generation:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
sitemaps: {
posts: {
sources: ['https://api.example.com/urls']
},
},
},
})
```
### Paginated Sources
For very large datasets:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
sitemaps: {
posts2020: {
sources: ['https://api.example.com/urls?filter[yearCreated]=2020']
},
posts2021: {
sources: ['https://api.example.com/urls?filter[yearCreated]=2021']
},
posts2022: {
sources: ['https://api.example.com/urls?filter[yearCreated]=2022']
},
},
},
})
```
### Experimental Options
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
experimentalCompression: true, // Gzip and stream sitemap
experimentalWarmUp: true, // Create sitemaps on Nitro start
}
})
```
---
## Caching Strategies
### Default Caching
SWR caching enabled in production (10 minutes default).
### Custom Cache Time
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
cacheMaxAgeSeconds: 3600 // 1 hour
}
})
```
### Disable Caching
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
cacheMaxAgeSeconds: 0
}
})
```
### Custom Cache Driver
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
runtimeCacheStorage: {
driver: 'cloudflare-kv-binding',
binding: 'SITEMAP_CACHE'
}
}
})
```
---
## Zero Runtime Mode
Generate sitemaps at build time for zero server overhead.
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
sitemap: {
zeroRuntime: true
}
})
```
**Benefits:**
- ~50KB reduction in server bundle
- Static file serving
- No runtime generation
**Requirements:**
- URLs only change on deploy
- All pages must be prerenderable
---
## TypeScript Interfaces
### SitemapUrl
```typescript
interface SitemapUrl {
loc: string
lastmod?: string | Date
changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never'
priority?: number
images?: ImageEntry[]
videos?: VideoEntry[]
news?: GoogleNewsEntry[]
alternatives?: AlternativeEntry[]
_sitemap?: string
_i18nTransform?: boolean
_encoded?: boolean
}
interface ImageEntry {
loc: string
caption?: string
geo_location?: string
title?: string
license?: string
}
interface VideoEntry {
title: string
thumbnail_loc: string
description: string
content_loc?: string
player_loc?: string
duration?: number
expiration_date?: Date | string
rating?: number
view_count?: number
publication_date?: Date | string
family_friendly?: boolean | 'yes' | 'no'
restriction?: { relationship: 'allow' | 'deny', country: string }
platform?: { relationship: 'allow' | 'deny', platform: string }
price?: { price: number | string, currency: string, type: string }[]
requires_subscription?: boolean | 'yes' | 'no'
uploader?: { uploader: string, info?: string }
live?: boolean | 'yes' | 'no'
tag?: string | string[]
}
interface GoogleNewsEntry {
title: string
publication_date: Date | string
publication: {
name: string
language: string
}
}
```
---
## Official Documentation
- **Sitemap Module**: https://nuxtseo.com/docs/sitemap/getting-started/introduction
- **Dynamic URLs**: https://nuxtseo.com/docs/sitemap/guides/dynamic-urls
- **Multi Sitemaps**: https://nuxtseo.com/docs/sitemap/guides/multi-sitemaps
- **Images/Videos**: https://nuxtseo.com/docs/sitemap/advanced/images-videos
- **I18n**: https://nuxtseo.com/docs/sitemap/guides/i18n
- **Performance**: https://nuxtseo.com/docs/sitemap/advanced/performance
- **GitHub**: https://github.com/nuxt-modules/sitemap
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |