Skip to content
SEO Navigator Docs

Init Astro project from an HTML file

This is the most common starting point: you have an HTML file ready (often generated by Claude or designed by hand) and a fresh GitHub repo wired to Cloudflare Pages. You want to “make it live” without manually scaffolding Astro on your laptop.

The init_astro_project tool does it in one MCP call.

Prerequisites

Section titled “Prerequisites”
  1. GitHub repo: empty, OR containing only README.md / LICENSE / .gitignore / .gitattributes / .github/. The default GitHub “Initialize with README” is fine.
  2. Cloudflare Pages project connected to the repo (framework preset “Astro”). The first build will fail because there’s no code yet — that’s expected.
  3. Site registered in /admin/sites as platform=astro, with:
    • GitHub repo + branch (usually main)
    • CF Pages project slug
    • Danger Zone: Allow full repo write ✔ (required)
    • Danger Zone: Allow direct push to primary branch ✔ (required for default main-branch init)

The tool

Section titled “The tool”
{
  "site_id": "my-astro-site",
  "project_name": "My Astro Site",
  "homepage_html": "<full HTML or fragment for src/pages/index.astro>",
  "homepage_title": "Optional — overrides <title>",
  "extra_pages": [
    { "route": "/playbook", "html": "<playbook HTML>", "title": "Playbook" },
    { "route": "/about",    "html": "<about HTML>" }
  ],
  "force": false
}

What it writes (one commit)

Section titled “What it writes (one commit)”
.
├─ package.json         astro@^5 + @astrojs/check + typescript
├─ astro.config.mjs     defineConfig, no integrations (add Tailwind/MDX later)
├─ tsconfig.json        extends astro/tsconfigs/strict
├─ .gitignore           node_modules, dist, .astro, .env*
├─ README.md            stub with project_name
├─ src/
│  ├─ env.d.ts
│  ├─ pages/
│  │  ├─ index.astro    homepage_html wrapped (standalone, no Layout)
│  │  └─ <extras>.astro one per extra_pages entry
│  └─ styles/
│     └─ global.css     minimal CSS reset
└─ public/
   └─ favicon.svg

The homepage_html (and each extra page’s html) is wrapped as a standalone .astro page: full <html>/<head>/<body> shell, no shared Layout component. This preserves the caller’s design system intact — inline <style> blocks, <script> tags, Google Fonts <link>s all survive.

The original <title> is replaced with the supplied homepage_title (or project_name if omitted) so SEO is consistent.

The Astro file includes an MCP marker comment so update_astro_route can recognise it as MCP-managed later.

Why “standalone” instead of a shared Layout

Section titled “Why “standalone” instead of a shared Layout”

If the HTML you push already has a complete design (fonts, CSS variables, inline styles, scripts) — which is typical for hand-built or LLM-generated landing pages — a shared Base.astro Layout would conflict with it. Standalone pages just work.

You can refactor to a shared Layout later by writing it as a component (bulk_write_astro_files makes that one commit) and rewriting individual pages to use it.

After init

Section titled “After init”

The tool returns:

{
  "repo": "owner/site",
  "branch": "main",
  "commit_sha": "abc123…",
  "files_written": 9,
  "files": ["package.json", "astro.config.mjs", "…"],
  "repo_was_empty": true,
  "build_status": "pending",
  "note": "Initialised Astro project on 'main'…"
}

Call check_astro_deploy with the commit_sha to watch the Cloudflare Pages build:

{ "site_id": "my-astro-site", "commit_sha": "abc123…" }

When the status is success, the production URL is live. The first build typically takes 30-90 seconds.

After the project exists

Section titled “After the project exists”

For subsequent edits, use the single-file or bulk tools instead of re-running init_astro_project:

Want to…Use
Add a new routecreate_astro_route (preview branch, safe default)
Edit a component / stylewrite_astro_file
Push many files at oncebulk_write_astro_files
Promote preview → mainMerge the branch on GitHub web, or super-admin flips allow_main_branch_push temporarily
Reset preview to start freshreset_astro_preview_branch

When NOT to use this

Section titled “When NOT to use this”
  • Repo has a real project already: refuses with E_REPO_NOT_EMPTY. Pass force=true to override (writes to a preview branch — does not blow away main).
  • You want Tailwind/MDX from day 1: the baseline is intentionally minimal. Either run a second bulk_write_astro_files to add the integration, or hand-edit astro.config.mjs + package.json immediately after init.
  • Layout-driven multi-page site: standalone wrapping is wrong for this case. Use bulk_write_astro_files directly with your Layout component + page templates.

Error reference

Section titled “Error reference”
CodeMeaning
E_FULL_REPO_WRITE_NOT_ALLOWEDSite doesn’t have allow_full_repo_write enabled. Super-admin must turn it on first.
E_MAIN_BRANCH_LOCKEDDefault mode pushes to main. Either enable allow_main_branch_push for the site, or pass force=true (which switches to a preview branch).
E_REPO_NOT_EMPTYRepo has files beyond README/LICENSE/.gitignore/.gitattributes/.github. Pass force=true to push into a preview branch and review before merging.
E_BAD_ROUTEA route in extra_pages failed validation (illegal segment, traversal, etc.).
E_BAD_INPUTMissing required field, or / showed up in extra_pages (reserved for homepage_html).