How to choose a static site generator for AI coding assistants
What to look for, how to test it, and what to avoid.

If you already know what you need and want to see how specific tools compare, go to vagejs compared. This page is about how to decide.

What is a static site generator?

A static site generator takes files you write, usually Markdown, and turns them into finished web pages before anyone visits. The result is a folder of plain HTML, CSS and images that any web host can serve. There's no server code to keep updated and no database to break into.

That suits most content sites: company sites, product pages, documentation, blogs and portfolios. You give up features that need a live server, such as user accounts or a shopping cart running on your own machine, and you get a site that's fast, cheap to host and hard to attack.

Why does an AI assistant change the choice?

When you build a site by hand, you learn a tool's habits over time. An assistant like Claude Code, Codex, Cursor, GitHub Copilot or Gemini CLI starts every session fresh. It reads your files, makes changes, runs commands and reads the results. Four things follow from that.

It reads before it writes. An assistant opens files to understand your project. The more files and moving parts there are, the more it has to read, and the more room there is to misunderstand. A project made of plain text files and short templates is easier to get right than one with a deep stack of build plugins.

It follows written instructions. Most coding assistants look for an instruction file in the project, such as AGENTS.md (read by Codex, Cursor, Copilot and others) or CLAUDE.md (read by Claude Code). A tool that ships one with every new project tells the assistant the rules on day one: where pages live, which commands to run, what not to touch.

It needs fast, exact feedback. An assistant works in a loop: change something, run a command, read the output, fix what's wrong. Output that names the file and the problem shortens that loop. Output that's vague, or that only shows up after a deploy, makes the assistant guess.

It can be confidently wrong. Assistants sometimes invent a setting, misspell a field, or link to a page that doesn't exist, and then report the job done. The tool should catch those mistakes before your visitors do.

What should you look for?

Here's the checklist. Each point says why it matters and how to test it yourself in a few minutes.

1. Content in plain files

Pages should be Markdown files in folders, kept in git. You can read every change the assistant makes, undo any mistake, and move the content to another tool later.

How to test it: after the assistant adds a page, run git diff. You should see a readable text file, not a database export or a generated blob.

2. An instruction file in every new project

The tool should create AGENTS.md or a similar file for you, describing its real commands, folders and rules. An instruction file you have to write yourself tends to go out of date the first time the tool changes.

How to test it: create a new project and open the instruction file. Does it say where pages go, which command checks the site, and what the assistant must not do?

3. Errors that name the file to fix

The assistant reads command output and acts on it. Clear exit codes, JSON output on request, and messages that say which file and which line help it fix the right thing the first time.

How to test it: break a link on purpose and run the tool's check or build. Note whether the message names the page, the broken target and the file.

4. Strict page settings

If a page's settings (title, description, date) are checked against a list of allowed fields, a typo fails loudly instead of quietly hiding a page or dropping its description.

How to test it: misspell description as descripton in one page. A good tool stops and tells you. A weaker one builds the page without a description and says nothing.

5. Checks before publishing

Broken links, missing descriptions, accessibility slips and invalid structured data should be caught on your own machine, before anything goes live. If the tool doesn't include checks, you'll need to add and maintain separate ones.

How to test it: look for a single command that checks the whole site without publishing it. Find out whether a deploy runs it first.

6. Search and AI-search files built in

A sitemap, robots.txt, page descriptions, sharing images, structured data and llms.txt should come from the pages that really exist. When an assistant adds or deletes pages, these files should follow without anyone remembering to update them.

How to test it: add a page, build, and open the sitemap. Then delete the page and build again. The sitemap should change both times.

7. No JavaScript sent to visitors unless you ask for it

Pages that are just HTML load fast on any phone, and there's less code for anything to go wrong in. When a page really needs an interactive part, you should be able to add it to that page only.

How to test it: build the starter site and look at the size of the JavaScript on a plain text page. Zero is the right answer for a content page.

8. Careful publishing

Assistants type commands quickly. A deploy that shows a plan, waits for your yes, refuses to upload secrets and never force-pushes over your history is worth a lot.

How to test it: read the tool's deploy docs. Look for what it does before uploading, and what it refuses to do.

9. Protection against injected links

Spam links slipped into content are a common attack on websites, and an assistant copying text from elsewhere can bring them in by accident. A tool that only allows links to websites you've approved stops them at build time.

How to test it: add a link to a website you've never linked to before. Does anything ask you to approve it?

No tool scores perfectly on every point, and some points will matter more to you than others. A personal blog can live without point 9. A business site edited by several people and an assistant probably can't.

How to test drive a generator in an hour

Reading feature lists only gets you so far. The best test is to give your assistant the same small job in each tool you're considering and watch what happens.

1. Create a new project with the tool's own starter command, then open it in your assistant.
2. Ask for three pages: a home page, an about page and a contact page, each with a title and a short description. Use the same words for every tool.
3. Ask for one mistake on purpose: "Add a link from the about page to /team/." That page doesn't exist.
4. Run the tool's check or build and see whether the broken link is reported, and how clearly.
5. Ask the assistant to fix whatever was reported. Count how many attempts it takes.
6. Build and look at the output. Open the sitemap, robots.txt and any llms.txt. Check the JavaScript size on the about page.
7. Read the diff. Could you review this change in a pull request without help?

