Less runtime. More website.

What does this website actually need to do?

Introduce projects, publish technical articles and invite people to contribute. The content changes when a new post or project update arrives, not on every page request. That makes it possible to generate the finished pages during the build.

The web server then delivers HTML and CSS. Visitors need neither an account nor a running server application to read an article.

Content is data with a contract

Titles, descriptions and dates should follow the same structure in every post. A Content Collection describes these fields and validates them during the build. This simplified example defines a collection of local articles:

import { defineCollection } from "astro:content";
import { z } from "astro/zod";
import { glob } from "astro/loaders";

const blog = defineCollection({
  loader: glob({
    base: "./src/content/blog",
    pattern: "**/*.{md,mdx}",
  }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
  }),
});

export const collections = { blog };

These entries power the listing, individual article pages and RSS feed. Metadata is maintained once and used in several places. The Astro Content Collections documentation explains the details.

Markdown first, MDX when needed

Markdown is enough for ordinary text. MDX adds the ability to include components directly in a post, such as this note:

This keeps recurring elements consistent without turning the writing process into a large page template. MDX files are part of the trusted source code: they can contain imports and executable expressions.

Where static sites reach their limits

A personal inbox, database writes or current account information require additional runtime logic. If a feature like that becomes necessary, it needs to be added deliberately. Reading project pages and articles only requires the static build.

Changes to publication dates need a new build too: a static site does not publish itself just because time has passed. A scheduled post appears after the next build following its publication date.

A small, straightforward workflow

1. Write a Markdown or MDX file.
2. Add its title, description, date and topics in the frontmatter.
3. Read and check it locally with npm run dev.
4. Run npm run build to validate content and types and generate static files.
5. Publish the contents of dist/ on the web server.

Fewer moving parts make it easier to focus on the actual work: good projects and clear writing.