How to wire programmatic SEO into an Astro static site: A Field Guide for SaaS Founders

Difficulty: intermediate Time: 45-90 minutes for initial setup, plus data preparation time

You're running an Astro static site for your SaaS and you need programmatic SEO pages that rank without triggering a Helpful Content penalty. You don't want to hand-write 200 comparison pages, but you also don't want to spin up a separate subdomain or pay an agency to manage a proprietary CMS. Astro's build-time generation lets you create thousands of SEO-optimized pages from structured data, deploy them on your primary domain, and serve them as static HTML with zero runtime cost.

This guide walks you through the architecture: how to structure your data source, how to use Astro's dynamic route syntax to generate pages at build time, how to inject structured data and meta tags, and how to validate output before deployment. You'll end with a working pSEO pipeline that generates pages during your CI build, serves them from your CDN, and integrates seamlessly with your existing Astro site. No subdomains, no client-side rendering, no runtime API calls.

Before you start

  1. Step 1: Structure your pSEO data source and decide on URL patterns

    Before you write any Astro code, map out your URL structure and data schema. Programmatic SEO fails when founders generate pages first and figure out URLs later. Decide now whether you're building comparison pages, alternative pages, integration pages, or location-based landing pages. Your URL pattern determines your file structure in Astro.

    For comparison pages, a pattern like /compare/[tool-a]-vs-[tool-b]/ works well. For alternative pages, /alternatives/[competitor-name]/ is standard. For integration pages, /integrations/[platform-name]/ keeps URLs clean. Whatever pattern you choose, make sure each URL segment maps to a field in your data source. If you're pulling from a CSV, your columns might be tool_a_slug, tool_b_slug, tool_a_name, tool_b_name, description, pros_cons, and pricing_comparison.

    Create a sample dataset with 5-10 rows to test your pipeline. Don't start with 500 pages. Export it as JSON and place it in src/data/comparisons.json or fetch it from a headless CMS API at build time. Astro runs server-side during the build, so you can call any API, read any file, or query any database that's accessible from your CI environment. The key constraint: all data must be available at build time, not at request time.

    Validate that every row in your data source produces a unique URL. Duplicate URLs will cause build errors or silently overwrite pages. Write a quick Node script that iterates your data and checks for collisions before you wire it into Astro.

  2. Step 2: Create a dynamic route file with getStaticPaths

    Astro generates static pages from dynamic routes using getStaticPaths. This function runs once at build time and returns an array of paths and props. Each path becomes a static HTML file in your dist/ folder. Create a new file at src/pages/compare/[slug].astro. The [slug] syntax tells Astro this is a dynamic route.

    Inside [slug].astro, export a getStaticPaths function at the top of your frontmatter section. Import your data source (or fetch it from an API), transform each row into a params object with a slug field, and return the array. For a comparison page, your slug might be tool-a-vs-tool-b. The params object must include every dynamic segment in your file path. If your path is [category]/[slug].astro, params needs both category and slug.

    Pass the full data row as props so your template has access to all fields. Astro will call your component once per path, passing params and props. This is where you map your data schema to your template variables. If your CSV has a field called tool_a_name, destructure it from Astro.props and use it in your heading tag.

    Test locally by running astro build. Astro will generate one HTML file per path. Check dist/compare/ to confirm your pages exist. Open one in a browser and view source to verify the content is in the HTML, not injected by JavaScript. If you see empty divs or client-side fetch calls, you've misconfigured the data flow.

  3. Step 3: Build your page template with SEO meta tags and structured data

    Your [slug].astro file is both a data loader (via getStaticPaths) and a template. Below the frontmatter, write the HTML structure for your pSEO page. Use Astro.props to access the data you passed from getStaticPaths. For a comparison page, you'll have a heading with both tool names, a description paragraph, a pros-and-cons table, and a call-to-action linking to your product.

    Inject SEO meta tags in the <head> section. Astro lets you define <head> content inside your component or use a Layout component. Either way, set a unique <title> tag for each page using your data. A comparison page title might be Tool A vs Tool B: Feature Comparison for [Your Niche]. Set a meta description (120-160 characters) that promises a concrete benefit and includes your primary keyword. Set og:title, og:description, and og:url for social sharing.

    Add JSON-LD structured data for BreadcrumbList and Article (or FAQPage if your template includes FAQs). Google's rich results documentation specifies the required fields. For BreadcrumbList, include your homepage and category page as parent items. For Article, include headline, datePublished, dateModified, and author. Use your data fields to populate these values dynamically. Validate your JSON-LD with Google's Rich Results Test before you deploy.

    Keep your content structure simple: H1 with the page title, H2 for each major section, and paragraphs or tables for the comparison data. Avoid walls of AI-generated prose. If your data includes bullet points for pros and cons, render them as <ul> lists, not paragraphs. If you have pricing data, use a <table> with clear column headers. Crawlers and readers both prefer structured content over narrative blocks.

  4. Step 4: Wire in your content generation strategy (template-based or AI-assisted)

    You have two paths for content: template-based (safe, predictable, limited scale) or AI-assisted (faster, riskier, requires editorial oversight). Template-based means your data source includes all prose, and your Astro component just renders it. AI-assisted means you generate prose at build time by calling an LLM API inside getStaticPaths, then pass the generated text as props. Both approaches work; your choice depends on content volume and quality tolerance.

    For template-based content, your CSV or JSON includes pre-written descriptions, pros, cons, and conclusions for each page. You write these once (or hire a writer), and Astro renders them verbatim. This is the safest approach for Helpful Content compliance because every page is human-reviewed before deployment. The downside: writing 200 unique pages takes 100+ hours. Use this approach if you're generating fewer than 50 pages or if your niche has high E-E-A-T requirements (legal, medical, financial).

    For AI-assisted content, you call an LLM API (OpenAI, Anthropic, or a local model) inside getStaticPaths, pass structured data as context, and generate prose for each page. Store the generated text in your props object. This scales to thousands of pages, but you must review output quality. Generate a sample batch of 20 pages, read them end-to-end, and check for hallucinations, repetitive phrasing, and factual errors. If more than 10% need manual edits, your prompt or data quality needs work.

    If you use AI generation, cache the results. Don't regenerate content on every build. After your first successful generation, save the output to JSON files in src/data/generated/ and commit them to your repo. Subsequent builds read from the cache. This prevents token-cost surprises, ensures consistent output, and lets you review changes in pull requests before they go live.

  5. Step 5: Add internal linking and navigation to connect your pSEO pages

    Programmatic SEO pages need internal links to pass PageRank and help crawlers discover your content. Orphaned pages (pages with no inbound links) rarely rank, even if the content is excellent. Your Astro site needs a navigation strategy that connects your pSEO pages to your main site and to each other.

    Create a category index page at src/pages/compare/index.astro that lists all your comparison pages. Use getStaticPaths to load your data, then render a grid or list of links with anchor text that includes your primary keywords. For example, "Compare Tool A vs Tool B" is better anchor text than "Learn more." This index page should be linked from your main navigation or footer so crawlers can reach it from your homepage.

    Add related links within each pSEO page. If you're building comparison pages, link to alternative pages for each tool mentioned. If you're building alternative pages, link to comparison pages that include that tool. Use your data source to define these relationships. Add a related_pages array to each data row, or compute relationships programmatically based on shared tags or categories.

    Include a breadcrumb navigation component that shows Homepage > Compare > Tool A vs Tool B. Implement this as a reusable Astro component that takes the page title and category as props. Breadcrumbs help users navigate and provide additional internal links. Match your breadcrumb HTML to your BreadcrumbList structured data so Google can display rich snippets.

  6. Step 6: Validate output quality and check for Helpful Content red flags

    Before you deploy, validate that your generated pages meet Google's quality guidelines. Helpful Content penalties target sites with thin, repetitive, or AI-generated content that provides no unique value. Your pSEO pages must pass a manual review test: if you read five random pages, can you tell them apart? Do they answer different questions? Do they provide information you couldn't get from a competitor's page?

    Run a build and open ten random pages from your dist/ folder. Read them as a user, not a developer. Check for repetitive phrasing ("In today's competitive landscape" appearing in every intro), template artifacts (placeholder text like [TOOL_NAME] that didn't get replaced), and factual errors (wrong pricing, wrong feature descriptions). If you spot patterns, fix your data source or your template logic.

    Use a tool like Screaming Frog or a custom script to crawl your dist/ folder and check for duplicate title tags, duplicate meta descriptions, missing H1 tags, broken internal links, and orphaned pages. Fix any issues before you deploy. Google treats these as quality signals. A site with 200 pages and 50 duplicate titles will struggle to rank.

    Check your page word count. Pages under 300 words are often flagged as thin content unless they're highly specific (like a single integration guide). Pages over 2,000 words better be genuinely comprehensive, not padded with filler. Aim for 500-1,000 words per page for comparison and alternative content. If your template generates 300-word pages, add more data fields (customer quotes, feature tables, pricing breakdowns) to increase unique content per page.

  7. Step 7: Deploy your Astro site and monitor indexing in Google Search Console

    Your Astro site builds to a dist/ folder containing static HTML files. Deploy this folder to your hosting provider (Vercel, Netlify, Cloudflare Pages, or any static host). Your pSEO pages are now live on your primary domain, not a subdomain. This is critical for SEO: subdomains don't inherit domain authority from your main site, and Google has historically treated subdomain-based pSEO as lower quality.

    After deployment, submit your sitemap to Google Search Console. Navigate to Sitemaps in the left sidebar, enter your sitemap URL (usually /sitemap.xml), and click Submit. Google will begin crawling your pages. Indexing typically takes 1-7 days for new pages, longer if your domain is new or has low authority.

    Monitor the Coverage report in Search Console to track how many pages are indexed, how many are excluded, and why. Common exclusion reasons: duplicate content (fix your meta descriptions), crawled but not indexed (add more internal links), soft 404 (your page returns 200 but looks empty to Google). If more than 10% of your pages are excluded after two weeks, you have a quality issue. Review your content and add more unique, useful information per page.

    Set up a Google Analytics event to track visits to your pSEO pages. Tag all pSEO URLs with a UTM parameter or filter by URL pattern in your analytics dashboard. Track bounce rate, time on page, and conversion rate (trial signups, demo requests, email captures). If your pSEO pages have a 90% bounce rate and 10-second average session, users aren't finding them useful. Improve your content or rethink your keyword targeting.

Conclusion

You've wired programmatic SEO into your Astro site using build-time generation, dynamic routes, and on-domain deployment. Your pSEO pages are static HTML files served from your CDN, with no runtime cost and no subdomain risk. You've validated your output for duplicate content, structured data errors, and Helpful Content red flags. Now you monitor indexing in Google Search Console and iterate based on what ranks.

Your next steps: expand your data source to cover more keywords, add related links between page types, and track which pages drive trial signups. If you used AI-assisted generation, review your output quality every 50 pages and adjust your prompts as needed. If you used template-based content, consider hiring a writer to scale beyond your initial batch. Programmatic SEO is a compounding investment: the first 50 pages take the most work, but pages 51-500 reuse the same pipeline.

Troubleshooting

Pages build successfully but return 404 in production

Check your hosting provider's routing rules. Some hosts require a _redirects file or vercel.json to handle dynamic routes. Astro generates a trailing slash by default (/compare/tool-a-vs-tool-b/); if your host strips trailing slashes, you'll get 404s. Add trailingSlash: 'always' to your astro.config.mjs.

Build fails with 'getStaticPaths is not defined' error

You're exporting getStaticPaths from a static route or not exporting it at all. Dynamic routes ([slug].astro) require a getStaticPaths export. Static routes (about.astro) cannot have one. Check your file name and export syntax.

All pages have the same title and meta description

You're not passing unique data to your template. In getStaticPaths, make sure each params object includes the data needed to generate unique titles. In your template, use Astro.props to access that data and interpolate it into your <title> and <meta name="description"> tags.

Pages are indexed but not ranking

Check your keyword targeting in Google Keyword Planner or Ahrefs. If you're targeting zero-volume keywords, you won't get traffic even if you rank #1. Add more internal links from high-authority pages on your site. Improve your content uniqueness: if your page is identical to ten competitor pages, Google has no reason to rank yours higher.

Build time is too long (10+ minutes for 500 pages)

You're likely calling an external API inside getStaticPaths without caching. Move API calls to a separate pre-build script, cache the results as JSON, and read from the cache during astro build. If you're generating images or running heavy transformations, parallelize the work or move it out of the build step.

Google Search Console shows 'Crawled but not indexed' for most pages

Your pages are too similar or too thin. Google crawled them but decided they don't add value. Add more unique content per page (500+ words), improve internal linking, and make sure each page targets a distinct keyword. Check for duplicate content using Copyscape or Siteliner.

Related Articles