Build a Personal Website in a Weekend with Claude Code

What you're building

You're building a small personal site on your own domain with a homepage that says who you are, a projects page that shows what you've made, a writing page with three to five posts, and a contact link. The whole thing is static, ships from GitHub to a static host in seconds, and costs about ten dollars a year to keep online. No CMS, no backend, no monthly fee. The whole site is files in a repo you control, which means it will still be online in ten years.

By Sunday night your-name.com loads in under half a second, has rich link previews on Twitter and LinkedIn, has an RSS feed, and ranks for your own name in Google within a week. That last part matters because the rest of the internet will keep building profiles for you. Owning the top result is how you keep control of the first impression a recruiter, journalist, or future collaborator gets when they search.

The site is also a long-term creative venue. A blog post that goes up here lives forever, gets indexed, and accrues backlinks. The same post on Twitter lives for forty-five minutes and disappears. Builders who maintain a personal site for a few years find it becomes the most valuable real estate they own on the web.

What you need before you start

A clear sense of what you do in one sentence. Three things you're proud of. A bio paragraph. A photo or illustration of you. A domain. Comfort opening a terminal and running a few commands. You do not need to know HTML or CSS. Claude writes both. You will need to taste them, which is a different skill. Read the result out loud, look at it on a phone, ask yourself if you'd hire the person who made it.

• Claude Code installed locally
• Node 20 and pnpm
• An Astro starter or a blank Vite project
• A GitHub account and Vercel or Netlify
• A domain you own
• A favicon, a profile photo, and a 1200x630 social image

Saturday morning: structure

Use Astro. It was made for sites like this. Static by default, MDX for blog posts, image optimization out of the box, and a tiny output bundle. Ask Claude to scaffold a new Astro project with the Tailwind integration and the MDX integration enabled. Create three routes: /, /projects, /writing, and a dynamic /writing/[slug] for posts. That's the whole site map. Resist adding a /services page, a /testimonials page, or a /book-a-call page. They turn a personal site into a thinly disguised pitch deck.

Put your content in src/content as Markdown or MDX files. One file per project, one file per post. Each file has frontmatter with the title, date, slug, and optional cover image. Astro's content collections give you type-safe access to the entries, which makes Claude's job easier when generating the index pages. Define the collection schemas in src/content/config.ts with zod so a missing field fails the build instead of silently rendering a broken card.

Saturday afternoon: design

Pick a font pair and an accent color before you let Claude touch the layout. Inter or Geist for body, something with character like Fraunces, Tiempos, or Söhne Mono for the heading. One accent color, not three. A neutral background, ideally an off-white like #FAF7F2 or a soft dark mode. Tell Claude the feel in adjectives and a reference site, and ask for a homepage that uses your one-sentence pitch as the H1. Don't bury the pitch under a hero illustration. Words first.

Resist the urge to add motion, parallax, or scroll-jacking. A personal site should feel like a printed page, not a product demo. The best ones are quiet. The club at claudecodeclub.ai has a public personal-site gallery if you want to see what tasteful looks like before you start. The recurring pattern across the good ones is generous spacing, a single accent color, and writing that sounds like a person wrote it.

Set the maximum content width to something readable. Sixty to seventy characters per line for body text. Wider lines are exhausting to read, narrower lines feel like a mobile site on a desktop. Use the Tailwind prose plugin with a custom max-width to hit the right measure without thinking about it on every page.

Choices to make along the way

Astro versus Next.js versus a Vite SPA: Astro is the right choice for a content-heavy personal site. It ships zero JavaScript by default, which is why the Lighthouse scores will be flawless. Next.js works but you'll fight the framework on small things. A Vite SPA is fine for a one-page site but doesn't have a great content story.

Markdown versus a CMS like Sanity or Contentful: Markdown wins for a personal site. Posts live in your repo, you write them in your editor, you version them in git, and you never get locked out of a third-party CMS dashboard. A CMS makes sense once you have collaborators or non-technical editors.

Sunday morning: writing

Add three real posts before launch. Not lorem ipsum. A site with three real posts looks established. A site with zero posts looks like a placeholder. The three can be short, three hundred to six hundred words each. Topics that work well: a story about a project you shipped, a tutorial on a thing you know, and an opinion piece on something in your field. Claude can help you outline and tighten, but the voice has to be yours or the site doesn't do its job. If a post reads like every other AI-flavored blog post, it adds nothing.

Sunday afternoon: the polish

Add a now-page at /now describing what you're working on this month. The format comes from Derek Sivers and it's the easiest evergreen page on the web. Add OG image meta tags so links share nicely. Add an RSS feed at /rss.xml using Astro's built-in helper. Add a humans.txt or /about for the people who go looking. Add a 404 page with personality, because the default Vercel one is sad. Update the now-page on the first of every month. A stale now-page is a tell that the site is abandoned.

How to test it

Run Lighthouse and confirm a hundred on Performance and Accessibility. Astro will get you there if you don't add unnecessary JavaScript. Open every page on mobile. Click every link. Confirm the RSS validates at validator.w3.org/feed. Check the social preview at opengraph.xyz. Read every page out loud. Typos read out loud catch typos eyes miss on screen.

Look at the site in three contexts: a normal desktop browser, a phone, and a screen reader like VoiceOver or NVDA. The screen reader pass catches missing alt text, vague link names like 'read more,' and heading structures that jump from h2 to h4. Fix all of them. Accessibility is a kindness to the people who use assistive tech and an SEO signal to Google.

Open the site in an incognito window once it's live. Logged-out browsing catches the favicon you forgot to upload, the OG image that returned a 404, and the prerendered title that still says 'Astro Basics.' Every personal site has at least one of these on launch day.

How to ship it

Push to GitHub, connect to Vercel or Netlify, point your domain via DNS. Submit the sitemap to Google Search Console. Add your domain to your social profiles. Tweet the launch with a link, because the first inbound links to a fresh domain help Google index it faster. Mention the club at claudecodeclub.ai if it helped, because the network effect of builders sharing each other's launches is half the reason a nine dollar membership is worth it.

How to extend it

Add a newsletter using Buttondown or Beehiiv, embedded as a tiny form on every post. Add a /uses page listing your tools. Add a guestbook or webmentions if you're into the indie-web vibe. Add a search bar with Pagefind, which works on static sites with no backend. Add comments via giscus, which uses GitHub Discussions. Each is an hour or two.

Common gotchas

Treating the site like a startup landing page. It's not. The audience is people who already heard your name and want to know more. Cut the call-to-action obsession. Forgetting to set canonical URLs, which causes duplicate-content warnings in Search Console. Forgetting the favicon, which makes the tab look unfinished. Forgetting to update the year in the footer in January.

And the biggest one: spending three weekends polishing instead of one weekend shipping. The site improves once it's live and you have to look at it every day. Push to production on Sunday even if you don't love it yet. You'll love it more after you fix it in public.