This week I went through this site's SEO and fixed what was wrong. Some of it was missing config, but the worst problems came from Nuxt defaults I hadn't looked at: a component that rewrote my titles, unknown URLs that returned 200, and every external link in my posts marked nofollow. This is the Nuxt SEO setup that came out of it, with the config straight from the repo.

One caveat first. This site runs Nuxt 3.11 with Nuxt Content v2, @nuxtjs/sitemap 5, @nuxtjs/robots 3 and nuxt-schema-org 3. Nuxt 3 reached end of life in July 2026, and the current versions are Nuxt 4.6, Content 3, sitemap 9, robots 7 and schema-org 7. Most of what follows carries over unchanged. Where the newer versions differ, I say so.

What does a Nuxt SEO setup need?

For a content site like this one, the list is:

  • a canonical site URL that every module agrees on
  • a sitemap and a robots.txt that points to it
  • a title, description, canonical and Open Graph tags on every page
  • structured data for the person, the articles and the breadcrumbs
  • real HTTP status codes, especially 404
  • static HTML for pages that don't change
  • hreflang between translated posts
  • a share image for pages without their own

The modules are in nuxt.config.ts:

modules: [
  "@nuxt/image",
  "@nuxtjs/tailwindcss",
  "nuxt-icon",
  "@nuxtjs/sitemap",
  "@nuxtjs/robots",
  "@nuxt/content",
  "@vite-pwa/nuxt",
  "nuxt-schema-org",
],

Site config, sitemap and robots.txt

The sitemap, robots and schema.org modules all read the site URL from one place, the site key:

site: {
  url: "https://www.halit.org",
  name: "Halit Sever",
},

Set this first. Without it, the modules can't build absolute URLs for the sitemap and structured data.

The sitemap config:

sitemap: {
  strictNuxtContentPaths: true,
  exclude: ["/kac-gun-oldu"],
  urls: [
    { loc: "/", priority: 1.0, changefreq: "weekly" },
    { loc: "/blog", priority: 0.9, changefreq: "weekly" },
    { loc: "/projects", priority: 0.7, changefreq: "monthly" },
    // older posts with a fixed lastmod
  ],
},

strictNuxtContentPaths makes the module add every Nuxt Content document under its real path. The module also scans pages/, so a page you don't want indexed has to go in exclude. On Nuxt Content v3 this option is gone. Sitemap v9 dropped Content v2 support, and you add defineSitemapSchema() to a collection's schema in content.config.ts instead, with @nuxtjs/sitemap listed before @nuxt/content in modules.

robots.txt:

robots: {
  rules: [
    { UserAgent: "*" },
    { Allow: "/" },
    { Sitemap: "https://www.halit.org/sitemap.xml" },
  ],
},

The rules array is the robots v3 shape. Before I fixed it, the config used an older shape and the generated robots.txt didn't list the sitemap. Open /robots.txt on your deployed site and check that the Sitemap: line is there.

Hiding a page without listing it in robots.txt

This site has one page that shouldn't be indexed. It isn't in robots.txt, on purpose. robots.txt is public, so a Disallow line tells everyone the path exists. A Disallow also stops crawlers from fetching the page, so they never see its noindex tag and can still index the URL from links. Instead the page has a noindex meta tag and the server sends a header through a route rule:

routeRules: {
  "/kac-gun-oldu": {
    headers: { "X-Robots-Tag": "noindex, nofollow, noarchive" },
  },
},

Per-page meta with useSeoMeta and a canonical

app.vue sets the defaults that apply everywhere:

useSeoMeta({
  themeColor: "#07080b",
  ogType: "website",
  ogSiteName: "Halit Sever",
  robots: "index, follow",
});

Each page then sets its own title, description, canonical and Open Graph tags. This is the post page, pages/posts/[...slug].vue:

const post = doc.value;
const postUrl = `https://www.halit.org${route.path}`;
const description = String(post.description ?? "")
  .replace(/\s+/g, " ")
  .trim();
const lang = post.lang ?? "en";
const ogImage = post.thumbnail
  ? `https://www.halit.org${post.thumbnail}`
  : "https://www.halit.org/og.png";

