A technical blog has requirements that are simple and demanding at the same time: it has to be fast, indexable, easy to write for and cheap to host. After trying headless CMSs, databases and ready-made platforms, I went back to the oldest and sturdiest format there is: markdown files in a repository, turned into static HTML at build time.
This post shows how the site you're reading was put together.
The stack
- Nuxt 4: the framework, with server rendering and static generation;
- Nuxt UI 4: components and the theme system (colors, typography, dark mode);
- Nuxt Content 3: turns the
content/folder into a typed, queryable database; - Tailwind CSS 4: utility styling, with the brand tokens defined in CSS.
Everything is prerendered. There is no server in production: just HTML files on a CDN.
export default defineNuxtConfig({
modules: ['@nuxt/ui', '@nuxt/content'],
// Fully static: fast, cheap and indexable
routeRules: { '/**': { prerender: true } }
})
Typed collections
Nuxt Content 3 works with collections: you declare where the files come from and the shape of the frontmatter. Got a field wrong? The build tells you.
export default defineContentConfig({
collections: {
blog: defineCollection({
type: 'page',
source: 'blog/*.md',
schema: z.object({
date: z.string(),
segment: z.enum(['engenharia', 'produto', 'dados', 'marketing', 'negocios']),
category: z.string(),
tags: z.array(z.string()).default([]),
featured: z.boolean().default(false),
draft: z.boolean().default(false)
})
})
}
})
Querying feels like writing SQL, only typed:
const posts = await queryCollection('blog')
.where('draft', '=', false)
.where('segment', '=', 'engenharia')
.order('date', 'DESC')
.select('title', 'description', 'path', 'date')
.all()
The select matters: in lists, only the card's fields go into the page payload, without the article bodies.
Segments and categories
The blog has two levels of organization. Segments are the big topics (Engineering, Product, Data, Marketing, Business), each with its own color, icon and page. Categories live inside a segment (Architecture and Front-end in Engineering, Discovery in Product, and so on).
The definition lives in a single TypeScript file that feeds the menu, the filters, the colors and a script that checks every post uses a segment and a category that exist. One source of truth, no duplicated lists.
Reading time calculated at build time
Instead of asking the author to fill it in, reading time is calculated in a Content hook, from the raw markdown, ignoring code blocks:
hooks: {
'content:file:afterParse'({ file, content }) {
if (!file.id.startsWith('blog/')) return
const text = String(file.body).replace(/```[\s\S]*?```/g, '')
const words = text.split(/\s+/).filter(Boolean).length
content.readingTime = Math.max(1, Math.round(words / 220))
}
}
That way the value goes into the database and lists can show it without loading the text.
Covers generated by code
Producing an image for every post is the kind of chore that makes a blog stall. Here, each cover is an SVG drawn by a Vue component: one drawing per segment (lines of code, rings, bars, waves, a network), in the segment's color, with variations taken from the title by a deterministic generator. Same title, same cover, on the server and in the browser.
The result: zero images to produce, zero bytes of JPG, and every post carrying the site's visual identity.
Search and filters without a server
The blog page is prerendered with every post. The filters (segment, category, search) run in the browser, ignoring accents and case, and go into the URL so a filter can be shared. For a few dozen or a few hundred posts, it's instant and needs no search service.
Real SEO
Static doesn't mean forgotten by search engines, quite the opposite. Every page has:
- its own
title,descriptionand Open Graph; - a canonical pointing to the clean URL;
- JSON-LD with
Personon the site andBlogPostingon every article; - sitemap.xml and rss.xml generated by server routes and prerendered at build time.
Writing a post
In the end, writing means creating a file:
---
title: 'Post title'
description: 'One sentence that makes people want to read.'
date: '2026-11-12'
segment: engenharia
category: frontend
tags: [nuxt, vue]
---
The text in markdown, with **bold**, lists, tables and code blocks.
Commit, push, and the deploy generates the HTML. No dashboard, no database, no plugin to update.
Conclusion
For a personal or company blog, versioned markdown and static generation are still unbeatable on cost, speed and durability. Nuxt Content 3 adds what was missing: types, queries and an integration with the interface that makes the result feel like a product, not a template.
Murilo Anzini
Hands-on writing on engineering, product, data and marketing for people who want to understand, and build, the whole journey of a product.