Ship & extend

Files, git & deploy

What is generated, what is yours, and how a sitereal project ships.

A sitereal project is a repository. Everything the builder does ends up as a file change you can read, review and revert — which means the way you ship it is the way you already ship Astro sites.

Files

The Files view browses the whole repo: one folder at a time, with a breadcrumb and Root always a click away, plus a search that matches paths across the project. Files open in the editor with syntax colouring; you can create, rename and delete.

Generated files are marked. They open read-only-ish — you can look, but the next save overwrites them, so edit them through the tool that owns them:

Everything else is yours: src/layouts/PlainBase.astro, anything you write by hand, your own components, astro.config.mjs, package.json.

Version control

The Git panel does the everyday four:

• Branches — see local and remote, switch, create.
• Commit — stage everything and commit with a message.
• Pull — fetch and bring the current branch up to date.
• Push — stage, commit and push in one action.

Every project gets git init when it is created. That is not a nicety: without its own repository, a git command run inside the folder walks up until it finds one, and a project created inside another checkout would quietly commit into that.

GitHub

Connect an account (through the GitHub CLI) and you can create a repository, pick an existing one, or paste a remote URL. Only the pointer to the remote changes — disconnecting leaves your history and your files exactly where they are.

What a good diff looks like

Because site.sitereal is written with a stable key order, a one-field change is a one-line diff rather than a reshuffle of the file. And because pages emit as ordinary .astro, a pull request shows the actual markup that changed:

- <h1 builder-data-element="heading" class="hero__title">Hello</h1>
+ <h1 builder-data-element="heading" class="hero__title">Hello, world</h1>

Reviewers do not need sitereal to review a sitereal change.

Building and deploying

Nothing special:

npm run build      # a static site in dist/
npm run preview    # serve exactly what you just built

Deploy dist/ anywhere static — Netlify, Vercel, Cloudflare Pages, S3, a VPS with nginx. Or point a host at the repository and let it run npm run build on push, which is what the GitHub connection is for.

If your project needs SSR, add the adapter Astro provides and configure it in astro.config.mjs. sitereal does not sit in that decision — it writes pages, Astro decides how they are rendered.

Handing over to a host that cannot build

Some hosting does not build anything. A cPanel or Plesk plan bought for WordPress has an FTP login, a public_html and no Node anywhere near it — and replacing that site should not mean moving the client to another host first. Settings → Publish → Export static site builds the project here and hands back a zip of dist/: the finished HTML, CSS, JavaScript, images and fonts. No PHP, no database.

One file in the archive is not part of the build. .htaccess replaces the one WordPress left behind — that file sends every address to index.php, so leaving it in place means the homepage works and nothing else does. Ours carries the 404 document, gzip, cache headers for the hashed assets and the project's own redirects (Settings → Redirects). Every directive is wrapped in <IfModule>, so a host missing a module skips the block instead of answering 500.

The archive holds no instructions of its own. This is the procedure:

1. Back up the whole hosting first — files and database. This is the step nobody regrets.
2. Remove the WordPress from the web root: wp-admin/, wp-includes/, wp-content/, wp-*.php, xmlrpc.php and the old .htaccess. Leaving them costs nothing in speed but leaves an unpatched WordPress on the internet, which is how sites get taken over after they are replaced.
3. Switch on hidden files before you upload. .htaccess begins with a dot, so the macOS Finder hides it (⇧⌘. toggles it) and so do most FTP clients — FileZilla under Server, Cyberduck under View, the Plesk file manager under its settings gear. This is the step that gets missed, and the site looks broken in a way that has nothing to do with the build.
4. Upload the contents of the archive — not the folder itself — into public_html/. When it is right, public_html/index.html exists and public_html/.htaccess beside it.
5. Uncomment the HTTPS block at the end of .htaccess once the certificate is installed and https:// loads in a browser. It ships commented out on purpose: forcing HTTPS before the certificate exists takes the site down rather than securing it.

Two requests say whether the .htaccess is being read at all. The status code is what a crawler goes by, and the title tells you whose error page answered:

curl -s https://example.com/no-such-page/ | grep -i '<title>'
# → your own 404 page. The hosting company's default means the file is not being read.

Changing the site later is not editing these files. They are build output and the next export overwrites them: edit in sitereal and export again.