How to Build and Host a Static Astro Site with GitHub Copilot Agent Mode

Cover image for How to Build and Host a Static Astro Site with GitHub Copilot Agent Mode

This guide shows how to design, build, manage, and deploy a static website. You will use GitHub Copilot Agent mode, Impeccable UI Design, Astro, a custom local CMS, and GitHub Pages.

Note: These steps and prompts also work with other AI coding tools, such as Claude Code, Codex, or Antigravity.

Step 1: Product Definition

Define your project scope before you write code. Clear choices early prevent rework later.

  • Intended audience: Identify who will read the site and what problem they need to solve.
  • Site goal and visitor action: State what visitors should do or learn, such as reading guides, viewing work, or following a link.
  • Languages and URL structure: Decide if the site uses one language or multiple locales. Note date rules and path rules for each language.
  • Core features and pages: List the required pages, navigation items, search options, RSS, or contact links.
  • Content types and fields: List each content type and its required fields. This supports Astro Content Collections and your custom local CMS.
  • Media and downloadable files: List images, diagrams, icons, or files to store in the repository.
  • Legal and privacy pages: Plan required pages such as an imprint or privacy policy. Check local rules for external links and embedded media.
  • GitHub Pages URL plan: Note if you start on username.github.io/repo-name or a custom domain. This affects site and base settings later.

Prompt: Refine Product Definition

Help me complete the product definition for a static Astro site hosted on GitHub Pages.
Ask short questions about:
- Target audience and main goal
- Pages, features, and content types with fields
- Languages, media needs, and legal pages
- Hosting URL or custom domain plans

Then summarize the final product scope in clear, short sentences.

Step 2: Install Tools and Skills

Install the local runtime and the skills before you start your coding agent.

1. Install Node.js and pnpm

  1. Install Node.js (Node.js 22 or newer is recommended for Modern Web Guidance).
  2. Enable pnpm so you can run project scripts and manage packages.
  3. Open your project folder in your code editor or terminal.

2. Install Impeccable UI Design

