Astro

Founders note: Astro is my new Jekyll. Jekyll has been my absolute preferred stack for a blog, a newsletter, or a CRM-facing site—and in the age of AI, when MD files are incredibly valuable for building systems that are highly responsive to new data and archival, Astro is just the next level up.

What Astro is

Astro is a JavaScript web framework optimized for content-driven websites. Server-first: it renders on the server and sends lightweight HTML to the browser with zero unnecessary JavaScript overhead.

If your public site is mostly articles, playbooks, landing pages, newsletter archives, and docs—not a logged-in dashboard on every route—Astro is built for that job. Content collections give you Markdown and MDX with TypeScript type-safety and frontmatter validation. Islands architecture means you bring React, Vue, or Svelte only where you need client-side interactivity; everything else stays static HTML.

It is built in Node. It is available as a package. And it takes Jekyll one step farther—same flat-file philosophy, modern tooling, and the option to drop React apps onto portions of the page to make them dynamic on the fly.

The Jekyll lineage — Tom Preston-Werner and the WordPress liability

Jekyll is a Ruby project that landed around the same time GitHub launched. Tom Preston-Werner—GitHub cofounder, still blogging at tom.preston-werner.com—wrote Blogging Like a Hacker about the fact that most blogs are built in WordPress and have way too much power under the hood. They end up becoming liabilities when they have become untended—plugins, databases, attack surface, and a CMS nobody maintains.

The developer answer was always a flat-file, renderable templating system that runs locally but generates super-fast HTML. No database. No server required for the read path. Just HTML stored and rendered through a Git project.

My first website, Stephen Smith Solutions, was entirely static. There was no reason for a database. There was no reason for a server. It was just HTML stored and rendered through a GitHub project. Astro is the next step up from that model—not a retreat from it.

MD files in the AI age

In the age of AI, MD files are not nostalgia—they are infrastructure. When your content lives as Markdown in the repo, agents can read it, validate it, cross-link it, and extend it without scraping a CMS or reverse-engineering a database schema. You get archival that stays responsive to new data: drop a transcript in content-source/, assemble to MDX, publish, and the whole system stays coherent.

That is why flat-file publishing keeps winning for founders who publish—not because databases are bad, but because words belong in files when AI is part of the editorial loop.

Why devs skip it

Most developers default to Next.js or reach back to WordPress because it is familiar. Resume comfort, tutorial gravity, “that is what startups use.” Next is the right call when every page is an app. WordPress is the wrong call when your blog will sit untended for six months and become a plugin liability.

Astro does not look like the shiny app framework on Hacker News. It looks like “just HTML.” That simplicity is the power—static HTML, which is super fast, highly secure, and cheap to host at the edge.

Next.js vs Astro — when you need an app shell

Next.js is the right tool when you need server actions, deep auth middleware, and a unified app shell on every route. Astro is the right tool when you need Core Web Vitals without a performance project—marketing pages, build-in-public logs, playbook entries, newsletter archives, docs.

You are not locked out of React. This site uses @astrojs/react for interactive components; they hydrate as islands. You are choosing where JavaScript ships, not whether you can use your favorite UI library.

How we use it

I built my entire newsletter on top of Astro. I do not have multiple writers. I do not have to change content on a CMS schedule. I set up my content systems and render them out. It is entirely fast and reactive—and then I use React apps to make portions of it dynamic on the fly.

On Fractional.tools, the marketing site is built in Astro—it handles the public website and is hosted on Cloudflare. It generates static HTML, which is super fast and highly secure. The product UI is React on Cloudflare; the API runs on Fly.io; data and auth sit on Supabase. Astro owns the content surface, not the logged-in product.

This site—stephansmith.me, including the playbook you are reading—is the same pattern: Astro 6, MDX content collections, Tailwind, Cloudflare Pages on push to main. See the Fractional.tools tech stack map for how Astro sits next to Fly, Supabase, and Inngest in production.

At a glance

• What it is: Jekyll’s successor in Node—server-rendered HTML, MDX/Markdown collections, islands for interactivity, deploy adapters for Cloudflare and peers.
• Best for: Blogs, newsletters, playbooks, docs, build-in-public hubs—anything where most pages are words, MD is your source of truth, and SEO/speed matter.
• Not a fit: A product that is a single authenticated SPA on every route, or a multi-writer CMS with daily in-browser editing—reach for a different layer.
• Pairs with: Cloudflare for DNS and Pages hosting, Supabase for data behind the static shell, Inngest for jobs triggered from forms or webhooks, Cursor for building and editing the MD archive agents read.

When to reach for it

Reach for Astro when your site is content, not app chrome—and when you want the Tom Preston-Werner/Jekyll bet: flat files, local build, HTML out, no untended WordPress under the hood. If your co-founder wants “the same stack as everyone else,” tell them MD in git is now AI-ready infrastructure, static HTML means faster pages and lower burn, and you can still drop React where the page actually needs to move.

Watchouts

Content collection schemas and astro:content loaders are the one-time unwrap—worth reading the docs once before you let the agent invent frontmatter. Client directives (client:load, client:visible) are easy to overuse; default to zero JS and add islands surgically. If you need edge middleware auth on every request, plan that layer explicitly—Astro supports it, but it is not the “mostly static” happy path.

See it in the stack: Fractional.tools · tech stack map

Related playbook entries

• Cloudflare — DNS, Pages, and Workers; where this site and Fractional.tools static shells live.
• Fly.io — API and edge compute; Astro handles the public marketing layer.
• Supabase — Postgres and auth behind content sites and product UIs.
• Inngest — background jobs when your static site triggers work via API or webhooks.

AI prompts for vibe coding

Addendum — the rocket A

The Astro mark is a lowercase wordmark and a rocket-ship A on navy—content framework branding that does not pretend to be an enterprise app suite. Same irrational confidence Jekyll had: your blog does not need a database. I love that.

Astro logo — flat files in, HTML out, rocket on the letter A. My new Jekyll; the site you are reading runs on this stack.