When I rebuilt this site I figured I’d either pay a developer or spend a weekend on WordPress plugins. I did neither. I told Claude what I wanted, it wrote the files, and the site’s been live since August. I’ve never logged into an admin panel since.
And the only thing I knew how to do going in was buy a domain and poke around a hosting panel. If you’ve ever pointed a domain at a host in Hostinger or GoDaddy, you can do this.
Everything else, the AI does. The rest of this is how to set it up so you can still run it in six months.
First, what Astro is
Astro takes a folder of text files and turns them into a finished website.
You write a page, Astro builds it into plain HTML, and your host hands that file to visitors.
People call this a static site. It’s how websites worked before WordPress, and it came back because most websites never needed a database in the first place.
Two more words you’ll run into.
GitHub is where the folder lives. It’s Google Drive for code, except it keeps a note on every single change, who made it and when, and you can undo any of them.
A build is the step where Astro turns your text files into the website. Your host does it for you every time you save.
Why not just use a CMS
A CMS is WordPress or Squarespace or Webflow. You log in, click into a page, type, hit publish. Your content sits in a database and gets assembled into a page every time somebody visits.
I’m not anti-CMS. I’ve built plenty of sites on them and for a lot of businesses it’s still the right call. But here’s what you’re giving up.
There’s a lot to hack. A CMS has a login page, a database, and a pile of plugins. Every one of those is a way in. A static site has none of it. There’s no login page on this site because there’s nothing to log into.
Plugins break. One updates, your contact form stops sending, and nothing tells you.
Leaving means rebuilding. Move off Squarespace and you start over. Move an Astro site and you copy a folder somewhere else.
And the big one, an AI can’t see your CMS. Your content is stuck in a database behind a login. Ask ChatGPT to help rewrite your services page and you’re pasting text into a box and pasting it back out. When the site is text files, the AI reads every page at once. It’ll catch that a price on one page doesn’t match the same price on another and fix both. It can add a page that links into your navigation correctly, because it can see the navigation.
That last one is why I’d do it this way again.
What GitHub gets you
Astro’s a good tool, but Eleventy or Hugo would work too.
What matters is that your website is a folder of text and every change to it gets recorded. You get four things out of that:
-
You ask for changes in plain English. “Put this testimonial on the pricing page, under the FAQ.” The AI finds the page and matches the formatting of the ones already there.
-
You can undo anything. Every change is a saved point with a note attached, and you can go back to any of them.
-
You own it. The folder is yours. No platform can shut it off, jack up the price, or make you rebuild to leave. Same rule I use on everything I build for a client: if you can’t run it without me, I shouldn’t have built it that way.
-
The AI gets better at your site over time. You can leave notes for it in the folder, which I’ll get to, and it reads them before it touches anything.
I’ve said the same thing about building your own automations instead of renting somebody else’s and about letting AI do the work instead of advise on it.
How the AI walks you through it
“The AI does it” covers a lot. Here is what it looks like.
You’ll use a coding assistant. Claude Code, Cursor, ChatGPT’s Codex, they all do this job. The difference between one of those and a normal chat window is that it can read and change files on your computer and run commands for you. You don’t type anything into a black terminal window. You say “start the preview so I can look at it” and it does.
So every round goes:
- You tell it what you want.
- It writes or changes the files.
- It starts a preview and gives you a web address like
localhost:4321. - You open that in your browser and look at your site.
- You tell it what’s wrong. “The heading’s too big.” “Wrong shade of orange.” “This one’s fine.”
You’re the one looking at the screen deciding whether it’s right, same as you would be with a designer.
Where people go wrong is trying to get the whole site in one go. “Build me a website” gets you something generic you can’t really react to. “Build me the homepage, hero section only, headline and one button” gets you something you can look at and have an opinion about. Same reason I only vibe-code things with a tiny surface area.
Write a spec first
A website is too big for one prompt. You end up with a wall of text nobody can read back, the AI loses track of most of it, and when you change your mind there’s nowhere to go and change it.
So for anything this size I write a spec first. It’s a plain document that says what the thing is and what the rules are:
- Every page, and one line on what each one is for.
- What you want a visitor to do.
- The rules that apply everywhere. Colors, how the navigation works, how you write.
- What you’re not building.
The AI reads the document instead of a prompt, and it can go back and read it again whenever it needs to. When I change my mind I change the document.
The other half is the mockup. Before any of this got built I mocked up the whole site in Claude Design, page by page.
The spec and the mockup were most of what the AI got. The prompt at the bottom of this post is the rest of it: the technical stuff that’s the same no matter what your site is.
Write your own copy too. The AI is good at structure and bad at sounding like you.
The steps
1. Install the coding assistant and hand over the spec
Give it your spec, your mockup and the prompt from the bottom of this post, in that order. It reads all three before it writes anything, then builds a page at a time so you can look at each one.
It’ll want you to install a couple of things first. Node, mainly, which is what Astro runs on. Let it walk you through that instead of Googling it.
2. Look at it, react, repeat
Ask for the preview, open the address it gives you, and go page by page.
The one people forget is phone width. Drag your browser window in and look at every page again.
3. Put it in GitHub
The AI does this. You need a free GitHub account and you click “create repository” once. Keep it private if you want, mine is.
4. Point your host at it
On Hostinger it’s a Web App deployed from GitHub. Framework preset Astro, branch main, Node version 22, build command npm run build, output directory dist, entry file blank. Netlify, Vercel and Cloudflare Pages have the same three or four fields under different names, and they all have a free tier.
Then you attach your domain like you would to anything else and turn on Force HTTPS in the panel.
After that, saving a change to main is publishing.
What we learned building this one
All of this is in the prompt at the bottom, but you’ll get more out of it knowing why.
Keep a file of things that are easy to get wrong. This repo has a CLAUDE.md in it and every coding assistant reads a file like that before it starts. Mine has the stuff you only learn by breaking it: which greys work on a dark background and which work on a light one, that the nav bar is full and an eighth item wraps, that pushing to main is a deploy. Every time I found one the hard way it went in the file, and no AI has made that mistake since.
Make the computer check the things you’ll forget. Ask for checks, not just pages. This site refuses to build if a page is missing a title or description, if a page has two main headings, if an internal link points at a page that doesn’t exist, or if the site map disagrees with the pages. I don’t remember any of those rules and I don’t need to, because the build stops and tells me.
Branch before you change anything meaningful. Pushing to main publishes, so you want the AI working on a copy. Tell it to branch, look at the result, then merge. If it comes back wrong you delete the branch and nothing ever reached your site.
Keep your images in the repo. Not linked in from somewhere else. A hosted image is one more thing that can move, get blocked, or stop loading. Every image on this site ships with the site.
Add as few outside scripts as you can stand. There’s one on this site, HubSpot, for tracking and the cookie banner. No tag manager. A tag manager is a box where anybody with the password can put code on every page of your site with no record of it, and you can just skip that. While we’re on HubSpot, most of what people upgrade for can be done without upgrading.
Publish a plain-text copy of your site for AI. Ours is at /for-your-ai: every page dumped into one text file, generated from the built site, so it can’t go stale on me. It’s what ChatGPT reads when somebody asks about us.
Where this is a bad idea
Three of them.
You need logins or a store with inventory. Static sites don’t do user accounts. You can add Shopify or Stripe for checkout, but if people logging into your site is the core of the business, go get a platform.
Somebody non-technical has to publish daily and won’t touch an AI. If your marketing coordinator posts three times a week and is never going to open a coding assistant, you’re building a workflow nobody will use.
You want it done this afternoon and you don’t care what it looks like. Squarespace, one hour. That’s a fine answer for plenty of businesses.
Otherwise, for a services site, a consultancy, a portfolio, a product marketing site with a blog, I’d do it this way.
The prompt
This is the technical half, and it’s the same for everybody. Your spec is the half that’s yours. Fill in the bracketed parts, delete the examples, and paste it into Claude Code, Cursor, or Codex in an empty folder on your computer.
You are building a website for me. I am not a developer. I can buy a
domain and find the settings in a hosting panel, and that is the limit
of what I know how to do.
I am also giving you a spec document and a mockup of the site. Those
two are the source of truth for what the site says and how it looks.
Where this message and the spec disagree, ask me. Everything below is
how to build it, not what to build.
Read all of it before you do anything. Then confirm the plan back to
me in plain English and wait for me to say go.
=== ABOUT THE SITE ===
(If your spec already covers this, say so and skip it.)
Business: [what you do, one or two sentences]
Who it is for: [your customer]
What I want a visitor to do: [book a call / buy / subscribe]
Tone: [e.g. direct and plain, no marketing hype]
Pages I want, and what each one is for:
- / [homepage: what it should make somebody do]
- /[page] [what it is for]
- /[page] [what it is for]
- /blog [an index plus individual posts]
- /contact [what happens here]
Brand: [colors if you have them, fonts if you have them, or say you
do not and ask me to pick from what you suggest]
Domain: [yourdomain.com]
Host: [Hostinger / Netlify / Vercel / Cloudflare Pages]
I will write the words on every page. Do not write marketing copy for
me. Use obvious placeholder text where my copy goes, and ask me for it
section by section as we build.
=== HOW TO WORK WITH ME ===
1. One piece at a time. Build one section of one page, show me, wait
for my reaction. Never build five pages and then ask what I think.
2. Explain every technical word the first time you use it, in one
sentence, in words a non-technical person understands.
3. Run every command yourself. Do not hand me a command to paste
unless there is no other way, and if there is no other way, tell me
what it is going to do and what I should see when it works.
4. When you need a decision from me, give me your recommendation and
why, not a menu of five options.
5. If I ask for something that will cause a problem later, say so
before you build it.
6. Never publish anything without asking me first.
=== THE TECHNICAL SETUP (build it this way) ===
Framework: Astro, static output, TypeScript in strict mode, Tailwind
for styling. Pin every dependency to an exact version, no version
ranges, so my site cannot change on its own.
Structure:
- One shared layout that every page uses.
- That layout requires a page title and a meta description as
mandatory inputs. A page that does not supply both must fail the
build rather than ship with an empty tag. Title 62 characters or
less, description between 50 and 158.
- Every page emits a self-referencing canonical URL, Open Graph and
Twitter card tags, and a 1200x630 PNG or JPG preview image. Never
emit meta keywords.
- Blog posts are Markdown files in a content collection with a schema
that validates the frontmatter, so a post with a missing or
over-long description fails the build instead of shipping.
- Structured data (JSON-LD) is ONE entity graph shared across the
whole site, not a separate snippet per page. Define my organization
and me as people/org entities once, and have pages reference those
entities by ID rather than repeating them. Two nodes describing the
same person is two people to a search engine.
- Generate a sitemap and an RSS feed from the pages themselves, never
a hand-maintained list.
- robots.txt allows the AI crawlers by name (GPTBot, ClaudeBot,
PerplexityBot, Google-Extended and the rest), not just by wildcard.
- Also generate a plain text version of the whole site for AI tools:
an llms.txt index plus one .md file per page, generated from the
BUILT pages so they can never drift from what is published. Never
hand-write these summaries. If the files get large, split them by
topic, because AI fetch tools silently truncate long pages at around
25,000 tokens.
Links, images and scripts:
- Internal links are written as paths (/pricing), never as full URLs,
so a link checker can catch one pointing at a page that does not
exist.
- Every image, font and logo lives in the repository and is processed
by the build. Nothing is hotlinked from another site.
- No tag manager. Add third-party scripts one at a time, only when I
ask, and tell me what each one costs me in speed and privacy.
- No API keys, passwords or tokens anywhere in the files, ever, not
even temporarily.
Accessibility and color:
- Every text color must clear 4.5:1 contrast against the background it
actually sits on. Check this with real numbers, do not eyeball it.
- If the site has both dark and light sections, work out one set of
greys per background and write down which set goes where. A grey
that passes on one will usually fail on the other.
- Exactly one h1 per page.
=== CHECKS I WANT YOU TO BUILD ===
Write scripts that run after the build and FAIL it if any of these are
true. I will not remember these rules, so the computer has to.
- A page is missing a title, description or canonical.
- A page has zero or more than one h1.
- Two pages share a title or a description.
- An internal link points at a page that does not exist, including a
post still marked as a draft.
- The sitemap and the canonical URLs disagree.
- A page is missing from the AI text files.
- Any page renders with an empty body.
Add a GitHub Action that runs the same build on every push, so a
broken build shows up in a log I can read instead of on my live site.
=== WRITE THINGS DOWN ===
Create a CLAUDE.md in the root of the project. It is not documentation
of everything. It is only the things that are easy to get wrong and
expensive to find out about later. Every time we hit one of those,
add it. Start it with:
- what publishing looks like and which branch does it
- the single command that runs all the checks
- which colors are legal on which background
- any limit in the design that will break if we add one more thing
(a navigation bar that is full, for example)
Also write a README with how to run it, and a deploy file with the
exact host settings once we have them working.
=== HOW WE PUBLISH ===
- Pushing to the main branch is the deploy. Treat every push to main
as publishing to the live internet.
- So: work on a branch, show me, and only merge to main when I say so.
- Before any push, run the full check command and show me it passed.
- Never force push. Never rewrite history.
=== GOING LIVE ===
When we are ready to connect the domain, give me the exact settings to
enter in my hosting panel, field by field, and then check these
against the LIVE address, not against my computer:
1. The live robots.txt is our file and not the host's default, which
on some hosts blocks Google entirely.
2. No page is sending an X-Robots-Tag: noindex header. Use a cache
buster on the URL so you are not reading a cached copy.
3. Every page returns 200, URLs are consistent, and the 404 page works.
These cannot be checked from the built files on my machine, so they
have to be checked against the live site, by hand, at launch. Put that
list in the deploy file so we run it again after any change to hosting
or the domain.
=== START HERE ===
Do not write any code yet. First, tell me back:
- the page list you understood, and what each page is for
- what I need to install on my computer before we start, and walk me
through installing it
- what the first thing you are going to build is
Then wait for me.
Where I’d start
Open a blank document and write the spec. Every page, one line each on what it’s for, what you want a visitor to do, and the rules that apply everywhere.
Then mock it up, buy the domain if you don’t have one, install Claude Code or Cursor, and hand over all three.
If you get stuck partway through, or you get it live and want somebody to tell you what’s wrong with it, book 30 minutes. I’m curious what people are running into with this.