Web · Setup

Setup — for Peter

The one-time work that stands up the SuperStories website system. Once these steps are done, the PM operates it using the workflow page, the VA and the client are brought on through the onboarding page, and why this beats the alternatives is on the comparison page.

This is the one heavy build. Plan a focused half-day to a day for the template itself. After that, every client site is a clone, and the technical part of a new site drops to 30 to 60 minutes.

The stack, and why

• Astro builds the site statically. Visitors get ready-made pages, so the site is fast and scores well on Core Web Vitals and SEO. Astro can source content from anything, which keeps the content layer swappable.
• Sveltia is the editor (a git-based headless CMS). The client edits text and photos in a web form. Content is stored as markdown / JSON in the repo, not in a vendor's database.
• GitHub is the single source of truth. Code and content live together with full version history.
• Coolify hosts and rebuilds the site on every commit. SSL included.

Why git-based, not Sanity or a hosted CMS: ownership and no lock-in. The content lives in your own git, so there is no free tier that can be revoked and no vendor holding the content. Sveltia is open-source software you run, not a SaaS plan that can be repriced. The only dependency is the git host, which already holds the code. For a portfolio of small client sites this is the safe, free, repeatable choice. Reserve a hosted CMS for a site that genuinely outgrows flat files (heavy relational content, a translation team with roles, thousands of documents).

Step 1 — Build the Astro + Sveltia template once

This is the asset. Build it once, clone it forever.

1. New Astro project. Port the design (for the first client, markandreas.com, the hand-built HTML is the design reference).
2. Model the content as Astro content collections: page sections, method/spoke pages, and any list types the client needs. The fields here are exactly what the client will edit.
3. Keep components generic and brand-driven so a clone restyles fast.
4. Commit to a private GitHub repo. This repo is the starter; future sites clone it.

The two time sinks the first time: porting the design into Astro components, and the editor auth in Step 3. Both become a fixed pattern after the first run.

Step 2 — Define the Sveltia content schema

The Sveltia config (config.yml or equivalent) defines the collections and fields the client sees. This maps one-to-one to the Astro content collections.

• Name fields in plain language the client understands (Heading, Intro, Photo, Button text).
• Group by page so the editor reads like the site.
• Add image fields that upload into the repo's media folder.
• For multi-language sites, define locales here. Sveltia gives side-by-side editing and optional DeepL drafts; it pairs with Astro's native i18n routing. Not needed for an English-only site like markandreas.com.

Step 3 — Wire the editor login (GitHub auth)

Sveltia talks to GitHub through an OAuth app plus a small auth helper. This is the fiddly part the first time.

1. Create a GitHub OAuth app for the editor.
2. Deploy the Sveltia auth helper (Cloudflare Workers based, or sveltia-cms-auth) and point the CMS config at it.
3. The admin page lives at /admin on the site. Editors log in with a (free) GitHub account.
4. Wrap /admin in a branded entry page ("Edit your website", one Log in button, reassuring copy), so the client never starts on a developer-looking screen. GitHub's own consent screen cannot be restyled (it is GitHub's domain), so the bigger lever is the guided onboarding: a VA walks the client through creating and authorizing their own GitHub identity once (see the onboarding page), so the client's recurring experience after that is just "click Log in, land in the editor."

Do not build a custom email / magic-link front-end with a shared bot account: it is custom code to maintain, it loses per-user ownership and attribution, and it adds attack surface. Sveltia over GitHub, softened by the branded entry and guided onboarding, is the right balance.

Once this pattern is proven on the first site, a clone reuses it by re-pointing the OAuth app and config at the new repo.

Step 4 — Host on Cloudflare Pages (client-owned), with auto-rebuild

Default host is Cloudflare Pages: it builds Astro from the repo on every commit and serves the static site from a global CDN, with SSL and edge security included. Free tier covers a client site. Nothing to maintain, no server to patch. You are not a hosting company; Cloudflare is.

Ownership model. The client owns and creates the three pieces themselves: the domain, the Cloudflare account, and the GitHub account / repo. You and the team get collaborator access to deploy and maintain. This maximises ownership and keeps the client off any dependence on you as a host. The cost is a one-time account setup, which the guided onboarding handles (see the onboarding page). The domain is the ownership anchor; content is portable in git regardless, so there is no lock-in.

1. Client creates the GitHub repo (or you create it and transfer; default is the client creates it under their own account) and the Cloudflare account; they add you as collaborator.
2. Connect the repo to a Cloudflare Pages project. Build command runs Astro; output dir is the static build. Each commit triggers a rebuild, so a client save in Sveltia goes live in about a minute.
3. Point the domain and enable SSL (automatic on Cloudflare).

Alternative: Coolify on a server you control (Hetzner), if you want one ecosystem with the rest of SuperStories. That means you own server upkeep (updates, SSL, firewall). A static site there is still safe, but it is a server someone maintains. Cloudflare Pages is the lower-burden default for client sites.

Step 5 — SEO, AEO, and the discovery basics

Built into the template so every clone inherits them:

• Per-page unique <title>, meta description, and canonical. Exactly one <h1> per page.
• JSON-LD schema: Person, ProfessionalService / LocalBusiness, Course, Book, FAQPage where they apply.
• sitemap.xml, robots.txt, clean human-readable URLs.
• llms.txt at the web root, so AI answer engines can read what the site is.
• Answer-first copy and FAQ blocks, so LLMs can lift clean definitions.

Step 6 — The connected system (leads, analytics, search)

• GHL is the CRM: the form, the follow-up, the calendar. I&Y wire it. Every enquiry captures found ("how did you find me"), UTM, referrer, landing page, and segment.
• Umami, self-hosted on Coolify, for privacy-first traffic analytics. No cookie banner.
• Google Search Console for the search slice. Google Business Profile for the local and brand slice, set up in-house.

Step 7 — The repo structure for client sites

Brand foundations and decision docs are text. They live in this proprietary repo under websites/, mirroring the video shape.

websites/
├── recipes/                 ← cross-client knowledge
│   ├── intake-template.md   ← the fillable client intake
│   └── astro-sveltia-template.md  ← the starter pattern, components, schema notes
└── clients/<client>/
    ├── README.md            ← what this instance is, links to the live repo
    ├── CONTENT.md           ← verified facts, offer, booking paths, NAP, image manifest
    └── decisions.md         ← positioning calls and deltas from the template

The live site itself is its own git repo (cloned from the starter), not stored here. This folder holds the foundation and the decisions, the same way video/clients/ holds brand guides.

Step 8 — The review surface

Every page in review carries the SuperStories annotation tool (annotations.superstories.com), bucketed per project. It is a review tool only: the script and its config come off before production. This is how Peter and the client leave feedback during the build.

What does NOT live in this setup

• A hosted CMS by default. Git-based (Sveltia) is the default; reserve Sanity for a site that truly outgrows it.
• A second CRM. GHL is the CRM, Airtable is not.
• The live site in this proprietary repo. The site is its own repo; this holds the foundation.
• Client copy written by us. The client owns it in the editor.
• The review tools in production. They come off before launch.

Build timeline — the one-time template

End of the build: a working, editable, fast site, and a starter repo that clones in minutes. Every site after this reuses it; see the workflow page for what the PM then runs.