Set up Astro with GitHub Pages, migrate homepage, and publish docs as site pages by Copilot · Pull Request #1966 · counterfact/api-simulator

Copilot · 2026-04-27T23:24:53Z

Migrates the counterfact.dev homepage from Jekyll to Astro, deploying via GitHub Actions to GitHub Pages. The new-homepage branch's docs/index.html becomes the foundation. All markdown files under docs/ are published as styled pages on the site, with .md links preserved in source (works on GitHub) and stripped at build time.

Summary

Introduces a self-contained Astro v5 project under site/ with a layout/page split, wires up official GitHub Pages deployment, and migrates the dark-themed homepage HTML. CSS and JavaScript are kept in their own source files and bundled by Vite during build. An Astro content collection with a glob loader publishes every .md file under docs/ as a page at /docs/<slug>. All doc links in the source use .md extensions so they remain clickable on GitHub; a custom rehype plugin strips those extensions at build time so the site URLs are clean. Each doc page is also served at its .md-suffixed URL (e.g. /docs/getting-started.md) with a canonical link pointing to the clean URL. The site/ directory is excluded from the root ESLint configuration so its Astro/Vite-specific files are not linted by the project-level rules.

Original Prompt

We want to move this site to Astro and deploy it via GitHub Pages, using the existing index.html from the new-homepage branch as the foundation.

This should be done in a way that preserves the current homepage content while setting us up for future expansion (docs, additional pages, etc.).

Goals

Set up an Astro project in this repo
Configure deployment to GitHub Pages via GitHub Actions
Convert the existing index.html (from new-homepage) into an Astro layout/template
Use the existing homepage content as the site's root (/)

Manual acceptance tests

