Building a Website with Astro + Cloudflare Pages

A complete beginner's guide, written so anyone can follow it.

Before you start — pre-flight checklist

Tick these off in your head before you sit down to do this:

Start here: set Claude up, then let it walk you through this whole guide

This is the most important thing on the page, so do it first. You do not have to follow this guide alone. You can hand the entire guide to Claude and have it walk you through every step, one message at a time, in plain English — checking in with you before each next step, and helping the moment anything looks confusing. Setting this up takes about two minutes.

Step 1 — Open Claude

1. Go to claude.ai in your web browser.
2. Sign up, or log in if you already have an account. The free plan is fine for this part.
3. Click New chat to start a fresh conversation.

Step 2 — Give this guide to Claude

1. Find this guide file on your computer (the PDF or web page you are reading right now).
2. Drag it into the chat box — or click the paperclip (or +) icon and choose the file.
3. Wait a few seconds for it to finish uploading.

Step 3 — Ask Claude to be your step-by-step guide

Copy the message below and paste it to Claude exactly as it is. This tells Claude to lead you through the whole thing:

From now on, any time you're unsure what to do, just tell Claude where you are and it will help. Between this guide and Claude, there is genuinely no point where you have to work it out on your own.

How to use this guide

This guide is designed two ways at once: as something you can read end-to-end to understand what you're building, OR as something you can skip through to just get the site up. Pick the one that fits how you learn.

Path A — I want to understand what's happening

Read Chapter 1 first for the big picture, then the Reference section at the back for the technical details (what each tool is, how to read the Terminal, common surprises). Then come back and follow chapters 2 through 12 in order. The whole guide takes about 20 minutes to read.

Path B — I just want to get my site up

Skip straight to Chapter 3 (Setting up your project on your computer). Follow the steps in order. If you hit something confusing, the explanations are waiting for you in the Reference section at the back — or just ask Claude.

1. What you're building (the big picture)

A website is a collection of files (HTML, CSS, images, JavaScript) that live on a computer connected to the internet 24/7. When someone types your address into a browser, that computer sends them the files. They see your website.

The setup we're using is called a static site:

• Your website pages are pre-built into plain files on your laptop
• Those files get uploaded to a hosting service that puts them on the internet
• The hosting service is free because static files are cheap to serve
• Changes happen by editing the source files and uploading them again

That's the big picture. The setup uses a handful of free tools behind the scenes, but you don't need to understand any of them to follow this guide. If you ever want to know what each tool does, the descriptions are in the Reference section at the back.

Ready? Let's get you set up.

2. Before you start — checklist

You'll need:

• A Mac (this guide is written for macOS; Windows is similar but slightly different)
• An internet connection
• About 30–60 minutes for the initial setup
• A GitHub account (free — sign up at github.com)
• A Cloudflare account (free — sign up at cloudflare.com)
• Optional but recommended: your domain name (you can use Cloudflare's temporary URL until then)

3. Setting up your project on your computer

Step 1 — Install Node.js

Node.js is a small piece of software your Mac needs before we can do anything else. You install it once, the same way you'd install any normal Mac app, and then never have to think about it again. Takes about two minutes.

1. Open your web browser (Safari or Chrome).
2. Go to nodejs.org.
3. You'll see two big green download buttons. Click the one labelled LTS. (LTS stands for "Long Term Support" — the stable version. The site automatically gives you the right file for your Mac.)
4. The file downloads. It'll be called something like node-v20.x.x.pkg. Open it from your Downloads folder.
5. A familiar Mac installer window opens. Click Continue → Continue → Agree → Install. Type your Mac password when prompted.
6. When it says "The installation was successful," click Close. Node.js is now on your Mac.

Step 2 — Open Terminal

Terminal is the small window where you'll type a few short commands. You don't need to learn anything about it. Just open it and follow along.

1. Press Cmd + Space. A search bar appears in the middle of your screen.
2. Type Terminal.
3. Press Enter.

What you should see:

A small white window with black text. Three coloured dots top-left. The first line is just a greeting. The second line ending in % is where you type.

Step 3 — Check that Node.js installed correctly

Quick sanity check. Click anywhere inside the Terminal window so it's active. Type this exactly, then press Enter:

node --version

You should see something like v20.11.0. If you do, Node is installed and working. If you see "command not found," ask Claude — most likely the install didn't finish.

Step 4 — Tell Terminal to work on your Desktop

We'll put your project folder on your Desktop so it's easy to find later. Type this and press Enter:

cd ~/Desktop

Nothing visible happens. That's normal. You've just told Terminal "from now on, work in the Desktop folder."

The second line shows "Desktop" instead of "~" — that means you're now in the Desktop folder. Correct.

Step 5 — Create your website project

This is the satisfying one. With one command, Astro creates a new folder on your Desktop and fills it with everything needed for your website. Type this and press Enter:

npm create astro@latest

Astro will print some text and then ask you a few questions one at a time. Answer them like this:

It takes a couple of minutes. When it's done, you'll see something like "Liftoff confirmed!" and a new folder will appear on your Desktop.

Step 6 — Add Tailwind

Tailwind is a small add-on that makes styling your colours and fonts easier in the next chapter. We add it now while we're set up. First, move into your new project folder:

cd "DTI website"

(If you named your project something else, use that name instead of "DTI website".) Then install Tailwind:

npx astro add tailwind

It'll ask "Continue?" — type y and press Enter each time it asks.

Step 7 — Start your website on your laptop

Last step. This starts your website running on your own laptop so you can see it in your browser. Type this and press Enter:

npm run dev

It prints a URL like http://localhost:4321. Click that link (or copy it into your browser). You'll see your blank website running on your own machine. Only you can see it — that's correct, it's not on the internet yet.

To stop the local server later, press Ctrl + C in Terminal.

Step 8 — Install Claude Code (your website builder)

Claude Code is the tool that will actually build and edit your website for you. You talk to it in plain English and it writes the files. You install it once, right now, while Terminal is already open.

First, if your website preview from Step 7 is still running, stop it: click the Terminal window and press Ctrl + C. Then type this and press Enter:

npm install -g @anthropic-ai/claude-code

It takes about a minute. When it finishes and you see the % prompt again, start Claude Code by typing:

claude

The first time, it opens your browser to log in to your Claude account. Approve it, come back to Terminal, and you'll see a > prompt where you type your requests to Claude. That's Claude Code, running right inside your project folder. To leave it later, type /exit (or press Ctrl + C twice).

4. Configuring colours and fonts (Tailwind)

Your brand colours and fonts are set in one place inside your project. You don't need to know which file that is, and you don't need to open or edit it yourself. Claude Code does it for you.

Start Claude Code if it isn't already running (type claude in Terminal, inside your project folder), then say something like:

Claude finds the right styling file for your setup, makes the change, and tells you the colour names you can now use (for example bg-brand-plum for a plum background, or text-brand-gold for gold text). From then on, whenever you want those colours somewhere, you just ask Claude Code and it applies them.

5. Building the pages

What your project folder looks like

Before we touch anything, here's a map of what's inside your new DTI website folder. Don't memorise this — just glance at it so the words make sense when they come up.

DTI website/
├── public/              ← images and downloadable files
│   └── images/             you'll drop your photos here
├── src/
│   ├── pages/           ← one .astro file per page
│   │   ├── index.astro      = your home page
│   │   ├── about.astro      = /about page
│   │   └── pricing.astro    = /pricing page
│   ├── layouts/
│   │   └── Base.astro   ← the shared wrapper (nav + footer)
│   ├── components/
│   │   ├── Nav.astro    ← reusable nav at top of every page
│   │   └── Footer.astro ← reusable footer at bottom of every page
│   └── styles/
│       └── global.css   ← YOUR COLOURS AND FONTS (Claude edits this)
├── astro.config.mjs     ← Astro's main settings
├── package.json         ← list of installed tools
└── node_modules/        ← installed code (DO NOT TOUCH)

Your pages live in src/pages/. Each .astro file is one page. The file name becomes the URL:

• src/pages/index.astro → the home page
• src/pages/about.astro → the /about page
• src/pages/services.astro → the /services page

Reusable pieces (Nav, Footer) live in src/components/ and get imported by each page. Your overall page wrapper (the thing that puts the Nav at top and Footer at bottom) lives in src/layouts/Base.astro.

6. Getting your site live (GitHub + Cloudflare)

Step 6.0 — Sign up for GitHub and Cloudflare (if you haven't already)

Both are free. Both take less than two minutes. You sign up the same way you'd sign up for any normal website — email and password.

GitHub:

1. Open github.com/signup in your browser
2. Enter your email → create a password → pick a username (this becomes part of your URLs, so choose something businesslike)
3. Verify with the puzzle they give you
4. Check your email and click the verification link

What GitHub looks like once you're logged in: a mostly white dashboard with a list of your "repositories" on the left. Repositories (or "repos") are just project folders stored online. You'll have zero to start. We'll create your first ones in Step 6.1.

Cloudflare:

1. Open dash.cloudflare.com/sign-up in your browser
2. Enter your email → create a password
3. Verify your email
4. You don't need to enter a card. The free tier doesn't ask for one.

What Cloudflare looks like once you're logged in: a dashboard with orange and white branding. Left sidebar has options including "Workers & Pages" — that's where we'll go in Step 6.3.

Step 6.1 — Create your GitHub repo

Go to github.com and sign in. Click the + icon in the top-right → New repository. Name it something like yoursite-website (private is fine). This one folder is your whole website, and it's what Cloudflare will watch.

Step 6.2 — Connect your local project to GitHub

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Now, in Terminal, inside your project folder, run these (replace YOURUSERNAME with your GitHub username):

git remote add origin https://github.com/YOURUSERNAME/yoursite-website.git
git add .
git commit -m "Initial commit"
git push origin main

Once that push succeeds, your code is on GitHub.

Step 6.3 — Set up Cloudflare Pages

1. Go to dash.cloudflare.com and sign in
2. Click Workers & Pages → Create application → Pages → Connect to Git
3. Authorise Cloudflare to access your GitHub
4. Select your yoursite-website repo
5. Settings:
   • Framework preset: Astro
   • Build command: npm run build
   • Build output directory: dist
   • Branch: main
6. Click Save and Deploy

Below is a simplified layout of each Cloudflare screen — what buttons to look for and what to click. The real Cloudflare interface uses orange and white branding and looks more polished, but the labels and buttons are the same.

Step 6.4 — See your site live

You're already done — the push you did in Step 6.2 is exactly what Cloudflare just built. Wait about 60 seconds, then visit the your-site-abc.pages.dev URL Cloudflare gave you (it also emails it to you). Your site is live on the internet.

7. Pointing your domain at the new site

If you have your own domain (e.g. yourbusiness.co.nz) you'll change its DNS settings so visitors land on your Cloudflare-hosted site instead of wherever it used to point.

If you'd rather add records by hand instead of moving nameservers, here's that path:

1. In Cloudflare Pages, open your project → Custom domains → Set up a domain
2. Enter your domain name → Cloudflare gives you DNS records to copy
3. Log in to your domain registrar (the company you bought your domain from)
4. Find DNS settings → add the records Cloudflare gave you
5. Save. Propagation takes a few minutes to a few hours

8. Cancelling your old hosting (Webflow, etc.)

Only do this AFTER your new site is fully working at your domain.

Cancelling Webflow:

1. Log in at webflow.com
2. Click your profile (top-right) → Workspace settings or Site settings
3. Go to Billing or Plans
4. Find your active plan → Cancel plan or Downgrade to free
5. Confirm cancellation; note the renewal date — you'll still have access until then

You can also export your Webflow site as a backup before cancelling (Settings → Export → ZIP). Useful if you want to keep the design files.

9. How to update your site going forward

Once everything's set up, normal updates are this short:

1. Open Terminal, navigate into your project folder: cd ~/Desktop/yourproject
2. Start a Claude Code session
3. Tell Claude what to change in plain English
4. Claude edits the files
5. Run git add . then git commit -m "what you changed" then git push origin main
6. Wait ~60 seconds. Cloudflare rebuilds. Done.

10. What else your website can do

This kind of website can do almost everything most small-business sites need. Here are the common questions, with the simple answer for each.

Can I add new pages?

Yes, and it's easy. Tell Claude Code "add a page called Pricing" (or About, Services, Gallery, anything). Claude creates the page, links it from your navigation, and you can fill in the content. New pages take about a minute each.

Will my site work on phones and tablets?

Yes, automatically. The way this site is built (Astro + Tailwind) handles phone, tablet, and laptop screen sizes for you. When you tell Claude Code to add or change a section, the result is responsive by default. You can check by opening your site in your phone's browser, or by shrinking your laptop browser window — the layout adjusts on its own.

How do I add photos?

Drop the photo files into the public/images folder inside your project. Then tell Claude Code where you'd like them: "use beach-shoot-1.jpg as the hero image on the home page," or "add the three portrait photos to the About page."

Photos live on your site and load from Cloudflare's fast global network — no extra service needed for normal amounts. If you ever build a huge gallery (hundreds of large photos), Claude can help you switch to a dedicated image host like Cloudinary or Bunny, but you won't need that for a typical site.

How do I add videos?

Best practice: upload your video to YouTube or Vimeo, then embed it on your site. Two reasons:

• Video files are big. Hosting them on your own site can slow load times.
• YouTube and Vimeo handle the heavy lifting — different qualities for different connections, captions, mobile playback.

To embed: upload to YouTube (can be public or unlisted), copy the "Share → Embed" code, and tell Claude Code "embed this YouTube video on the home page." Done.

Can I let people book appointments / make reservations?

Yes. Sign up for a booking service like Calendly, Cal.com, Acuity, or SavvyCal. All have free or cheap plans. They give you either a link or a small piece of embed code. Tell Claude Code "add a Calendly booking widget to my Sessions page" and they'll embed it. Your visitors book through that, and the booking lands in your calendar.

Can people pay me for my services on the site?

Yes. You add a "Buy" or "Book" button that connects to a payment service. The payment service handles the card details safely — you never touch them. Your visitor pays, you get the money, and your site stays simple. Common options:

• Stripe — flexible, low fees, used by most businesses. Best for selling services or accepting deposits.
• Payhip — easiest setup for digital products, courses, downloads. (Belinda already uses this.)
• Gumroad — similar to Payhip, popular for creators.
• PayPal — familiar to customers; usually used alongside Stripe.

The setup pattern is the same for all of them: sign up with the payment service, create your product (e.g. "1-hour session, $250"), copy the checkout link or button code they give you, and tell Claude Code to add it to the right page. Your visitor clicks "Buy," lands on the payment service's secure checkout, pays, and the money lands in your bank account a day or two later.

Can I have a portfolio or photo gallery?

Yes. A portfolio is just a page (or a few pages) with images and short descriptions. Tell Claude Code "build me a portfolio page with these five projects" — give the project names, descriptions, and image filenames. Claude lays it out and you fine-tune the look.

Can I collect emails for a newsletter?

Yes. Sign up with an email service like Mailchimp, ConvertKit, Buttondown, or MailerLite. They give you a signup form. Tell Claude Code "add my Mailchimp signup form to the footer" and it goes everywhere on the site. New signups appear in your email service's dashboard, ready to send to.

Can I have a contact form?

Yes. Two common ways:

• Simple: use a free service like Formspree or Web3Forms. They give you a tiny snippet of code. Tell Claude Code where to put it. Messages from your visitors land in your email inbox.
• Even simpler: skip the form. Put your email address or a Calendly link on the page. Lots of small businesses do exactly this.

Can I add a blog?

Yes. Astro is great for blogs. Tell Claude Code "set up a blog with a posts folder." Each post becomes a separate file in a folder, and Astro generates a blog index page automatically. Writing posts means creating new files, which Claude Code can also help with.

Can Google and AI tools find my site?

This setup is one of the best for being found. Because your pages are plain HTML built ahead of time, all your text sits right in the page where search engines and AI crawlers can read it. Many sites built with heavier tools are harder to crawl because their content only appears after scripts run. Yours does not have that problem.

To help crawlers along, there are two small files worth adding. Tell Claude Code: "Add a sitemap and a robots.txt that welcomes search engines and AI crawlers, and set my site address in the config."

• A sitemap is a list of every page on your site, so crawlers find them all instead of hoping to stumble across them. It updates itself as you add pages.
• A robots.txt file tells crawlers what they are allowed to read. You can use it to explicitly welcome the AI crawlers (such as GPTBot, the one ChatGPT uses), which matters if you want AI tools to find and mention you.

What about my Google Business Profile?

Your Google Business Profile (the free listing with your map pin, opening hours, photos and reviews) is separate from your website, and it is one of the most overlooked parts of being found, especially for local searches. The two are not the same thing and you manage them in different places.

• Your website is what you build here. You update it through Claude Code.
• Your Business Profile lives on Google. You update it inside Google's Business Profile dashboard, your hours, photos, services, posts, and your replies to reviews.

Connect the two by adding your website address in the "Website" field of your Business Profile. Keep your business name, phone number, and (if you have one) address identical across both, Google rewards consistency. Reviews on your profile are one of the biggest factors in local ranking, so it is worth asking happy clients to leave one.

If you run more than one business, keep a separate Business Profile for each, and point each profile at its own website. Do not merge them.

Add your booking link. If you take bookings or calls, add your scheduling link (such as your Calendly or Cal.com URL) to your Business Profile so a "Book" button appears right on your Google listing. People can then book you straight from search, without even visiting your site. It turns your profile into another booking funnel and signals to Google that you are an active, bookable business, which helps your ranking.

Should I link between my own pages?

Yes, a little. When it reads naturally, link from the text on one page to another relevant page. For example, when a page mentions seeing examples, that phrase can link to your examples page. These in-content links help visitors move around and help search engines understand how your pages relate. Tell Claude Code "add a few natural internal links across my main pages" and it will suggest sensible ones. Do not overdo it; a handful of genuine links beats stuffing links everywhere.

Do I need a privacy policy and terms and conditions?

If you collect any information at all, even just email addresses from a signup form, you should have a privacy policy. It is a short, plain page saying what you collect, why, and how you look after it. In New Zealand this is expected under the Privacy Act.

A terms and conditions page is worth having if you sell anything or provide a service, especially one that relies on third-party platforms. It sets out what people can expect, your refund and cancellation rules, and the limits of your responsibility. Tell Claude Code what your business does and it will draft both pages in plain language.

Anything else I can add?

Most third-party services that give you an "embed code" (a small snippet of HTML) can be added to your site. If you find a service you want to use, tell Claude Code: "I want to use [service name] on my site — what's the simplest way to add it?" Claude will look up how and walk you through.

11. Security and safety — your honest fears, answered

This chapter exists because the questions you have are normal questions and you deserve real answers, not technical hand-waving. Read it once. Refer back when you need to.

What can go wrong (the realistic list)

What "site crash" looks like — and what to do

A "crash" for this kind of site means one of three things:

1. Cloudflare's network has a temporary issue. Visitors see a Cloudflare error page for a few minutes. You do nothing — it resolves itself. Cloudflare has roughly 99.99% uptime, which is a few minutes of unavailability per year across the whole network.
2. Your most recent change broke something. A page looks wrong or fails to load. Fix: in Terminal, run git revert HEAD then git push origin main. This undoes your last change and re-publishes the previous working version within a minute.
3. Your domain stops pointing at Cloudflare. Usually because the domain expired (renewal didn't go through) or DNS got changed by accident. Fix: log into your registrar, renew or restore the DNS records.

"Can my site be hacked?" — the honest answer

Most "hacking" stories you hear about websites are about dynamic sites: WordPress, Shopify, custom databases, sites with user logins. Those have many ways in: SQL injection, weak admin passwords, vulnerable plugins, exposed login forms.

Your site is static. It's HTML and CSS files served from Cloudflare's network. There is:

• No database to inject malicious queries into
• No user login form to brute-force
• No admin panel exposed on the public web
• No plugins that can become vulnerable over time
• No server code that runs when a visitor loads the page

The realistic ways someone could change your site content:

1. They guess or steal your GitHub password. Defence: strong unique password + two-factor authentication. Covered below.
2. They compromise your Cloudflare account. Same defence.
3. They compromise your domain registrar account and redirect traffic elsewhere. Same defence.

Notice the pattern: every realistic risk is about your account credentials, not about the website's code. Protecting accounts is the actual security work.

Credit card safety — where money lives

Here is exactly where credit cards do and don't enter the picture:

When you sell something on your site (covered in Chapter 10), the "Buy" button takes the visitor to a separate, secure checkout page run by the payment service (Stripe, Payhip, etc.). Card details are entered THERE, on the payment service's servers, never on yours. The payment service is responsible for keeping that data safe — they're set up for it, with all the banking-grade security. Your site never sees the card.

This is why even if someone managed to break into your website's files, they'd find HTML and CSS — no card data to steal, because there was never any card data to begin with.

Claude on your laptop — what Claude can and cannot do

Reasonable fear: "I'm letting Claude run commands on my computer. What's the boundary?"

What Claude Code can do

• Read and write files inside the project folder you're working in
• Run Terminal commands you approve, in that folder
• Suggest changes; you decide whether to accept them
• Search the web for documentation when needed

What Claude Code cannot do

• Access your browser's saved passwords or autofill data
• Read your email or send messages on your behalf
• Open your banking app or any other app
• Access your photos, documents, or files outside the project folder you're working in
• Charge your credit card or make purchases
• Install software without your explicit approval
• Continue running after you close the Terminal window

Sensible practices when working with Claude Code

• Keep Claude in a dedicated project folder (e.g. ~/Desktop/DTI website). Don't run it from your home folder where personal files live.
• If a command Claude suggests looks unfamiliar, ask "what does this do?" before approving it. Claude will explain.
• Close the Terminal window when you're done. The session ends.
• Never paste passwords, card numbers, or API keys into the chat. Claude doesn't need them and shouldn't have them.

Protecting your accounts (the actual real risk)

If 95% of realistic threats come from compromised accounts, here's the 95% solution:

1. Use a password manager

Sign up for one of: 1Password, Bitwarden, or iCloud Passwords (built into Apple devices). Let it generate a long random password for each account: GitHub, Cloudflare, your domain registrar, your email. Don't try to remember them. The password manager remembers them for you.

Why this matters: the most common way accounts get compromised is that the user re-used a password that was leaked from some other site years ago. Unique passwords eliminate this entire category of attack.

2. Turn on two-factor authentication (2FA) on these four accounts

• Your email (the one you used to sign up for everything)
• GitHub
• Cloudflare
• Your domain registrar

Two-factor means: even if someone has your password, they also need a 6-digit code from your phone to log in. Use an authenticator app (Google Authenticator, 1Password's built-in one, or Authy). SMS-based 2FA is better than nothing but apps are stronger.

3. Review who has access — periodically

Every few months, log into GitHub and Cloudflare → Settings → check that no unfamiliar devices, apps, or "deploy keys" are connected. Remove anything you don't recognise.

"What if something happens and I need help?"

Phishing — what to watch for

You'll start getting emails about your domain, your hosting, your GitHub repos. Most are real. A few are scams. The pattern to recognise:

• Urgency: "Your domain expires in 24 hours, click here now to renew"
• Threats: "Your account will be suspended unless you confirm details"
• Sender domain doesn't match: email says "GitHub" but the address is [email protected] not [email protected]
• Asks for password or card via the link: real services never ask this in an email

Universal rule: when in doubt, don't click. Open a fresh browser tab, type the address by hand, log in directly. If something needs your attention, it'll be in your account dashboard.

Visitor privacy — what you're responsible for

If your site collects any visitor information (contact form, email signup, analytics), some basics apply:

• Privacy policy: a simple page on your site explaining what you collect and why. Free generators exist (e.g. termly.io, getterms.io).
• Cookie banner: only required if you use cookies for tracking (Google Analytics, Facebook Pixel, etc.). If your site is pure static with no tracking, you don't need one.
• Contact form submissions: they go to your email. Treat them like you treat any client email — don't share, store securely.
• NZ Privacy Act: if you collect personal info, you must use it only for the stated purpose and keep it secure. The Privacy Commissioner website has plain-English summaries.

The one-page security summary

12. Troubleshooting — when things don't go as planned

Things will occasionally go wrong. They go wrong for everyone, including professionals. The list below covers the most common situations beginners hit and what to do. If your situation isn't here, paste the exact error into Claude and ask for help — that's what Claude is there for.

Terminal says "command not found: npm" (or "command not found: node")

Node.js isn't installed on your Mac yet. Go to nodejs.org and download the "LTS" version. Run the installer. Close and reopen Terminal. Try again.

Terminal asks for my password while installing things

That's normal. Type your Mac admin password. You won't see characters appear as you type — that's also normal (security feature). Press Enter when done.

I'm getting "permission denied" errors

You're trying to install something to a place your account doesn't own. Most often this is fixed by either using sudo (which makes Terminal ask for your password) or — better — by using a tool like nvm to manage Node properly. Ask Claude to walk you through this; the exact fix depends on your setup.

Git says "please tell me who you are" (or "unable to auto-detect email address")

Git just needs your name and email once before it can save anything. Run these two lines (use your own details), then try the git commit again:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Git is asking me for a username and password and rejecting them

Since 2021, GitHub no longer accepts passwords via Terminal. You need a "personal access token" instead. In GitHub: Settings → Developer settings → Personal access tokens → Generate new token (classic) → tick "repo" → generate → copy the token. Paste THAT instead of your password.

My Cloudflare build failed

Open the build log in the Cloudflare dashboard. Look for the line starting with Error:. The most common causes:

• You forgot to commit something — run git status locally, commit anything red, push again
• The build command is wrong — should be npm run build
• The output directory is wrong — should be dist

If you can't tell, paste the whole error log into Claude.

My site loaded but looks completely wrong

Try a hard refresh: press Cmd + Shift + R in your browser. Browsers cache old versions. If that doesn't fix it, the issue is probably in the build itself — open the Cloudflare dashboard and check whether the latest build succeeded.

My site looks great on a computer but is a mess on mobile (squashed into a strip, background spilling out the side, everything zoomed out)

This is one of the most common mobile bugs, and it has one usual cause: something on the page is wider than the phone screen. When a page is wider than the screen, the phone zooms the whole thing out to fit, so everything looks shrunk into a narrow column with the background colour showing on the side.

The usual culprit is a side-by-side (two-column) layout where the columns are told to never shrink below a certain width, but never told to stack on small screens. Two 280px columns side by side simply don't fit on a 360px-wide phone.

The fixes (ask Claude to apply these):

• Let columns stack on mobile. Any side-by-side layout needs to wrap onto separate rows on a narrow screen (in CSS flexbox this is flex-wrap: wrap; with Tailwind, use responsive classes like flex-col md:flex-row).
• Trim large desktop padding on mobile. A 60px gap on each side is fine on a laptop but eats half a phone screen. Reduce it on small screens.
• Add a safety net. Set overflow-x: hidden and max-width: 100% on the page so nothing can ever force sideways scrolling, and make images max-width: 100% so they never exceed their container.

I accidentally deleted my project folder from Desktop

If you pushed to GitHub before deleting, your work is safe online. Go back to Terminal:

cd ~/Desktop
git clone https://github.com/YOURUSERNAME/your-repo-name.git

This re-downloads everything from GitHub. You haven't lost anything. (This is why we use GitHub.)

I broke something and want to start completely over

Don't panic. If you haven't done anything important, here's the safe path:

1. Make a copy of your project folder to your Desktop, just in case
2. Delete the original folder
3. Start the guide from Chapter 3 again
4. Push to your existing GitHub repo when you're ready

Cloudflare is showing my old domain not the new site

DNS changes take time to propagate — sometimes a few minutes, sometimes 24 hours. Wait. If it's been more than 24 hours, check that the DNS records in your registrar match what Cloudflare told you to use.

Two days in, I've forgotten what I was doing

Open this guide. Open the Claude conversation you set up. Tell Claude what state your project is in. Claude will help you figure out where you are and what's next.

Reference — for the curious

Contents of this section:

• The tools, what each one does, and why you need them
• Reading the Terminal — what you'll see and what it means
• Copy-paste pitfalls
• Scary moments that are normal
• Looking under the hood of your site (browser dev tools)

The tools, what each one does, and why you need them

Your Mac's Terminal

Terminal is a small window where you type text commands instead of clicking buttons. It's already on your Mac — no installation needed.

How to open it: Press Cmd + Space, type Terminal, press Enter.

What it looks like when it opens:

A small white window. Black text. Three little dots in the top-left corner for close/minimise/maximise. That's it.

Why you need it: Most developer tools are controlled by typed commands, not clicked icons.

Used in: Chapter 3 (Setting up your project on your computer).

Node.js and npm

Node.js is a program that lets your Mac run JavaScript code locally (not just in a browser). npm ("Node Package Manager") comes with it — it's like an app store for tiny pieces of code that other developers have shared.

What it looks like: You don't see Node.js as an app with an icon. It runs invisibly in the background after you install it. You'll only ever interact with it by typing node or npm commands into Terminal.

Why you need it: Astro (your site builder) is written in JavaScript. To run Astro on your laptop, you need Node.js. To install Astro, you need npm.

Used in: Chapter 3. You install it from nodejs.org with one click on a familiar Mac installer.

Astro

Astro is the website builder. You write your pages in special .astro files that mix HTML, CSS, and a tiny bit of JavaScript. When you run a build command, Astro turns those files into plain HTML/CSS/JS that any browser can read.

What it looks like: A folder on your Desktop with a name like DTI website, full of files and sub-folders.

Why you need it: Astro lets you split your site into reusable pieces (one Nav, one Footer used on every page) instead of copy-pasting the same code into every file. Changes to the Nav update every page automatically.

Used in: Chapter 3 (creating the folder) and Chapter 5 (building your pages inside it).

Tailwind CSS

Tailwind is a CSS styling system that uses small utility classes (like bg-plum, text-gold, p-4) instead of writing custom CSS for everything. You define your brand colours once, then use them as class names throughout the site.

What it looks like: A styling file inside your Astro folder (usually src/styles/global.css). You'll never edit it by hand — you'll tell Claude Code "set my plum colour to #3D2438" and Claude does it.

Why you need it: Saves hours. Changing your brand colour from gold to bronze means editing one line in one file, not finding every occurrence across many files.

Used in: Chapter 4 (Configuring colours and fonts).

Claude Code (the CLI tool)

Claude Code is a version of Claude that runs inside your Terminal and can directly read, edit, and create files in your project folder. You talk to it in plain English ("change the home page hero copy to X", "add a new page about pricing"), and it makes the edits and saves them.

What it looks like: Same Terminal window as before, but now there's a Claude chat happening inside it. You type your request, Claude responds, files get edited.

Why you need it: Editing .astro files by hand requires knowing HTML and CSS. Claude Code does the editing for you while you describe what you want.

Used in: Chapters 4, 5 and 9 (building and updating your pages). You install it in Chapter 3, Step 8 with one command: npm install -g @anthropic-ai/claude-code. It needs a paid Claude plan (Claude Pro or higher).

Git

Git is a tool that tracks every change you make to your files. Every save creates a snapshot you can return to. Think of it as "infinite undo" for your project. It's already installed on your Mac.

What it looks like: Nothing visual. Git lives quietly inside your project folder. You interact with it by typing short commands like git status, git add ., git commit -m "..." into Terminal. You don't have to "learn Git" — you'll copy and paste the same five commands forever.

Why you need it: Safety net. If something breaks, you can roll back to a working version. Also required for GitHub and Cloudflare Pages to know what to publish.

Used in: Chapter 6 (Getting your site live). The exact commands are written out for you.

GitHub

GitHub is a free website that stores your project's files online and tracks the history of changes. Each project ("repo") lives at a URL like github.com/yourname/yourproject.

What it looks like: A regular website you log into in your browser. Mostly white with some green and blue accents. Looks more like a clean dashboard than a coding tool. You sign up the same way you'd sign up for any service — email and password.

Why you need it: Two reasons. (1) Backup — if your laptop dies, your project is safe online. (2) Cloudflare Pages watches your GitHub repo, so when you push a change to GitHub, Cloudflare automatically rebuilds and publishes the live site.

Used in: Chapter 6.

Cloudflare Pages

Cloudflare is a company that runs a giant network of servers around the world. Cloudflare Pages is their free service for hosting static websites. You connect it to your GitHub repo once. From then on, every time you push a change to GitHub, Cloudflare builds your site and serves it to visitors from servers near them.

What it looks like: Another regular website (dash.cloudflare.com) you log into in your browser. Orange and white branding. A dashboard with your projects listed.

Why you need it: Free hosting with global speed. The free tier handles plenty of traffic for most small businesses.

Used in: Chapter 6.

Your domain (e.g. yoursite.co.nz)

The domain is the human-readable address visitors type into their browser. You bought it from a domain registrar (the company you pay yearly for it). To make the domain point at your new site, you'll change a few DNS records in your registrar's settings. (DNS = "Domain Name System" — the internet's address book.)

What it looks like: Whatever website you bought your domain from — likely a NZ registrar like discountdomains.co.nz or freeparking.co.nz, or international like Namecheap or GoDaddy. You log in to manage settings.

Used in: Chapter 7 (Pointing your domain at the new site).

How it all fits together

In plain English:

1. You edit .astro files on your laptop with Claude Code
2. Git tracks every change
3. You push changes to GitHub with one command
4. Cloudflare Pages sees the GitHub push and rebuilds your site automatically
5. Your domain (set up once) points visitors at Cloudflare's servers
6. Visitors see your latest changes

Reading the Terminal — what you'll see and what it means

The prompt

When Terminal opens, you see something like:

belinda@MacBook-Pro ~ %

That's called the prompt. It's Terminal telling you "I'm ready, type something." The bits mean:

• belinda = your username
• MacBook-Pro = your computer's name
• ~ = which folder you're in (~ means your home folder)
• % = the "I'm ready" marker

The blinking cursor

After the prompt there's a blinking block or line — that's just the cursor. It blinks whether something is happening or not. If you ran a command and the cursor is sitting there, the command is probably still running. Wait.

Typing your password

When Terminal asks for your password (it usually says Password:), you type it normally and press Enter. You will NOT see any dots, asterisks, or letters appear as you type. That is on purpose, for security. Just type carefully and press Enter.

Long walls of text after a command

When you install something with npm, Terminal will sometimes print hundreds of lines very fast. Don't try to read all of it. Look at the last few lines. If they say something like added 247 packages in 8s or include the word success or no ERROR in caps, you're fine.

Yellow vs red text

• Yellow / orange text = warning. Almost always safe to ignore. Things like "deprecated" or "X packages have moderate vulnerabilities" are warnings.
• Red text with the word "Error" or "ERR!" = actual problem. This is the kind that stops your work and needs attention.

Yes/no questions

Many setup commands ask questions. They look like this:

Use TypeScript? (Y/n)

The capital letter is the default. So (Y/n) means "yes by default — press Enter to accept." (y/N) means "no by default." If you just press Enter without typing, the capital letter wins.

Useful keyboard shortcuts (memorise these three)

Diagnostic commands when you're lost

Copy-paste pitfalls

You'll copy a lot of commands from this guide and from Claude. Three things to watch:

1. Smart quotes vs straight quotes

If you copy a command from a Word doc, email, or PDF, the quotes sometimes get converted from " (straight) to " or " (curly). Terminal will reject curly quotes with an error. If a copied command fails with a weird error, retype the quotes by hand.

2. Multi-line commands

Some commands wrap across multiple visible lines but are one command. When you copy them, copy the whole thing in one go and paste once. Terminal handles the wrapping.

3. Don't paste random commands from the internet

If you find a command on a forum or blog and you don't understand what it does, paste it into Claude and ask "what does this do and is it safe to run?" before running it. Most are safe. Some can damage your system. When in doubt, ask.

Scary moments that are normal

The first time you do this, these things will look alarming. They're all fine.

"Apple cannot verify this app is free from malware"

Comes up when you install Node or another tool from outside the App Store. Click Open or go to System Settings → Privacy & Security → "Allow anyway." It's fine for Node, Cursor, VS Code, and other developer tools.

"X packages have N vulnerabilities" after npm install

You'll see this every time. For a typical Astro site, the vulnerabilities are in build tools that never run on your live site. Ignore unless Claude tells you otherwise.

"npm WARN deprecated" lines

Warning, not error. Means some sub-tool inside the install is old. Your project still works. Ignore.

Terminal sat for 30+ seconds doing nothing after I pressed Enter

Most likely it's still working — npm install and npm create astro can take a minute or two on a slow connection. The blinking cursor doesn't mean "ready." Look at the line above the cursor. If there's no new prompt (% or $), it's still running.

Hundreds of new folders appeared inside my project

That's node_modules. Astro needs ~200 small tools to build your site. They live in that folder. You'll never open it. Don't touch it. Git is set up to ignore it automatically.

"detached HEAD" in git

Sounds terrifying. Just means you're looking at an old version of your code. Run git checkout main to get back to the current version. Nothing is broken.

I closed my laptop and now the site at localhost:4321 won't load

When you close Terminal (or shut your Mac), the local dev server stops. Open Terminal, navigate to your project folder, run npm run dev, and it'll be running again.

I see a giant wall of red text after git push

Read the first or last line, not the middle. The most common cause: GitHub doesn't know who you are yet. The fix is usually one command, which Claude will give you.

Looking under the hood of your site (browser dev tools)

Sometimes Claude will say "check the browser console for errors." Here's how:

1. Open your site in Chrome, Safari, or Firefox
2. Right-click anywhere on the page → click Inspect (Safari: needs Develop menu turned on in Preferences first)
3. A panel opens at the bottom or side of your browser. Click the Console tab
4. Red lines = errors. Yellow lines = warnings (safe to ignore). White / grey lines = informational
5. Copy any red lines and paste them into Claude

Close it with the X in the panel corner, or by pressing the same shortcut again (Cmd + Option + I on Mac).

SEO and AI search — the truth about how this affects discoverability

This is one of the most misunderstood topics on the internet, so let's address the mechanics. Specifically: does running a site built with JavaScript tools hurt how you rank on Google or appear in AI search results?

The short answer

No. In almost every measurable way, an Astro site on Cloudflare Pages is better for SEO than a typical Webflow site. Page speed, mobile performance, control over meta tags, sitemap quality, and crawlability are all equal or better.

The confusion comes from mixing up two very different things: "a website that uses JavaScript" and "a website that requires JavaScript to display its content." Astro is the first; the SEO problem applies only to the second.

What happens when you build an Astro site

When you run npm run build on your laptop (or when Cloudflare builds the site after you push to GitHub), Astro reads your .astro files and turns them into plain HTML files — the same kind of HTML that's been used to build websites since 1993.

By the time Google's crawler arrives at your website, there is no JavaScript involved. The crawler downloads a plain HTML page with your full content already inside it — exactly like it would from a WordPress, Webflow, or hand-coded HTML site.

Where the "JavaScript hurts SEO" myth comes from

The myth is real but it applies to a specific kind of site: Single Page Applications (SPAs). These are sites where you visit one HTML page that's mostly empty, and JavaScript then fills in all the content by talking to a server.

Examples of SPAs: most apps built with React, Vue, or Angular without server-side rendering. Gmail. Twitter. Facebook.

SPAs have historically had SEO problems because Google's crawler had to run the JavaScript to see what was on the page — which it does, but slowly and sometimes imperfectly.

Astro is the opposite of an SPA. It pre-builds everything to HTML so search engines see content immediately, no JavaScript execution required.

Astro vs. Webflow for SEO — honest comparison

Practical takeaway: in real-world SEO terms (the things Google uses to rank you), Astro on Cloudflare ties or wins on every meaningful dimension. The biggest practical win is page speed, which Google explicitly uses as a ranking signal.

How AI search engines treat your site

"AI search" refers to tools like ChatGPT search, Perplexity, Google's AI Overviews, Claude's web tools, Bing Copilot. These work differently from traditional Google search, and they treat your site differently again:

• Most AI crawlers do NOT run JavaScript. They read raw HTML only. This makes pre-rendered sites (like Astro) strictly better for AI search than JS-heavy SPAs.
• AI engines reward clean semantic markup. Using proper <h1>, <article>, <section>, <p> tags helps AI understand your content. You have full control over this in Astro.
• AI engines value clear, readable content over keyword stuffing. The way you write matters more than the platform you write on.
• Structured data (JSON-LD) is becoming increasingly important. It lets AI engines understand "this is a service business in Auckland that does photography." Astro lets you embed any structured data you want.

What matters for SEO and AI discoverability

Ranking signals roughly in order of importance:

1. Quality content that answers what people are searching for (no tool changes this — you have to write well)
2. Page speed and mobile experience (Astro on Cloudflare wins big here)
3. Backlinks from other reputable sites (independent of platform)
4. Clear page structure with proper headings (Astro gives you full control)
5. Meta titles and descriptions that match search intent (Astro: full control)
6. Structured data for rich results (Astro: full control)
7. Internal linking between pages (independent of platform)
8. HTTPS, sitemap, robots.txt (Cloudflare provides; Astro generates sitemap)

Common myths, debunked

What you should do for SEO in your new site

1. Use real headings (one <h1> per page, then <h2>, <h3> in order) — Claude Code can do this for you
2. Write a unique meta title and meta description for every page — these show up in Google search results
3. Use descriptive alt text on every image — helps Google Images and screen readers and AI
4. Install Astro's sitemap integration: npx astro add sitemap — one command, done
5. Add structured data (JSON-LD) for your business — Claude Code can paste this in for you
6. Write useful content. The single biggest SEO factor is "does this page help the person who searched?"

The technical SEO checklist — copy this for every site you build

Everything above is the "why". This is the "what to do". Each item is something Claude Code can set up for you in minutes. The fastest way to use this on a new site is to paste the whole list to Claude and say "set all of this up for my Astro site". Once it is done, a new site is technically sound from day one and you never have to remember the details.

After setup, validate it (free tools)

1. Google Search Console (search.google.com/search-console) — verify the site, submit your sitemap (https://yourdomain/sitemap-index.xml), and watch which pages get indexed. Do this for every new site.
2. Rich Results Test (search.google.com/test/rich-results) — paste a page URL to confirm your structured data is valid.
3. PageSpeed Insights (pagespeed.web.dev) — confirm your Core Web Vitals are in the green.
4. Bing Webmaster Tools — same idea as Search Console, for Bing (which also feeds some AI search).

Migrating an existing site — keeping the rankings you already have

If you're replacing a site that's already live and already ranking (this was written after doing exactly this for two real sites), this section is the one that actually protects your rankings. Everything above matters for a brand-new site; this is the extra layer for a site with history.

What's normal after you flip the switch

Even a perfect migration causes some short-term ranking wobble, because Google has to re-crawl and re-evaluate your pages at their new home. This is documented directly by Google, not a guess:

• 1 to 4 weeks of fluctuation is normal for a small site that kept its domain and URLs — this is Google's own guidance, not a symptom of something wrong.
• Full settling typically takes 2 to 6 weeks if the redirects and technical setup are clean. Changing your domain name at the same time (not just the platform) pushes this out further — weeks to a few months.
• Don't judge it from a web search or a single tool in the first couple of weeks. Google Search Console (Coverage report + URL Inspection) is the only authoritative source for whether your pages are actually indexed cleanly. Rank-tracking tools like SEMrush and a plain web search can disagree with each other and with Search Console during this window — that disagreement is itself a normal sign of reindexing in progress, not a red flag on its own.
• Use URL Inspection → Request Indexing in Search Console on your handful of most important pages right after launch. It doesn't guarantee faster ranking, but it gets Google to look at the new page sooner instead of waiting for its normal crawl schedule.

After you launch: getting found, and what to monitor

Once your site is live, a short one-time setup gets you into search and gives you real visitor data. After that, it mostly looks after itself, there is almost no ongoing technical maintenance.

The one-time setup (do once per site)

• Force HTTPS. On Cloudflare: SSL/TLS → Edge Certificates → turn on "Always Use HTTPS" and set Minimum TLS Version to 1.2. The certificate auto-renews forever; nothing to maintain.
• Google Search Console (search.google.com/search-console). Add your site. If your DNS is on Cloudflare it often auto-verifies. Submit your sitemap (sitemap-index.xml), then use "Request indexing" on your most important pages to get them crawled in hours instead of weeks.
• Bing Webmaster Tools (bing.com/webmasters). Use "Import from Google Search Console", one click, no re-verifying. This matters because ChatGPT and Microsoft Copilot search use Bing's index.
• Cloudflare Web Analytics. Turn it on (Analytics → Web Analytics → Add a site, "automatic setup" if your site runs through Cloudflare). Privacy-friendly, no cookie-consent banner needed, and it counts real human visits, not bots.

The safeguard: ask Claude to re-audit everything, once the site is fully live

Two things make it easy for an SEO item to fall through the cracks, even when you followed this guide carefully:

• Long chats get restarted. If your build spanned more than one Claude conversation (very common — a migration alone can take several sessions), a later session has no memory of what an earlier one already did. It is easy to assume something was covered when it was only planned.
• Platform defaults can change after you read this. Cloudflare, GitHub, and Google can all change their own default settings over time. A step that used to be "off by default" (like AI crawler blocking) could ship as "on by default" tomorrow, with nothing in your project files showing it happened, because it lives in a dashboard, not in your code.

Once your site is fully live — domain pointing, DNS settled, everything from this guide done — run one more pass. Paste this to Claude (with browser access, so it can actually check your live dashboards, not just your files):

Set this up once so you never have to remember it

The easiest way to make sure this actually happens every month is to not rely on yourself remembering. Ask Claude to set it up as a recurring task, once, right now:

Which dashboard tells you what

What you do NOT need to check or maintain

• The sitemap updates itself. It regenerates automatically every time the site rebuilds (every change you publish). You never manually update or resubmit it. Search engines re-read it on their own.
• HTTPS and the SSL certificate auto-renew. Cloudflare manages it. The toggles you set stay set. Nothing to check.
• Security headers are static. Set once, done.

So there is no recurring technical chore. The only ongoing "work" is the good kind: publishing useful content, and glancing at your two dashboards (Web Analytics and Search Console) now and then to watch it grow.

Things you must NOT do

Glossary

Astro

A static site builder. Turns your .astro files into plain HTML/CSS/JS that any browser can serve.

Branch

A parallel version of your code in Git. The default branch is usually called main. You can have separate branches for in-progress work that doesn't affect the live site.

Build

The process of turning your source files into final website files. Run with npm run build.

CLI

"Command Line Interface". Tools you control by typing commands instead of clicking. Terminal is a CLI.

Cloudflare Pages

A free hosting service. Connects to your GitHub repo and publishes your site automatically when you push changes.

Commit

A saved snapshot in Git. Each commit has a short message describing what changed.

Deploy

Putting your latest changes onto the live website.

DNS

"Domain Name System". The internet's address book. Maps your domain (yoursite.com) to a specific server.

Git

A version-tracking tool installed on your Mac. Records every change to your files.

GitHub

A website where your Git repositories live online. Backup and collaboration tool.

npm

"Node Package Manager". Installs and manages JavaScript libraries.

Node.js

A program that runs JavaScript outside the browser. Needed to run Astro on your laptop.

Push

Uploading your local Git commits to GitHub.

Repo / Repository

A Git project folder, usually one website or app.

Static site

A website made of pre-built files (no live database or backend). Cheap to host, very fast.

Tailwind CSS

A styling system using small utility classes. You define your brand colours once and use them by name everywhere.

Terminal

The text-based interface where you type commands. Built into macOS.