--- title: "How to ship static-site SEO end-to-end" slug: "static-site-seo" category: "howto" tags: ["howto", "seo", "ssg", "quartz", "build-time", "json-ld", "sitemap"] status: "stable" last_updated: 2026-05-15 summary: "Ship every SEO artifact a static site needs at build time: canonicals, sitemap, robots, JSON-LD, OG images, llms.txt, and verify with curl before deploy." related: ["[[seo/technical]]", "[[seo/structured-data]]", "[[seo/discoverability-files]]", "[[howto/add-jsonld-to-static-site]]", "[[howto/deploy-quartz-site]]", "[[howto/ship-llms-txt]]", "[[ops/github-pages]]", "[[tooling/quartz-config]]", "[[seo/glossary]]", "[[seo/audit-checklist]]"] --- ## Overview A static site has one advantage and one constraint for SEO. The advantage: every artifact (HTML, meta, JSON-LD, sitemap, robots, llms.txt) is computed at build time, deterministic, and reviewable in a diff. The constraint: nothing is dynamic, so the build must produce every discoverability file the same as a server-rendered site would. This guide ships the full SEO surface for a Quartz site to GitHub Pages or Cloudflare Pages. Adapt the same steps for Astro, Next.js `output: "export"`, or any other SSG. ## Prerequisites - A working static-site build (`npx quartz build` or equivalent) that emits to `public/`. - A custom domain you control, or a stable subdomain on the host. - Access to Google Search Console (GSC) for sitemap submission and post-deploy verification. - The umbrella rules from [[seo/technical]] read once before starting. ## Steps ### 1. Pin the canonical base URL in build config The build needs to know the production URL so canonicals, OG tags, sitemap entries, and JSON-LD all match. In Quartz, set `baseUrl` in `quartz.config.ts`: ```ts configuration: { baseUrl: "llmbestpractices.com", // ... } ``` Quartz uses `baseUrl` to emit a CNAME, build canonical `` tags, and write absolute URLs into the sitemap. Setting it once removes a whole class of URL-drift bugs covered in [[seo/technical]]. See [[tooling/quartz-config]] for the full options. ### 2. Emit one canonical per page, self-referential Quartz's default emitter writes `` per page when `baseUrl` is set. Verify on a built page: ```bash npx quartz build grep -l 'rel="canonical"' public/*.html | head -3 grep 'rel="canonical"' public/index.html ``` If any page is missing the tag, the emitter chain in `quartz.layout.ts` is wrong. Add the canonical component to the `head` array. ### 3. Generate sitemap.xml at build, not by hand Quartz emits `public/sitemap.xml` from every page's frontmatter `last_updated`. Verify after build: ```bash xmllint --noout public/sitemap.xml && echo "valid" grep -c "" public/sitemap.xml # should equal page count ``` Do not hand-edit. The sitemap regenerates on every build; manual edits get overwritten and create drift. ### 4. Place robots.txt at the site root Quartz reads `static/robots.txt` and copies it to `public/robots.txt` verbatim. Minimum content: ``` User-agent: * Allow: / Sitemap: https://llmbestpractices.com/sitemap.xml ``` Add `Disallow:` lines only for directories that genuinely should not be crawled (admin panels, drafts). Over-blocking is the most common static-site SEO bug. ### 5. Inject JSON-LD into every page JSON-LD ships in `` as a `