cd site && npm install && npm run dev — homepage renders with correct dark theme, nav, hero, and code sections
cd site && npm run build — exits 0, site/dist/ contains index.html, counterfact.svg, CNAME, and a docs/ directory with HTML pages for every markdown file under docs/
Preview with npm run preview — no broken assets, fonts load, SVG logo appears, nav "Docs" link opens /docs/getting-started (not GitHub)
Push to main — Deploy Site to GitHub Pages workflow passes in Actions
Visit https://counterfact.dev — visually matches new-homepage branch's docs/index.html
Visit https://counterfact.dev/docs/getting-started — page renders with dark theme, "← Home" link, and full Getting Started content
Click a cross-doc link (e.g. from /docs/getting-started to /docs/patterns) — navigates correctly with no .md in the URL
Open a docs/*.md file directly on GitHub — all cross-document links resolve correctly (.md extensions intact in source)

Tasks

site/ Astro project — package.json (astro v5.18.1), astro.config.mjs (static output, site: "https://counterfact.dev"), tsconfig.json, .gitignore
site/src/layouts/MainLayout.astro — HTML shell with <head>, Google Fonts links, import "../styles/main.css", and optional canonicalPath prop that emits <link rel="canonical">; exposes optional title prop
site/src/styles/main.css — ~900 lines of CSS extracted from the original inline <style> block
site/src/pages/index.astro — full body content from new-homepage/docs/index.html; curly braces in code examples escaped as {/}; references ../scripts/main.js via <script> import </script>; doc links use .md extensions (e.g. /docs/getting-started.md)
site/src/scripts/main.js — clipboard copy and IntersectionObserver JS extracted from the original inline <script> block
site/src/content.config.ts — Astro v5 content collection using glob loader, pointing to ../docs; publishes all **/*.md files as the docs collection
site/src/pages/docs/[...slug].astro — dynamic route generating two static pages per doc: a clean URL (/docs/<slug>) and a .md-alias URL (/docs/<slug>.md), both with <link rel="canonical"> pointing to the clean URL; page title extracted from the first # H1 heading with a slug-derived fallback
site/src/layouts/DocLayout.astro — dark-theme prose layout wrapping MainLayout; includes "← Home" breadcrumb and styled typography; forwards canonicalPath to MainLayout
site/astro.config.mjs — custom rehype plugin rehypeStripMdLinks strips .md extensions (including ?query and #anchor variants) from local href attributes when markdown is rendered to HTML; protocol URLs (://, mailto:, tel:) are left untouched
site/public/ — CNAME (counterfact.dev) and counterfact.svg; image src updated from ./counterfact.svg → /counterfact.svg
.github/workflows/deploy-site.yaml — triggers on main push and workflow_dispatch; uses Node 22, npm ci, and the official configure-pages / upload-pages-artifact / deploy-pages action chain
.gitignore — excludes site/node_modules, site/dist, site/.astro
docs/index.html — synced to the new-homepage branch version
eslint.config.cjs — added a dedicated { ignores: ["site/**"] } entry so the root ESLint run skips all files under site/; placed as a standalone object (ESLint flat config requires ignores-only objects for global file exclusions)

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/43628429-220a-4b27-8e3f-46cb6a0c81e2 Co-authored-by: pmcelhaney <51504+pmcelhaney@users.noreply.github.com>

pmcelhaney

Extract the inline CSS and JS into files.

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/daa2911f-811d-4bc5-958c-7eab9c30187a Co-authored-by: pmcelhaney <51504+pmcelhaney@users.noreply.github.com>

Copilot · 2026-04-27T23:45:43Z

Extract the inline CSS and JS into files.

Done in commit 27e46fe. The inline CSS is now in site/src/styles/main.css (imported via import "../styles/main.css" in the layout frontmatter), and the inline JS is in site/src/scripts/main.js (referenced via <script> import "../scripts/main.js"; </script> in the page). Both are bundled by Vite during npm run build.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /usr/local/bin/node node /home/REDACTED/work/api-simulator/api-simulator/site/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

@@ -0,0 +1,33 @@
+function copyCmd() {


pmcelhaney

The index page currently links to GitHub.com

Instead of linking to Github, I want all of the files under docs to be published to the web site.

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/a5fe156d-85a0-441e-aa8c-05215f78cec8 Co-authored-by: pmcelhaney <51504+pmcelhaney@users.noreply.github.com>

Copilot · 2026-05-04T23:52:30Z

The index page currently links to GitHub.com

Instead of linking to Github, I want all of the files under docs to be published to the web site.

Done in commit b94cd42. All .md files under docs/ are now published to the site via an Astro content collection with a glob loader. Each doc is served at /docs/<slug> (e.g. /docs/getting-started, /docs/patterns, /docs/reference, /docs/faq, /docs/comparison). The links in the homepage have been updated from GitHub URLs to the site-relative paths. 50 pages are generated in total.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /usr/local/bin/node node /home/REDACTED/work/api-simulator/api-simulator/site/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

pmcelhaney

Some of the links end in .md and some do not. I need all of the links to end in .md so that the links will still work on Github and I also need Astro to still work. I imagine the best way to do that is to keep the .md extensions in the source and strip them in the build. But if there's another standard way to solve this problem, do that.

…urce consistency Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/a80d1491-c25e-47d8-92a1-e7c33f4ae0d9 Co-authored-by: pmcelhaney <51504+pmcelhaney@users.noreply.github.com>

Copilot · 2026-05-05T00:07:38Z

Some of the links end in .md and some do not. I need all of the links to end in .md so that the links will still work on Github and I also need Astro to still work. I imagine the best way to do that i...

Done in commit 56e798b.

The approach:

Markdown source files keep .md links — they already do, so they continue to work on GitHub as-is.
astro.config.mjs rehype plugin strips .md (including ?query and #anchor variants) from all local href attributes when markdown is rendered to HTML. Cross-links like ./getting-started.md become ./getting-started in the output.
index.astro links updated to use .md extensions (e.g. /docs/getting-started.md) to be consistent with the markdown source convention.
.md-alias routes — [...slug].astro now generates both /docs/getting-started and /docs/getting-started.md serving the same page, with a <link rel="canonical" href="https://counterfact.dev/docs/getting-started"> on both to keep SEO clean.

Build generates 99 pages (1 homepage + 49 clean doc URLs + 49 .md-alias URLs).

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /usr/local/bin/node node /home/REDACTED/work/api-simulator/api-simulator/site/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

pmcelhaney

eslint is failing on new files created under the site directory. Exclude the site directory from eslint.

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/8006aa92-316a-4c32-91a9-578136f2d34d

Copilot · 2026-05-05T00:23:48Z

eslint is failing on new files created under the site directory. Exclude the site directory from eslint.

Done in commit 0c27b48. Added a dedicated { ignores: ["site/**"] } entry at the end of eslint.config.cjs. In ESLint flat config, global ignores must be in an object with ignores as the sole key — mixing it into the existing config block with linterOptions would only suppress rules for that block rather than skipping the files entirely.

Initial plan

82d0fd0

Copilot AI assigned Copilot and pmcelhaney Apr 27, 2026

Copilot started work on behalf of pmcelhaney April 27, 2026 23:24 View session

Copilot AI linked an issue Apr 27, 2026 that may be closed by this pull request

Set up Astro with GitHub Pages and migrate homepage from new-homepage branch #1965

Closed

4 tasks

Add Astro site setup and GitHub Pages deployment workflow

c9fa147

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/43628429-220a-4b27-8e3f-46cb6a0c81e2 Co-authored-by: pmcelhaney <51504+pmcelhaney@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Set up Astro with GitHub Pages and migrate homepage~~ Set up Astro with GitHub Pages and migrate homepage from new-homepage branch Apr 27, 2026

Copilot AI requested a review from pmcelhaney April 27, 2026 23:38

Copilot finished work on behalf of pmcelhaney April 27, 2026 23:38

pmcelhaney requested changes Apr 27, 2026

View reviewed changes

Copilot started work on behalf of pmcelhaney April 27, 2026 23:42 View session

Extract inline CSS and JS into separate files

27e46fe

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/daa2911f-811d-4bc5-958c-7eab9c30187a Co-authored-by: pmcelhaney <51504+pmcelhaney@users.noreply.github.com>

Copilot finished work on behalf of pmcelhaney April 27, 2026 23:46

Copilot AI requested a review from pmcelhaney April 27, 2026 23:46

github-code-quality Bot found potential problems Apr 27, 2026

View reviewed changes

Comment thread site/src/scripts/main.js

@@ -0,0 +1,33 @@

function copyCmd() {

pmcelhaney requested changes May 4, 2026

View reviewed changes

Copilot started work on behalf of pmcelhaney May 4, 2026 23:47 View session

Publish docs/ markdown files as Astro site pages at /docs/*

b94cd42

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/a5fe156d-85a0-441e-aa8c-05215f78cec8 Co-authored-by: pmcelhaney <51504+pmcelhaney@users.noreply.github.com>

Copilot AI changed the title ~~Set up Astro with GitHub Pages and migrate homepage from new-homepage branch~~ Set up Astro with GitHub Pages, migrate homepage, and publish docs as site pages May 4, 2026

Copilot finished work on behalf of pmcelhaney May 4, 2026 23:53

Copilot AI requested a review from pmcelhaney May 4, 2026 23:53

Merge branch 'main' into copilot/set-up-astro-github-pages

a448bf6

pmcelhaney requested changes May 5, 2026

View reviewed changes

Copilot started work on behalf of pmcelhaney May 5, 2026 00:01 View session

Strip .md extensions from rendered links; add .md alias routes for so…

56e798b

…urce consistency Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/a80d1491-c25e-47d8-92a1-e7c33f4ae0d9 Co-authored-by: pmcelhaney <51504+pmcelhaney@users.noreply.github.com>

Copilot AI requested a review from pmcelhaney May 5, 2026 00:08

Copilot finished work on behalf of pmcelhaney May 5, 2026 00:08

pmcelhaney approved these changes May 5, 2026

View reviewed changes

Merge branch 'main' into copilot/set-up-astro-github-pages

010ba1e

pmcelhaney marked this pull request as ready for review May 5, 2026 00:15

pmcelhaney requested changes May 5, 2026

View reviewed changes

Copilot started work on behalf of pmcelhaney May 5, 2026 00:20 View session

Exclude site/ directory from root ESLint config

0c27b48

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/8006aa92-316a-4c32-91a9-578136f2d34d

Copilot AI requested a review from pmcelhaney May 5, 2026 00:24

Copilot finished work on behalf of pmcelhaney May 5, 2026 00:24

pmcelhaney closed this May 5, 2026

pmcelhaney reopened this May 5, 2026

pmcelhaney approved these changes May 5, 2026

View reviewed changes

Merge branch 'main' into copilot/set-up-astro-github-pages

a430a09

pmcelhaney enabled auto-merge May 5, 2026 01:31

pmcelhaney added this pull request to the merge queue May 5, 2026

Merged via the queue into main with commit 948d036 May 5, 2026
8 of 9 checks passed

pmcelhaney deleted the copilot/set-up-astro-github-pages branch May 5, 2026 01:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Set up Astro with GitHub Pages, migrate homepage, and publish docs as site pages#1966

Set up Astro with GitHub Pages, migrate homepage, and publish docs as site pages#1966
pmcelhaney merged 9 commits intomainfrom
copilot/set-up-astro-github-pages

Copilot AI commented Apr 27, 2026 •

edited

Loading

Uh oh!

pmcelhaney left a comment

Uh oh!

Copilot AI commented Apr 27, 2026 •

edited

Loading

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

pmcelhaney left a comment

Uh oh!

Copilot AI commented May 4, 2026 •

edited

Loading

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

pmcelhaney left a comment

Uh oh!

Copilot AI commented May 5, 2026 •

edited

Loading

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

pmcelhaney left a comment

Uh oh!

Copilot AI commented May 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Copilot AI commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Manual acceptance tests

Tasks

Uh oh!

pmcelhaney left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

pmcelhaney left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

pmcelhaney left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

pmcelhaney left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented May 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Apr 27, 2026 •

edited

Loading

Copilot AI commented Apr 27, 2026 •

edited

Loading

Copilot AI commented May 4, 2026 •

edited

Loading

Copilot AI commented May 5, 2026 •

edited

Loading