Use Impeccable ([https://impeccable.style](https://impeccable.style)) to explore design options and refine your layout.

  1. Run npx impeccable install in your project folder.
  2. Select GitHub Copilot (or your coding tool) when the installer prompts you.
  3. Choose whether to install for this project or globally.
  4. Allow the design hook if your tool supports it.
  5. Reload your editor or coding agent so the skill loads.

3. Install Google Modern Web Guidance

Use Modern Web Guidance to guide your agent toward modern web platform patterns and browser compatibility checks.

  1. Run npx modern-web-guidance@latest install in your project folder.
  2. Follow the setup prompts to choose your target agent and options.
  3. In Copilot CLI, you can also run /plugin marketplace add GoogleChrome/modern-web-guidance and /plugin install modern-web-guidance@googlechrome.
  4. Reload your editor or coding agent so the skill becomes active.

Step 3: Base Setup in Astro

Use these prompts in GitHub Copilot Agent mode to create the Astro foundation, SEO files, and dev script.

Prompt: Scaffold Astro Base and Dev Script

⚠️ Human Input Required: Replace [target audience] and [list core features] with your project details before you send this prompt.

Create a static Astro website for [target audience] with [list core features]. Use TypeScript for Content Collection schemas, utilities, and Astro components. Use Content Collections for content entries and keep pages statically prerendered. Add a "dev" script in package.json that starts the local Astro development server. Apply the Impeccable UI Design skill to propose design options and build the layout, then apply Google Modern Web Guidance to refine the HTML.

Prompt: Add RSS, Sitemap, and Search Optimization

⚠️ Human Input Required: Provide your target site URL (for example, [https://username.github.io](https://username.github.io) or [https://example.com](https://example.com)) when prompted by the agent.

Configure "site" in astro.config.mjs and add @astrojs/sitemap so building generates sitemap-index.xml.
Install @astrojs/rss and create src/pages/rss.xml.js to generate an RSS feed from the content collection.
Add canonical links, meta descriptions, and a robots.txt file in public/ that references the sitemap URL.

Step 4: Design with Impeccable and Custom Preferences

After you create the base Astro site, use Impeccable to shape the visual design around your own preferences. Impeccable helps you compare options, apply targeted edits, and save your design rules for later steps.

How to Create a New Design from Your Preferences

  1. Save project context: Run setup or initialization in Impeccable so the agent records your audience, purpose, and constraints.
  2. State your preferences and limits: Name your preferred mood, colors, fonts, and layout style. State clear limits, such as avoiding generic gradients or default fonts.
  3. Compare design variants: Ask Impeccable to generate multiple options for a section or component in your running page. Pick the option that matches your vision and keep it in your source files.
  4. Refine by area: Use focused commands or plain instructions for layout, typography, colors, spacing, and interactions. Review the result in the browser on desktop and mobile sizes.
  5. Save your design system: Document the final palette, typography, layout rules, and components in DESIGN.md. Future prompts and CMS edits will then follow the same visual system.

Prompt: Create a New Design Based on Your Preferences

⚠️ Human Input Required: Fill in all bracketed fields ([describe audience, tone, and visual mood], [list preferred colors...], etc.) with your design preferences before you run this prompt.

Use the Impeccable UI Design skill to design a new visual direction for this Astro site based on my preferences.
My preferences:
- Audience and mood: [describe audience, tone, and visual mood]
- Color palette: [list preferred colors, neutral tint, and contrast rules]
- Typography: [name heading and body font choices, or style direction]
- Layout and components: [describe page structure, spacing, and card or list style]
- Things to avoid: [list styles, colors, fonts, or patterns you do not want]

First, propose 3 distinct design options that match these preferences and explain the trade-offs.
After I choose an option, apply it to the Astro layouts and components, run a design review and polish pass, and save the chosen design system in DESIGN.md.

Step 5: Custom Local CMS for Your Features

Build a custom local CMS tool that matches your Astro Content Collections and site features. Keep it strictly for local editing.

Prompt: Build Custom Local CMS with pnpm cms and Clean Static Build

Create a custom local content management tool in this Astro project tailored to the exact Content Collections and fields defined for my site features.
Write changes directly to the local content files so Astro hot-reloads the dev server and the CMS editor reloads on changes.
Add a "cms" script in package.json ("pnpm cms") that starts the custom local CMS and runs the Astro dev server together.
Ensure the production static build ("astro build") excludes all CMS routes, scripts, and dev links so the deployed site contains zero CMS code.

Step 6: GitHub Actions Pipeline for GitHub Pages

Use the official Astro GitHub Action (withastro/action) to build and deploy static output to GitHub Pages.

Prompt: Create GitHub Actions Workflow

Create .github/workflows/deploy.yml using the official Astro GitHub Action (withastro/action) to build the static Astro site and deploy it to GitHub Pages on pushes to the main branch.
Configure workflow permissions (contents: read, pages: write, id-token: write) and use actions/deploy-pages.

In your GitHub repository, open Settings > Pages and set Source to GitHub Actions.

Step 7: Social Media Sharing Previews

Add Open Graph and Twitter card metadata so chat apps like WhatsApp show rich link previews.

Prompt: Add Open Graph and Social Share Tags

Add Open Graph (og:title, og:description, og:type, og:url, og:image) and Twitter card meta tags to the shared base layout.
Support per-page overrides for title, description, and preview image URLs, and ensure image URLs resolve to absolute URLs using Astro.site.

Step 8: Verify Modern Web Standards with Google Modern Web Guidance

Run a final check with Google Modern Web Guidance before you ship. This step checks your HTML, CSS, JavaScript, and dependencies against modern web platform practices and Baseline browser support.

How to Run the Verification

  1. Confirm your target browser support: Declare your Baseline target or browser support rules in your project instructions.
  2. Run a modernization and code scan: Use Modern Web Guidance to inspect your files for outdated patterns, unnecessary scripts, and legacy workarounds.
  3. Review accessibility, performance, and security: Check keyboard focus, semantic HTML, layout stability, and safe defaults.
  4. Verify in a real browser: Build and open the site in browsers to confirm layout and interactive behavior.

Prompt: Verify Modern Standards Across the Site

Use the Google Modern Web Guidance skill to verify that this static Astro site follows modern web standards.
Check the HTML, CSS, JavaScript, and package.json for outdated patterns, unnecessary workarounds, and browser compatibility issues against Baseline.
Review accessibility, performance (such as layout shift and loading), and security practices.
Report any findings, apply safe modern web fixes, and verify that the static build still passes.

Optional Step: Custom Domain and Base URL

Follow the GitHub Pages Custom Domain Documentation to map your domain.

  • Apex domain (example.com): Add the GitHub Pages A records (and optional AAAA records) at your DNS provider.
  • Subdomain ([www.example.com](https://www.example.com) or blog.example.com): Add a CNAME record pointing to <username>.github.io.
  • Repository setting: Enter your custom domain under Settings > Pages > Custom domain and enable HTTPS.

Prompt: Update Site and Base URL for Hosting Changes

⚠️ Human Input Required: Specify your exact custom domain or repository path when running this prompt so the agent sets site and base accurately.

Update "site" and "base" in astro.config.mjs for the new hosting URL.
If moving to a custom domain or root path, set "site" to the full custom domain URL and set or clear "base" as needed.
Update internal links, canonical URLs, RSS links, and Open Graph URLs so they match the new base path without broken routes.

Daily Workflow: How to Work with Your Site and Add Content

Once your site is set up, updating it takes only a few minutes. Here is how your day-to-day workflow works:

  1. Start your local environment: Run pnpm cms in your terminal. This launches both your local Astro preview server and your custom CMS editor side-by-side.
  2. Create or edit content: Open the local CMS in your browser to add new posts, update existing pages, or upload images. Because everything writes directly to your local Markdown/content files, you can preview your changes instantly with live hot-reloading.
  3. Publish your changes: When you are happy with how the site looks locally, commit and push your updated files to the main branch on GitHub (git add ., git commit -m "Add new post", git push).
  4. Automatic deployment: Your GitHub Actions pipeline automatically triggers, strips out all local CMS tools, builds the static Astro site, and deploys the live update to GitHub Pages.

Conclusion

It has never been easier to create a Jamstack site. With AI coding agents, modern frameworks like Astro, and free static hosting on GitHub Pages, you can go from an initial idea to a fast, custom-designed, and automated website in a single afternoon. So go out and build one!

Related posts