A complete beginner's guide, written so anyone can follow it.
Quick facts about what you're signing up for
| Total cost to start | $0 (free) |
| Ongoing monthly cost | $0 on free tiers. ~$10–15/year for your domain name only. |
| Time to set up first time | About 2 hours total, broken into 15–30 min chapters |
| Time for future updates | 1–5 minutes per change |
| Technical skill needed | None to start. You'll pick things up as you go. |
How long each part takes
Rough guide so you can plan. You can stop and resume between any of these.
| Set up Claude (before you begin) | ~2 minutes |
| Install tools + create the project (Ch. 3) | 30–45 minutes |
| Colours + fonts (Ch. 4) | 5–10 minutes |
| Build your pages (Ch. 5) | As long as you like; an hour gets a solid start |
| Go live: GitHub + Cloudflare (Ch. 6) | 20–30 minutes |
| Point your domain + DNS (Ch. 7) | 15–20 minutes, then up to a few hours for it to take effect on its own |
| Allow AI crawlers in Cloudflare | 2 minutes (don't skip this; see Ch. 10) |
| Cancel your old hosting (Ch. 8) | 5–10 minutes, do this LAST, after the new site is confirmed live |
Tick these off in your head before you sit down to do this:
☐ A Mac (Intel or Apple Silicon — both work)
☐ Your Mac admin password (the one you use to install apps)
☐ A stable internet connection
☐ At least 5 GB of free space on your Mac
☐ About an hour of focused time (or break it into chunks across days)
☐ A working email address (for GitHub and Cloudflare account signup)
Before you start — read this first
This is built differently from most technical guides. You are not going to be left on your own to figure things out when something goes sideways. That happens — and it's not your fault when it does. It's why most people give up halfway through tutorials like this.
Here's how this one is different: this guide is designed to be used alongside an AI assistant called Claude. The guide tells you what to do. Claude is your real-time helper for anything the guide doesn't anticipate — error messages, weird terminal output, "wait, what did that just do?", or just needing something explained again in different words.
Setting Claude up takes about two minutes. It's free to start. The next section walks you through exactly how, and we strongly recommend doing this before you touch Terminal or write a single line of anything.
Between this guide and Claude, there is no point in this process where you have to fend for yourself. If you get stuck, paste what you're seeing into Claude, tell it what step you're on, and it will help. That's the whole idea. You're not doing this alone.
This guide is designed to be used alongside Claude. The free plan at claude.ai is enough for the whole guide — no paid upgrade required.
Keep that conversation open while you build.
Later in the guide a related tool called Claude Code takes over inside your Terminal to make file changes for you. Same Claude, different access. We'll set it up in Chapter 5 when we need it.
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.
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.
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.
Start here → Set Claude up, then How to use this guide (takes 5 minutes total)
Part One — Build your website
Reference — only if you're curious
You don't need any of this to build the site. It's here for anyone who wants to understand what each tool is or what something on screen means.
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:
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.
You'll need:
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.
nodejs.org.node-v20.x.x.pkg. Open it from your Downloads folder.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.
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.
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.
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.
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:
| Question | What to type |
|---|---|
| Where would you like to create your new project? | Your project name (e.g. DTI website) |
| How would you like to start your new project? | Empty |
| Install dependencies? | Yes |
| Do you plan to write TypeScript? | No |
| Initialize a new git repository? | Yes |
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.
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.
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.
http://localhost:4321This is a natural save point.
If you need a break, take one. Close Terminal. Your work is saved. When you come back, open Terminal, type cd ~/Desktop/DTI\ website, then npm run dev, and you'll be right back where you left off.
Your project folder contains a file called tailwind.config.mjs. That's where your brand colours and fonts get stored.
You don't need to open or edit this file yourself. Open Claude Code and say something like:
Claude makes the edit and tells you what class names are now available. For reference, the file Claude is editing looks like this on the inside:
theme: {
extend: {
colors: {
'brand-primary': '#3D2438',
'brand-accent': '#A6824A',
'brand-light': '#EFE3DC',
},
fontFamily: {
heading: ['Georgia', 'serif'],
body: ['Inter', 'sans-serif'],
},
},
},
After this, you can write class="bg-brand-primary" anywhere in your pages and that element becomes plum.
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 ├── astro.config.mjs ← Astro's main settings ├── tailwind.config.mjs ← YOUR COLOURS AND FONTS (you'll edit this) ├── package.json ← list of installed tools └── node_modules/ ← installed code (DO NOT TOUCH)
src/pages/index.astro (your home page content) and tailwind.config.mjs (your brand colours and fonts). Claude Code will do the actual editing — you just describe what you want.
Your pages live in src/pages/. Each .astro file is one page. The file name becomes the URL:
src/pages/index.astro → the home pagesrc/pages/about.astro → the /about pagesrc/pages/services.astro → the /services pageReusable 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.
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:
github.com/signup in your browserWhat 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:
dash.cloudflare.com/sign-up in your browserWhat 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.
github.com and dash.cloudflare.com in separate browser tabs and keep them open through this whole chapter. You'll bounce between them and Terminal a few times. Easier than re-finding each one.
Go to github.com and sign in. Click the + icon in the top-right → New repository. Make two:
yoursite-website — for development (private is fine)yoursite-website-production — for live deploys (public or private; this is what Cloudflare watches)In Terminal, inside your project folder:
git remote add origin https://github.com/YOURUSERNAME/yoursite-website.git git remote add production https://github.com/YOURUSERNAME/yoursite-website-production.git git add . git commit -m "Initial commit" git push origin main
Your code is now on GitHub.
dash.cloudflare.com and sign in-production reponpm run builddistmainBelow 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.
Workers & Pages
Deploy serverless functions and static sites.
Choose how to get started:
Framework preset
Astro
Build command
npm run build
Build output directory
dist
If you see "Deployment in progress" and within ~60 seconds it changes to "Deployment successful," it worked. Cloudflare gives you a URL like your-site-abc.pages.dev. Click it to see your site live on the internet.
git push production main:main
Wait about 60 seconds. Cloudflare emails you a free URL like your-site-abc.pages.dev. Visit it. Your site is live on the internet.
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.
What you now have
Only do this AFTER your new site is fully working at your domain.
webflow.comYou can also export your Webflow site as a backup before cancelling (Settings → Export → ZIP). Useful if you want to keep the design files.
Once everything's set up, normal updates are this short:
cd ~/Desktop/yourprojectgit add . then git commit -m "what you changed" then git push production main:mainThis kind of website can do almost everything most small-business sites need. Here are the common questions, with the simple answer for each.
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.
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.
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.
Best practice: upload your video to YouTube or Vimeo, then embed it on your site. Two reasons:
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.
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.
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:
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.
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.
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.
Yes. Two common ways:
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.
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."
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.
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.
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.
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.
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.
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.
| Risk | How likely | What it would mean |
|---|---|---|
| Your site temporarily goes offline | Low (a few minutes per year) | Visitors see an error page until Cloudflare recovers. Your files are unaffected. |
| Someone guesses your GitHub or Cloudflare password | Low if you use a strong password + 2FA | They could change your site content. Fixable. |
| You accidentally publish something you didn't mean to | Medium for everyone learning | Easily reversed. Git keeps every previous version. |
| Your laptop is lost or stolen | Low | All your code is on GitHub. You get a new laptop, re-download, keep going. |
| Someone "hacks" the site itself | Very low | Static sites have almost no surface to attack (see below). |
| Your credit card details get exposed via the site | Effectively zero | Your site never touches your card. See "credit card safety" below. |
A "crash" for this kind of site means one of three things:
git revert HEAD then git push production main:main. This undoes your last change and re-publishes the previous working version within a minute.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:
The realistic ways someone could change your site content:
Notice the pattern: every realistic risk is about your account credentials, not about the website's code. Protecting accounts is the actual security work.
Here is exactly where credit cards do and don't enter the picture:
| Account / service | Does it have your card? | Why |
|---|---|---|
| GitHub (free tier) | No | Free plan, no card needed |
| Cloudflare Pages (free tier) | No | Free plan, no card needed |
| Your domain registrar | Yes, for renewal | This is the one place a card sits on file. They charge ~$10–15/year automatically. |
| Your website itself | No, never | Card numbers don't pass through your site, even when you sell things — see below. |
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.
Reasonable fear: "I'm letting Claude run commands on my computer. What's the boundary?"
~/Desktop/DTI website). Don't run it from your home folder where personal files live.If 95% of realistic threats come from compromised accounts, here's the 95% solution:
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.
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.
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.
| If this happens | What to do first |
|---|---|
| Your site is showing an error to visitors | Check Cloudflare status (cloudflarestatus.com). If it's a Cloudflare-wide issue, wait. Otherwise: git revert HEAD then push. |
| You think your GitHub or Cloudflare account is compromised | Change the password immediately. Turn on 2FA if it isn't on. Check recent activity in account settings. |
| You receive an email from "GitHub" or "Cloudflare" asking you to click a link | Don't click. Open a fresh browser tab, type the address yourself (github.com, dash.cloudflare.com), log in, check if there's a real notification waiting. |
| You lose your laptop | Change your passwords on a different device (GitHub, Cloudflare, registrar, email). Sign out of all sessions. Your files are safe on GitHub. |
| You forget which version of the site is live | The version on the main branch of your production repo is the live one. Cloudflare shows the latest deploy in the dashboard. |
| You think you accidentally broke something | Don't push to production until you're sure. Test on your laptop first (npm run dev). If you already pushed and it broke, git revert HEAD and push again. |
You'll start getting emails about your domain, your hosting, your GitHub repos. Most are real. A few are scams. The pattern to recognise:
[email protected] not [email protected]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.
If your site collects any visitor information (contact form, email signup, analytics), some basics apply:
Do these five things and you've handled 95% of real risk:
npm run dev) before pushing to productionThings 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.
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.
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.
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.
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.
Open the build log in the Cloudflare dashboard. Look for the line starting with Error:. The most common causes:
git status locally, commit anything red, push againnpm run builddistIf you can't tell, paste the whole error log into Claude.
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.
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.)
Don't panic. If you haven't done anything important, here's the safe path:
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.
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.
Everything below is optional.
The guide above is enough to build and run your website. This section is here for anyone who wants to understand what each tool does, what to expect on screen, or what a particular surprise means. Read it cover to cover if you're curious — or dip in only when something on your screen makes you go "wait, what?"
Contents of this section:
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 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 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 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: One file inside your Astro folder called tailwind.config.mjs. 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 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: Chapter 5 (Building the pages). Install instructions live at claude.ai/code.
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 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 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.
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).
In plain English:
.astro files on your laptop with Claude CodeWhen 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 usernameMacBook-Pro = your computer's name~ = which folder you're in (~ means your home folder)% = the "I'm ready" marker$ instead of %
Some Macs show $, others show %, some show >. All three mean the same thing: "ready for your command." Different shells use different symbols. Ignore which one yours uses.
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.
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.
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.
% or $) without saying "Error" or "ERR!", the command worked. Move on.
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.
| Shortcut | What it does | When to use it |
|---|---|---|
| Ctrl + C | Stop the running command | When you want to quit npm run dev or anything stuck |
| Up arrow ↑ | Show the previous command you ran | Saves typing. Keep pressing to go further back. |
| Tab key | Autocomplete file or folder names | Type cd ~/Des then Tab → it fills in Desktop/ |
Cmd + C is "copy" everywhere except in Terminal, where the shortcut to stop a process is Ctrl + C (the actual Control key, not Command). This trips everyone up. To copy text out of Terminal, you can still use Cmd + C with your mouse selection — the trick is only about stopping running processes.
| Command | What it tells you |
|---|---|
pwd | Which folder am I currently in? |
ls | What files are in this folder? |
cd ~ | Take me back to my home folder |
clear | Clear all the messy text from the screen (your work isn't lost) |
You'll copy a lot of commands from this guide and from Claude. Three things to watch:
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.
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.
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.
The first time you do this, these things will look alarming. They're all fine.
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.
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.
Warning, not error. Means some sub-tool inside the install is old. Your project still works. Ignore.
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.
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.
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.
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.
git pushRead 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.
Sometimes Claude will say "check the browser console for errors." Here's how:
Close it with the X in the panel corner, or by pressing the same shortcut again (Cmd + Option + I on Mac).
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?
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.
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.
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.
| Factor | Astro on Cloudflare | Webflow |
|---|---|---|
| Page speed | Excellent (Cloudflare's global network) | Good (Webflow's CDN) |
| Core Web Vitals | Excellent — minimal JS, fast loads | Decent — varies with template |
| Mobile performance | Excellent | Good |
| Crawlable HTML | Yes (static at build) | Yes |
| Custom meta tags / Open Graph | Full control | Good (panel-based) |
| Sitemap.xml | Auto-generated by Astro integration | Auto-generated |
| Structured data (Schema.org) | Full control — paste any JSON-LD | Limited by Webflow's UI |
| Custom URLs / redirects | Full control via files | Good |
| HTTPS | Free automatic | Included |
| Robots.txt | Full control | Editable |
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.
"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:
<h1>, <article>, <section>, <p> tags helps AI understand your content. You have full control over this in Astro.Ranking signals roughly in order of importance:
<h1> per page, then <h2>, <h3> in order) — Claude Code can do this for younpx astro add sitemap — one command, done.env at the root of your project. Never paste them directly into the code or into Claude prompts that you'll commit.
node_modules folder unless you know what you're doing
It contains the installed code Astro needs to run. If it gets corrupted, delete it and run npm install to rebuild it — but don't do this without a reason.
.astro files into plain HTML/CSS/JS that any browser can serve.main. You can have separate branches for in-progress work that doesn't affect the live site.npm run build.