Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 32 ยท Projects

Project: a blog with Nuxt Content style Markdown

Build a fast, SEO-friendly Nuxt blog from Markdown files: slug routes, useSeoMeta, a tags page and prerendering, with runnable Node stand-ins.

A blog is a great first Nuxt project, because it touches the features that make the framework worth using: file-based routes, content that is known ahead of time, per-page SEO tags, and pages you can prerender into plain HTML. You write posts as Markdown files, and the app turns them into fast pages.

In this project you set up the content, a catch-all route for posts, SEO tags, a tags page and prerendering. It combines Dynamic routes and params, Head, SEO and assets and Rendering modes. The Markdown part uses the official Nuxt Content module, in its current collection-based style. Module APIs move faster than the framework, so treat the code as a faithful sketch and check the module's own documentation for the exact version you install.

Real or stand-in? The Nuxt code below is real and read-only, because this site cannot run a Nuxt build. The runnable examples are Node.js stand-ins that do by hand what the framework and the module do for you: read Markdown posts with front matter, work out routes, tags and the prerender list, and render a page with its head tags and a 404.

What we are building

Markdown posts One file per post, with front matter.
Slug routes One catch-all page serves every post.
Tags page Posts grouped by tag.
SEO Title, description and canonical URL per page.
1 / 2
flowchart LR
    M["content/blog/*.md"] --> C["Content collection"]
    C --> L["Home page list"]
    C --> P["pages/blog/[...slug].vue"]
    C --> T["pages/tags/[tag].vue"]
    P --> H["Prerendered HTML"]
    T --> H

One collection feeds the list, the post pages and the tags pages. The build turns them into HTML.

Project structure

Terminal
# read-only
npx nuxi init my-blog
cd my-blog
npx nuxt module add content
TEXT
my-blog/
  content/
    blog/
      hello-nuxt.md
      why-nitro.md
  content.config.ts
  app/
    app.vue
    pages/
      index.vue
      blog/
        [...slug].vue
      tags/
        [tag].vue
  nuxt.config.ts

Each post has front matter, a block of metadata between two --- lines:

MARKDOWN
---
title: Why Nitro?
description: One server engine, many deployment targets.
date: 2026-02-03
tags: [nuxt, server]
draft: false
---

Nitro compiles your server for the place it will run.

## What you gain

- One codebase, many hosts
- Server routes without extra setup

The file path decides the URL: content/blog/why-nitro.md is served at /blog/why-nitro. That keeps the content folder simple and the URLs stable.

Step 1: define the collection

Recent versions of Nuxt Content describe content as collections in a config file, with a schema that checks the front matter. A post with a missing title then fails early instead of producing an empty page.

TypeScript
// content.config.ts (read-only)
import { defineCollection, defineContentConfig, z } from '@nuxt/content'

export default defineContentConfig({
  collections: {
    blog: defineCollection({
      type: 'page',
      source: 'blog/*.md',
      schema: z.object({
        date: z.string(),
        tags: z.array(z.string()).default([]),
        draft: z.boolean().default(false),
      }),
    }),
  },
})

type: 'page' means each file is a page with a path, title and description, and source says which files belong to the collection. The schema uses Zod, the same validation idea you will see again in Forms, validation and auth flows.

The first stand-in does the module's job without any packages. It parses front matter by hand, validates required fields like a schema would, drops drafts, sorts by date and then computes what the pages need: the routes, the tag index, and the list of paths a prerender would write.

Node.js From post files to routes, tags and a prerender list

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Three published posts give three post routes, and every tag found in them gives a tag route. The draft never reaches a route. A broken file stops the build with a clear message, which is the schema's job in the real module: validate early, fail loudly.

Step 2: the home page

The home page asks the collection for its posts, newest first. Auto-imports give you queryCollection and useAsyncData without any import line.

VUE
<!-- app/pages/index.vue (read-only) -->
<script setup lang="ts">
const { data: posts } = await useAsyncData('home-posts', () =>
  queryCollection('blog')
    .where('draft', '=', false)
    .order('date', 'DESC')
    .select('path', 'title', 'description', 'date')
    .all(),
)

useSeoMeta({
  title: 'My Blog',
  description: 'Notes on building with Nuxt.',
})
</script>

<template>
  <main>
    <h1>Latest posts</h1>
    <ul>
      <li v-for="post in posts" :key="post.path">
        <NuxtLink :to="post.path">{{ post.title }}</NuxtLink>
        <time :datetime="post.date"> {{ post.date }}</time>
        <p>{{ post.description }}</p>
      </li>
    </ul>
  </main>
</template>

select keeps the payload small: only the fields the list needs travel to the browser, not the full post bodies. That matters for performance, which you will see again in Performance and Core Web Vitals.

Step 3: the post page

One catch-all file serves every post. The [...slug] name captures the whole path, as described in Dynamic routes and params, and the module can find a page by its path.

VUE
<!-- app/pages/blog/[...slug].vue (read-only) -->
<script setup lang="ts">
const route = useRoute()

const { data: post } = await useAsyncData(route.path, () =>
  queryCollection('blog').path(route.path).first(),
)

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