Write down what you saw for each tool. The one where the assistant needed the fewest tries and you understood every change is usually the right choice.

What mistakes do people make when choosing?

Picking by popularity alone. A large ecosystem is a real advantage, but it doesn't help if your site needs none of it. A big plugin catalogue also means more ways for an assistant to wire things together in a way you can't follow.

Choosing an application framework for a content site. If your site is pages of words and pictures, a framework built for logins and dashboards brings a server, more code and more to maintain. Our comparison pages cover where that line falls.

Trusting the assistant's "done". An assistant reporting success isn't the same as a passing check. Pick a tool whose check you can run yourself, and run it.

Leaving SEO files for later. Sitemaps and robots.txt added by hand drift out of date as soon as pages change. Generated files stay right.

Letting the assistant publish unattended. Most mistakes are cheap to fix before they're live and awkward after. Keep the final yes for yourself.

Ignoring lock-in. Content stored in a builder's database or a proprietary format is hard to take with you. Our post on website builder lock-in explains why plain files matter.

Which tool fits which kind of site?

Short version: tools differ in what they run on, how much JavaScript they send to visitors by default, and whether checks before publishing, llms.txt and interactive components are built in. vagejs runs on Node.js, sends no JavaScript by default, and has all three built in: checks (vage check), llms.txt and React islands. Most other generators have none or only some of these built in.

For a side-by-side table of specific tools, what each is like to work with and who it suits, read vagejs compared. Tools change often, so check their own docs before you decide.

Using Claude Code with a static site generator

Claude Code works with any static site generator, but a few habits make the results more reliable.

Give it the rules in writing. Claude Code reads CLAUDE.md at the start of a session. If your tool ships an AGENTS.md, a one-line CLAUDE.md that says @AGENTS.md pulls it in, which is exactly what a new vagejs project has. Our Claude Code guide walks through the setup.

Ask for small changes and a check after each one. "Add a pricing page with three plans from docs/plans.md, then run npm run check and fix anything it reports" works better than "build my website". The check output tells Claude Code exactly what to fix, and you can read the result before moving on.

Keep publishing in your own hands. Let the assistant build and check. Read the deploy plan yourself, and approve it yourself.

Reuse prompts that work. Our prompt library has ready-made prompts for common jobs: starting a site, adding content, fixing problems and publishing safely.

The same advice carries over to Codex, Cursor, GitHub Copilot and Gemini CLI. Each reads an instruction file, runs commands and reads the output. The agents overview covers the differences.

Try the checklist on vagejs

vagejs was made with these points in mind, so it's a fair place to start your test drive, and a fair one to judge against the checklist. You need Node.js 22.12 or newer. Then, in a terminal:

npm create vagejs@latest my-site
cd my-site
npm install
npm run dev

Open the address the dev server prints, then run the one-hour test from earlier:

1. Open the project in your assistant. Claude Code, Codex, Cursor or another tool will find AGENTS.md and learn the rules.
2. Ask for the three pages and the broken link. For example: "Add About and Contact pages in plain English, link the about page to /team/, follow AGENTS.md and run npm run check."
3. Read the check output. The broken link is reported with the page and the file to fix.
4. Look at what was generated. Run npm run build and open dist/sitemap.xml and dist/llms.txt. They list exactly the pages you published.
5. Publish when you're ready. npx vage deploy shows what it will do and waits for your yes. See deployment for GitHub Pages, Cloudflare and Netlify.

The getting started guide covers the same steps in more detail, and checks and audits lists everything vage check looks for. For the full list of what's included, see features.

When isn't vagejs the right pick?

vagejs does one kind of site well, and it isn't the right tool for everything.

• Your site is mostly interactive, or you need Vue or Svelte islands. vagejs can make individual React components interactive, but it's built for pages that are mostly content. A framework built for interactive sites will serve you better.
• Your site needs a server. User accounts, payments handled on your own server, or pages that change for each visitor. Use an application framework.
• You want a hosted editor for non-technical colleagues. vagejs has a local editor that runs on your own computer, but no online admin screen. A typical CMS or a hosted builder may suit your team better, as our comparison pages discuss.
• You need a large ecosystem today. vagejs is new. Themes, plugins and community answers are still few. Older static site generators have years of them.
• You have tens of thousands of pages. vagejs doesn't yet write sitemap indexes, so very large sites are better served by a generator known for fast builds at that size.

Common questions

Do I need to know how to code? A little comfort with a terminal helps. Writing pages only takes plain text, and an assistant can do the setup and the fixes. The FAQ covers more.

Will a static site rank on Google? Being static doesn't hurt. Fast pages, clear summaries and an accurate sitemap help Google understand your site, but no tool can promise rankings. Our post on why AI-built sites don't show up on Google explains what usually goes wrong.

What's llms.txt, and do I need it? It's a proposed convention: a short text file that describes your site for AI tools. Some AI tools read it. It costs nothing to publish, and it won't change your Google rankings. Our SEO and AI search docs explain how vagejs writes it.

Can I move an existing site? Yes, if its content can be exported as Markdown or plain text. Start with your most important pages, check them, and add the rest over time.