useSeoMeta({
  title,
  ogTitle: title,
  description,
  ogDescription: description,
  ogImage,
  ogUrl: postUrl,
  ogType: "article",
  ogLocale: lang === "tr" ? "tr_TR" : "en_US",
  twitterCard: "summary_large_image",
  twitterCreator: "@halitsever_",
  author: "Halit Sever",
  articlePublishedTime: post.date ?? undefined,
  articleModifiedTime: post.updated ?? post.date ?? undefined,
  articleAuthor: ["Halit Sever"],
});

title is the post title with my name appended. The description is collapsed to one line because a folded YAML value can carry line breaks into the meta tag.

The canonical goes in useHead, since useSeoMeta only handles meta tags:

useHead({
  htmlAttrs: { lang },
  link: [{ rel: "canonical", href: postUrl }],
});

Setting htmlAttrs.lang from the post matters for the Turkish posts. Without it, a Turkish article would be served with <html lang="en"> from the global config.

Why I stopped using <ContentDoc> for the head

The post page used to render with <ContentDoc v-slot="{ doc }">. In Nuxt Content v2, <ContentDoc> calls useContentHead() with the document unless you pass :head="false". That function sets the page title to the bare front matter title and adds its own description and og:title tags. Because it runs inside a child component, its title won over the one my page set. Every post went out without my name in the title.

The fix was to fetch the document myself and render it with <ContentRenderer>, so the page is the only thing writing head tags:

const route = useRoute();
const { data: doc } = await useAsyncData(route.path, () =>
  queryContent(route.path).findOne(),
);
<div class="article-body">
  <ContentRenderer :value="post" />
</div>

On Content v3, queryContent is replaced by queryCollection("posts").path(route.path).first(), and the same pattern applies.

Return a real 404 for unknown posts

The old page wrapped all of its SEO code in if (doc.value) { ... }. For a path with no document, it rendered an empty article with status 200. Search engines call that a soft 404: a "not found" page that tells the crawler everything is fine. Now the page throws:

if (!doc.value) {
  throw createError({
    statusCode: 404,
    statusMessage: "Post not found",
    fatal: true,
  });
}

During SSR, createError sets the response status, and Nuxt renders its error page with a real 404. Try it on your own site with curl -I https://your-site/posts/does-not-exist and check the first line.

Structured data with nuxt-schema-org

The Person schema is shared, so it lives in a composable (shortened here):

// composables/usePersonSchema.ts
export const usePersonSchema = () =>
  definePerson({
    name: "Halit Sever",
    url: "https://www.halit.org",
    image: "https://www.halit.org/avatar.png",
    jobTitle: "Full-Stack Developer",
    worksFor: { "@type": "Organization", name: "90Pixel" },
    sameAs: [
      "https://www.linkedin.com/in/halitsever/",
      "https://github.com/halitsever",
      "https://x.com/halitsever_",
    ],
  });

The home page combines it with the site and the page:

useSchemaOrg([
  defineWebSite({ name: "Halit Sever", inLanguage: ["en", "tr"] }),
  usePersonSchema(),
  defineWebPage({ inLanguage: lang.value }),
]);

Each post adds an Article and a BreadcrumbList:

useSchemaOrg([
  usePersonSchema(),
  defineArticle({
    headline: post.title,
    description,
    image: ogImage,
    inLanguage: lang,
    author: { name: "Halit Sever", url: "https://www.halit.org" },
    url: postUrl,
    datePublished: post.date ?? undefined,
    dateModified: post.updated ?? post.date ?? undefined,
  }),
  defineBreadcrumb({
    itemListElement: [
      { name: "Home", item: "https://www.halit.org" },
      { name: "Writing", item: "https://www.halit.org/blog" },
      { name: post.title, item: postUrl },
    ],
  }),
]);

The module outputs everything as one JSON-LD @graph and adds the WebSite and WebPage nodes on its own. The nodes reference each other by @id, so the article's publisher and the page's about both point to the Person. Paste a post URL into Google's Rich Results Test to check the output.

hreflang between translated posts

Some posts exist in English and Turkish, like the Bursa day trip. Each version names the other in its front matter:

lang: tr
alternate: /posts/a-short-trip-to-bursa

The post page looks up the alternate and adds hreflang links for both versions next to the canonical:

const alternate = await useAsyncData(`${route.path}:alternate`, () =>
  post.alternate
    ? queryContent(post.alternate).only(["_path", "lang"]).findOne()
    : Promise.resolve(null),
).then((r) => r.data.value);
const alternateUrl = alternate
  ? `https://www.halit.org${alternate._path}`
  : null;

useHead({
  htmlAttrs: { lang },
  link: [
    { rel: "canonical", href: postUrl },
    // a preload for the post's first image sits here
    ...(alternate
      ? [
          { rel: "alternate", hreflang: lang, href: postUrl },
          {
            rel: "alternate",
            hreflang: alternate.lang ?? "en",
            href: alternateUrl!,
          },
        ]
      : []),
  ],
});

Google ignores hreflang unless the pages point to each other, so both front matters need the alternate field. Each version keeps its own canonical. The page also shows a visible "Read this post in English" or "Bu yazıyı Türkçe oku" link, which helps readers and gives crawlers a normal link between the two.

Prerendering posts and ISR for an API page

Posts don't change after I publish them, so they are prerendered to static HTML at build time:

routeRules: {
  "/": { prerender: true },
  "/blog": { prerender: true },
  "/posts/**": { prerender: true },
  "/projects": { isr: 86400 },
  // ...
},
nitro: {
  prerender: {
    crawlLinks: true,
    routes: ["/", "/blog" /* and the other entry pages */],
  },
},

crawlLinks makes Nitro follow every link from / and /blog during the build, so each post linked from the blog index gets prerendered without listing it. A crawler gets finished HTML from the CDN, with no server render on the first request.

/projects is different. It lists my GitHub repositories through the GitHub API, which allows 60 unauthenticated requests an hour. Rendering it on every request could hit that limit, and prerendering it would freeze the list until the next deploy. The isr: 86400 rule renders it on demand and caches it on Vercel's CDN for a day. Nuxt's docs say isr works on platforms with CDN caching, currently Vercel and Netlify.

Nuxt Content parses Markdown through @nuxtjs/mdc, which runs the rehype-external-links plugin with no options. That plugin's default rel is ["nofollow"]. So every external link in every post went out as rel="nofollow", including links to my own tools and repositories on other domains.

You override it in the plugin's options:

content: {
  markdown: {
    rehypePlugins: {
      "rehype-external-links": { options: { rel: ["noopener"] } },
    },
  },
},

Your rel replaces the default, so external links now get rel="noopener". Pass rel: [] if you want no rel at all. On Content v3 the same config sits under content.build.markdown.rehypePlugins.

To check, open a post, inspect an external link and look at its rel.

A 1200x630 share image

Posts with a thumbnail in their front matter use it as og:image. Everything else falls back to /og.png, a 1200x630 image made for link previews. Before, the fallback was my avatar, a 460x460 square that doesn't fit the wide preview cards. The pages set twitterCard: "summary_large_image" so X shows the large version too.

If you'd rather generate an image per page, nuxt-og-image renders them from a Vue component.

Should you just install @nuxtjs/seo?

For a new project, probably. npx nuxt module add @nuxtjs/seo installs nine modules together: robots, sitemap, schema-org, og-image, link checker, SEO utils, site config, skew protection and nuxt-ai-ready. This site installs the modules one by one, and the config is the same either way. The bundle won't fix the problems above for you, though. The <ContentDoc> head, the soft 404 and the nofollow default all needed code changes in my own pages.

If you're deciding between frameworks, I compared Nuxt vs Next as well. For another Nuxt walkthrough, see embedding a Metabase dashboard in a Nuxt app. And if you want this kind of audit done on your own Nuxt site, I'm available through hire.

FAQ

Is Nuxt good for SEO?

Yes. It renders HTML on the server by default, so crawlers get the content without running JavaScript, and it can prerender pages to static files. Just check the defaults: status codes, head tags from components and link attributes.

Does Nuxt generate a sitemap automatically?

Not on its own. The @nuxtjs/sitemap module generates /sitemap.xml from your pages, Nuxt Content documents and any URLs you add in config.

How do I set meta tags per page in Nuxt?

Call useSeoMeta() in the page's <script setup> for title, description and Open Graph tags, and useHead() for the canonical link and htmlAttrs.

Why does Search Console report soft 404s on my Nuxt site?

Usually because a dynamic route renders an empty page with status 200 when its data is missing. Throw createError({ statusCode: 404, fatal: true }) when the lookup returns nothing.

rehype-external-links adds rel="nofollow" by default. Set its rel option under content.markdown.rehypePlugins (Content v2) or content.build.markdown.rehypePlugins (Content v3).