useSeoMeta({
  title: post.value.title,
  description: post.value.description,
  ogTitle: post.value.title,
  ogDescription: post.value.description,
  ogType: 'article',
})

useHead({
  link: [{ rel: 'canonical', href: 'https://blog.example.com' + route.path }],
})
</script>

<template>
  <article v-if="post">
    <h1>{{ post.title }}</h1>
    <time :datetime="post.date">{{ post.date }}</time>
    <ContentRenderer :value="post" />
  </article>
</template>

Walk through it:

  • The key given to useAsyncData is the route path, so each post caches under its own key.
  • If no post matches, createError with fatal: true shows the error page with a real 404 status. A missing post must be a 404, not an empty page with status 200, or search engines will index nothing useful.
  • useSeoMeta sets the title, description and Open Graph tags. You can add a titleTemplate once in app.vue so each page only supplies its own part (Head, SEO and assets).
  • ContentRenderer renders the parsed Markdown. Raw HTML inside Markdown is not rendered unless you allow it, which is the safe default for posts written by many people.

The second stand-in plays the part of this page. It renders Markdown with a tiny, escaping converter, builds the head tags from the post, and answers an unknown path with a 404.

Node.js Render a post page with SEO tags and a 404

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first response shows the whole contract of a blog page: a unique title, description and canonical URL in the head, one h1, a machine-readable date and body headings shifted down one level. The <script> text in the post came out as &lt;script&gt;, escaped and harmless. The second response is the 404, with noindex so search engines do not list it.

Step 4: the tags page

A tags page filters the same collection. Because tags live in an array, one simple approach is to load the published posts and filter in the page:

VUE
<!-- app/pages/tags/[tag].vue (read-only) -->
<script setup lang="ts">
const route = useRoute()
const tag = String(route.params.tag)

const { data: posts } = await useAsyncData('tag-' + tag, async () => {
  const all = await queryCollection('blog')
    .where('draft', '=', false)
    .order('date', 'DESC')
    .select('path', 'title', 'date', 'tags')
    .all()
  return all.filter((post) => post.tags.includes(tag))
})

if (!posts.value?.length) {
  throw createError({ statusCode: 404, statusMessage: 'Unknown tag', fatal: true })
}

useSeoMeta({ title: 'Posts tagged ' + tag })
</script>

<template>
  <main>
    <h1>Tagged: {{ tag }}</h1>
    <ul>
      <li v-for="post in posts" :key="post.path">
        <NuxtLink :to="post.path">{{ post.title }}</NuxtLink>
      </li>
    </ul>
  </main>
</template>

Filtering in JavaScript is fine for a blog with hundreds of posts. A site with many thousands would query by tag in the database layer instead.

Step 5: prerender everything

A blog does not need a server to render pages on each request. Tell Nitro to prerender the site and follow links to find every page:

TypeScript
// nuxt.config.ts (read-only)
export default defineNuxtConfig({
  modules: ['@nuxt/content'],
  nitro: {
    prerender: {
      crawlLinks: true,
      routes: ['/', '/tags/nuxt'],
    },
  },
})

With crawlLinks on, the build starts from the listed routes and follows every NuxtLink it finds, so posts linked from the home page and tags linked from posts are all rendered. Tags that no page links to will not be found, so list them in routes or link to them from somewhere. Run nuxt generate for fully static output and put it on any static host, or use nuxt build with these rules if you also have server routes (Building and deploying Nuxt).

Ideas to extend the project

  • An RSS feed as a server route at server/routes/rss.xml.get.ts that returns XML.
  • A sitemap and robots.txt with the modules mentioned in Head, SEO and assets.
  • Newer and older links at the bottom of each post, using the neighbor idea from the first stand-in.
  • Image optimization for cover images with the image module.
  • Search over titles and descriptions, built from the same collection.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why is the post page named [...slug].vue in pages/blog/?

    The [...slug] catch-all matches any number of path segments. The page then looks up the content that belongs to route.path.
  2. 2. What should the post page do when no post matches the path?

    A missing post is a 404. A page with status 200 and no content can be indexed by search engines and confuses visitors.
  3. 3. What does nitro.prerender.crawlLinks do?

    The prerenderer starts from the routes you list and follows the links it finds in the HTML, so linked posts and tags are rendered too.
  4. 4. Why use select('path', 'title', 'description', 'date') on the list page?

    Without select, every full post body would be part of the data sent to the browser even though the list shows only titles and dates.
  5. 5. What is the benefit of a content schema in content.config.ts?

    The schema validates every post. A broken post stops the build instead of producing a half-empty page.

Summary

  • Store posts as Markdown files with front matter, and describe them with a content collection and a schema.
  • One catch-all page, pages/blog/[...slug].vue, serves all posts, and a missing post throws a real 404.
  • useSeoMeta and useHead give each page a title, description, Open Graph tags and a canonical link.
  • A tags page filters the same collection, so lists, posts and tags always agree.
  • Prerendering with crawlLinks turns the blog into static HTML. List any page that no link reaches in routes.
  • Use select to keep list payloads small.

Next: Project: a product catalog with cart