Init Astro project from an HTML file

Nội dung này hiện chưa có sẵn bằng ngôn ngữ của bạn.

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

GitHub repo: empty, OR containing only README.md / LICENSE / .gitignore / .gitattributes / .github/. The default GitHub “Initialize with README” is fine.
Cloudflare Pages project connected to the repo (framework preset “Astro”). The first build will fail because there’s no code yet — that’s expected.
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

{
  "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)

.
├─ 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

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

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

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

Want to…	Use
Add a new route	`create_astro_route` (preview branch, safe default)
Edit a component / style	`write_astro_file`
Push many files at once	`bulk_write_astro_files`
Promote preview → main	Merge the branch on GitHub web, or super-admin flips `allow_main_branch_push` temporarily
Reset preview to start fresh	`reset_astro_preview_branch`

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

Code	Meaning
`E_FULL_REPO_WRITE_NOT_ALLOWED`	Site doesn’t have `allow_full_repo_write` enabled. Super-admin must turn it on first.
`E_MAIN_BRANCH_LOCKED`	Default 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_EMPTY`	Repo has files beyond README/LICENSE/.gitignore/.gitattributes/.github. Pass `force=true` to push into a preview branch and review before merging.
`E_BAD_ROUTE`	A route in `extra_pages` failed validation (illegal segment, traversal, etc.).
`E_BAD_INPUT`	Missing required field, or `/` showed up in `extra_pages` (reserved for `homepage_html`).