@towa-digital/storyblok-nuxt-sitemap

Storyblok Nuxt Sitemap

Storyblok Nuxt Module for doing amazing things.

• ✨ Release Notes

Features

• get all stories from storyblok
• custom filtering
• nitro hook to adjust slugs if needed
• nitro hook to skip stories

Requirements

• @nuxtjs/sitemap nuxt sitemap installed — list this module before it in modules: it defaults sitemap.autoI18n to false so @nuxtjs/sitemap does not add self-referencing hreflang alternates to every entry (hreflang belongs in the page markup only). Set sitemap.autoI18n yourself to override.
• @storyblok/nuxt, @storyblok npm modules recommended, but not required
• @nuxtjs/i18n installed is recommended, but not required

Quick Setup

Install the module to your Nuxt application with one command:

npx nuxi module add @towa-digital/storyblok-nuxt-sitemap

Webhooks

To trigger the sitemap generation on content changes, you need to add a webhook in Storyblok. The webhook should be configured to send a POST request to your Nuxt application with the path /api/generateSitemapLinks. The secret choosen in storyblok should be set in the Nuxt configuration (storyblokNuxtSitemap section). The basic setup would be everytime a story gets published, unpublished, deleted or moved, the sitemap will need to be regenerated.

Custom Trigger for the webhook

If you want to trigger the sitemap generation manually, you can send a POST request to the same endpoint. The Request needs to have a sha1 hash of the webhook secret and the body of the request as a header Webhook-Signature.

Configuration

in your nuxt config file add the following configuration:

export default {
  modules: [
    'storyblok-nuxt-sitemap'
  ],
  storyblokNuxtSitemap: {
    enabled: true, // Boolean, default true
    debug: true, // Boolean, default false 
    webhookSecret: process.env.WEBHOOK_SECRET, // your webhook secret (added via Storyblok Webhook settings)
    storyblokApiKey: process.env.STORYBLOK_API_KEY, // your Storyblok API key
    onlyStartsWith: 'dirname/', // Filter stories based on directory name
    defaultLocale: 'en', // Default locale (if i18n is used)
    contentVersion: 'draft', // Content version to use (draft or published)
    translationMode: 'field', // "field": Field-level translation (default), "folder": Folder-level translation
    lastmod: true, // <lastmod> from Storyblok published_at (published) / updated_at (draft). Default true
  },
}

Entries are stored as { loc, lastmod? } objects, loc being exactly what the adjustSlug hook returned.

Adjust slugs

if you need to modify the slugs of the stories, you can use the nitro hook storyblok-nuxt-sitemap:adjustSlug. This hook is called for each story and allows you to adjust the slug before it is added to the sitemap.

// here is an example of how such a plugin could look like.
// /server/plugins/adjustSlugs.ts 
import { defineNitroPlugin } from '@nuxtjs/nitro'
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('storyblok-sitemap:adjustSlug', (slug: string, locale: string) => {
    // adjust slugs of stories that start with 'dirname/'
    const replacement = locale !== 'en' ? '' : locale + '/'
    if (slug.startsWith('dirname/')) {
      return slug.replace('dirname/', replacement)
    }
    return slug
  })
  // Hook to adjust slugs exclusive for folder translation mode
  nitroApp.hooks.hook('storyblok-sitemap:adjustSlugForFolderTranslation', (slug: string, locale: string) => {
    // Example: Remove en prefix from slugs if it is the default locale
    if (locale === 'en' && slug.startsWith(`${locale}/`)) {
      return slug.replace(`${locale}/`, '');
    }
    return slug
  })
})

Skip stories

To leave stories out of the sitemap, e.g. content types without a page of their own, use the nitro hook storyblok-sitemap:skipLink. It is called once per story with the cdn/links entry, before any slug adjustment. Return true to drop the story in every language.

// /server/plugins/skipLinks.ts
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('storyblok-sitemap:skipLink', (link) => {
    return link.slug.startsWith('dirname/downloads/')
  })
})

cdn/links carries no content type or content. To skip by content, look the stories up via cdn/stories once per generation run and match on link.uuid.

Storage

The plugin stores the sitemap in the nuxt storage. You can customize the storage by providing a custom storage implementation for sitemap in the nitro section of the nuxt config.

 // nuxt.config.js
 // here you can define your custom storage driver for the sitemap
  nitro: {
    storage: {
      sitemap: {
        driver: 'fs',
        base: './static/sitemaps',
      },
    },
  },

Contribution

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch