Build a Portfolio Website with Claude Code, No Coding

Last updated: August 2026

In this guide you will build a website with Claude Code from an empty folder to a live URL, even if you have never written a line of code. You finish with three files, one public address you can paste into a LinkedIn message, and a site you update by describing the change in plain English. Budget about two hours: roughly 70 minutes to build and preview, another 30 to deploy and point a domain at it. One of my students built hers this way, to show the Python and machine learning projects we had worked through together. Almost nothing that slowed her down was the code. It was the folder she chose, a permission dialog she did not expect, and one deploy error that read worse than it was. All three are in here.

What you need before starting

• A paid Claude plan with Claude Code installed. On Windows it prefers to run inside WSL, which is a separate 45 minute setup worth doing first.
• A project folder that is not inside OneDrive, iCloud Drive or Dropbox. Synced folders cause file locks mid-edit, and in one logged session a safety check refused to write to a synced path at all. Somewhere plain like Documents/sites is fine.
• A decision you can make in ten seconds: run node --version in a terminal. A version number means you can deploy from the command line in Step 6. An error means you take the drag-and-drop route instead, which is just as good. Knowing which one you are now beats finding out at the end.
• Three to five real things to show, with links, plus one photo of you.
• About two hours, and no prior web experience.
• Some tolerance for approval prompts. If terminals make you tense, start here rather than pushing through it.

Step 1: Set up the folder and write CLAUDE.md

Create an empty folder and move into it:

mkdir my-portfolio
cd my-portfolio

Then create a CLAUDE.md file. This is the single highest-leverage thing you can do, and it is worth understanding what a CLAUDE.md file is before you start. It is a plain text file Claude reads at the beginning of every session, so the context does not have to be re-typed:

# Project
A personal portfolio website for a data analyst moving into machine learning.
One page, fast, clean, mobile-friendly.

# Stack
Plain HTML and CSS only. No frameworks, no build step, no JavaScript unless I ask.
A beginner should be able to read every file.

# Rules
Keep everything in two files: index.html and style.css.
Explain what you changed in plain language after each edit.
Ask before adding any new file or dependency.

# Voice
Professional and warm. Short sentences. No buzzwords.

Every line there is doing a job. The Stack section is the one that matters most: without it, a fresh session will reasonably reach for React or Tailwind, because that is what most portfolio code on the internet looks like. You would then own a build step, a node_modules folder and a deploy that can fail, before you have written a single sentence about yourself. The "ask before adding any new file" rule is what keeps a one-page site a one-page site three prompts later. Anthropic's Claude Code overview covers what else the tool reads at startup.

Checkpoint: Your folder contains a CLAUDE.md file, and nothing else yet.

Step 2: Let Claude build the first version

Start Claude Code in the folder by running claude. On a first run it asks two things that stop people cold: whether you trust this folder (you do, you just made it), then permission before creating each file, with an option along the lines of "yes, and do not ask again this session." That approval covers this session in this folder only, not your whole machine. Sensible for a scratch portfolio folder. Not sensible out of habit in a folder holding real work.

Now describe the site in plain language. Be specific about structure, not style:

Build a one-page portfolio website as a single index.html plus a style.css.
Three sections: a short intro at the top, a Projects grid in the middle, and
a contact link at the bottom. Make it responsive and fast. No frameworks.

Claude Code creates the files and explains what it made. Your folder now looks like this:

my-portfolio/
├── CLAUDE.md
├── index.html
└── style.css

Open index.html and read it, even if you do not understand all of it. The Projects section will look roughly like this:

<section id="projects">
  <h2>Projects</h2>
  <div class="project-grid">
    <article class="project">
      <h3>Project one</h3>
      <p>One sentence on what it does.</p>
      <a href="#">View the code</a>
    </article>
    <article class="project">
      <h3>Project two</h3>
      <p>One sentence on what it does.</p>
      <a href="#">View the code</a>
    </article>
  </div>
</section>

Yours may have different class names or an extra wrapper. That is fine. What matters is that you can find the section by its heading, because that is what you are about to change. The rule that puts those cards side by side lives in style.css as a display: grid on .project-grid, with a @media query that collapses it to one column on narrow screens. You do not need to write that. You do need to know it exists.

Checkpoint: index.html and style.css both exist, and you can point at the Projects section in the HTML.

Step 3: Put your real projects in

A template with placeholder text is not a portfolio. Hand Claude the real content in one go:

In the Projects section, replace the placeholders with these four projects.
For each: a title, one sentence on what it does, and a link.

1. Sales dashboard. A Python script that turns our monthly CSV export into a
   chart pack. https://github.com/yourname/sales-dashboard
2. Churn model. A scikit-learn classifier that flags accounts likely to cancel,
   trained on 18 months of billing data. https://github.com/yourname/churn
3. Invoice parser. Pulls totals out of PDF invoices into a spreadsheet, built
   to kill a two-hour weekly job. https://github.com/yourname/invoice-parser
4. Weeknotes. A short blog about moving from analysis into machine learning.
   https://yourname.substack.com

Then replace the intro paragraph with these two sentences: [your own text].

The more specific and real your content, the less generic the result looks. Now for the skill that outlasts this project: how you ask for changes. Beginners type "make it look better" and get a random restyle that quietly undoes something they liked. Specific asks get the change you actually meant, for example "make the project cards two columns on desktop and one on mobile, with 24 pixels of space between them, and make the project titles slightly larger than the body text." Same effort, predictable result.

Give yourself an undo before you start experimenting. Either run git init and make one commit now, so you can always get back to a working page, or at minimum add "show me what you plan to change before you change it" to your prompt. A beginner who cannot undo will not experiment, and experimenting is the whole point.

Then your photo. Straight off a phone it is typically 4 to 6 MB, enough to make the page feel slow on mobile. At 1200 pixels wide it lands around 150 to 250 KB and looks identical on screen. Ask directly: "resize hero.jpg to 1200 pixels wide, save it as hero-small.jpg, and point the page at the new file."

Checkpoint: The Projects section shows your actual work, and the intro reads in your own voice.

Step 4: Preview it on your own machine

Before it goes public, look at it locally. From inside the folder, try these in order until one works:

python -m http.server 8000
py -m http.server 8000
npx serve

Most Macs and Linux machines run the first one. On Windows, python often opens the Microsoft Store instead of running anything, which is what the second line fixes. If neither works you do not have Python, and the third line uses Node instead, which is your prerequisite check showing up again.

Open http://localhost:8000 in your browser. Then narrow the window until it is about 375 pixels wide, roughly the width of a common phone. Three things to look for: text stays readable without pinching, the project cards stack into one column rather than squeezing, and nothing forces you to scroll sideways. Sideways scroll almost always means a fixed pixel width on an image or a container, and it is a one-line fix to ask for. Press Ctrl+C in the terminal to stop the preview.

Checkpoint: Your portfolio loads at localhost:8000 and still reads well at 375 pixels wide.

Step 5: Add the parts that make it findable

Most tutorials stop one step earlier. For a career changer this is the half that matters, because a portfolio exists to be pasted into a message, an application or a reply to a recruiter. As built so far, your page renders as a bare grey link when pasted, and it is invisible to anyone searching your name. Ask Claude Code for a proper head block:

<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Jane Okafor, Data Analyst and Machine Learning Projects</title>
  <meta name="description" content="Portfolio of Jane Okafor: Python dashboards,
    a churn model and an invoice parser, built while moving into machine learning.">
  <link rel="icon" href="favicon.png">

  <meta property="og:title" content="Jane Okafor, Data Analyst">
  <meta property="og:description" content="Python and machine learning projects, with code.">
  <meta property="og:image" content="https://yoursite.com/og-card.png">
  <meta property="og:url" content="https://yoursite.com">
</head>

Four of those lines earn their place. The <title> is what a search engine prints and what the browser tab says, so put your actual name in it. The viewport line is what makes the mobile layout work at all, and leaving it out is the most common reason a "responsive" page still looks tiny on a phone. The og: tags follow the Open Graph protocol, which is what LinkedIn, Slack and most messaging apps read to turn a pasted link into a card with a title, a sentence and an image. Ask Claude for a 1200 by 630 pixel image to point og:image at. Finally, add alt text to your photo and any project images: one plain sentence describing what is in the picture, which serves screen readers and anyone whose images fail to load.

Checkpoint: Viewing the page source shows a title containing your name, a description, and og: tags.

Step 6: Put it on the public web

Your node --version answer from the prerequisites decides which route you take. Both are free and both give you HTTPS automatically, with no certificate to buy or configure.

No Node. Go to Netlify Drop and drag your project folder onto the page. It uploads and hands you a live URL in seconds. One trap catches nearly everyone: index.html must sit at the top level of the folder you drop. Drop a folder that contains another folder that contains index.html and you get a "Page Not Found" screen that reads like the entire deploy failed. It did not. The file is one level too deep. The address you get is randomly generated, something like luminous-marzipan-4d2f1c.netlify.app. You are not stuck with it: open the site settings, change the site name, and the subdomain changes with it.

With Node. Run npx vercel inside the folder. It walks through a short sequence: log in (it opens a browser to confirm), "set up and deploy" yes, choose your own account as the scope, "link to an existing project" no, and press Enter to accept the current directory. The last question is the one that trips people, asking whether you want to override the build settings. For a plain HTML site the answer is no, because there is nothing to build. Saying yes drops you into settings you do not need. The Vercel CLI docs cover the rest.

To put your own domain on it, buy one from any registrar and remember that two dashboards must agree. First, in your host's dashboard, add the domain, which produces the exact DNS values to use. Then at the registrar create the records: an A record for the bare domain (some registrars offer ALIAS or ANAME instead, which works too) and a CNAME for the www version. Copy the values from your host's dashboard rather than from any blog post, because they change.

Propagation is usually minutes and occasionally as long as 48 hours. The HTTPS certificate is issued after DNS resolves, so a brief browser security warning in the first few minutes after switching is normal and clears itself. The failure I see most often is doing one side only: records set at the registrar while the host has never been told the domain exists, or the reverse.

Checkpoint: Your site loads at a public URL for someone who is not on your computer, and pasting that URL into a message shows a card rather than a bare link.

Where this breaks

You ask for too much at once. The fastest way to a broken first build is "make it look like a startup landing page with animations and a blog and dark mode." One student asked for a dark mode toggle before the Projects section had any real text in it, and we spent 20 minutes styling two themes for a page that still said "Project two." Get one honest page live, then add. Scope creep is the number one thing I watch stall beginners.

The deploy fails on a config detail. The error you are most likely to meet is Netlify's "Page Not Found. Looks like you've followed a broken link or entered a URL that doesn't exist on this site." That is almost never a broken build. It is index.html sitting one folder too deep. When any error you do not recognise appears, paste it straight back into Claude Code and ask what it means before you change anything. The message is usually the whole answer.

Your project folder is inside a synced drive. OneDrive, iCloud and Dropbox all rewrite files underneath you, which produces file locks and permission errors that look like the AI is malfunctioning. In one logged session a safety check refused to write to a synced path outright. That failure and five others are collected in six setup problems that stall every AI beginner. Move the folder somewhere plain and the whole category disappears.

It looks generic. That is a content problem, not a code one. Real project descriptions, a real photo, and one sentence in your own voice fix it faster than any amount of styling. If your intro could belong to anyone in your field, it is not finished.

What to build next

Once the site is live, the natural next step is giving it something to show. Adding a small project you built yourself, like a first RAG app, turns a portfolio into proof rather than a list of claims. And if you want to go beyond a static page later, the Claude Code tutorial covers the more capable builds, the ones with a backend and real data behind them.

If you want to build this with someone watching your screen and unblocking you the moment something breaks, that is exactly what my sessions are. Book a free Discovery Call and bring the projects you want to show off.

These tutorials come from the actual curriculum I teach 1-on-1. Every step here I have run myself before publishing it.