feat: rebuild the site's crawlable and citable surface

The site was a single URL whose every link left the domain, so there was
nothing on initphp.org to index beyond the homepage and nothing for an
answer engine to cite: not one Composer package name outside the four in
the terminal box, no PHP version requirements, no PSR claims, no dates.

Content
- Expand src/data/libraries.ts into the single source of truth for every
  package: slug, Composer name, wiki, Packagist URL, tagline, summary,
  minimum PHP, release version and date, PSR interfaces, required
  extensions and dependencies, all verified against Packagist and GitHub.
- Derive category membership and the featured set from it; remove
  src/data/featured.ts and the hand-maintained repo URLs in categories.ts,
  which could disagree with the catalogue.
- Add 27 pages under /libraries/ plus a /libraries/ hub: install command,
  package facts, source/docs/Packagist links and same-category related
  libraries. Point the homepage tiles and category lists at them, so the
  site finally has an internal link graph.
- Add an eight-entry FAQ, rendered visibly and mirrored in FAQPage JSON-LD
  from the same array.

Discoverability
- Add @astrojs/sitemap (29 URLs, lastmod from real release dates),
  public/robots.txt with the sitemap and explicit content signals, a 404
  page, llms.txt and llms-full.txt.
- Replace the lone Organization node with an @graph: Organization, WebSite,
  per-page CollectionPage/WebPage, ItemList, FAQPage, BreadcrumbList and
  SoftwareSourceCode/SoftwareApplication per package.
- Per-page titles, canonicals and og:url; description trimmed to 155 chars;
  robots opened up with max-image-preview:large and uncapped snippets.
- Lead the h1 with the brand; promote library and featured names from divs
  and spans to headings.

Assets
- Generate the favicon set, PWA icons and a 1200x630 og-image from the
  master logo (scripts/generate-icons.mjs). The 348 KB, 700x700 master was
  serving as both the favicon and the 32x32 navbar logo, and as a square
  og:image behind a summary_large_image card.
- Drop 1.4 MB of unreferenced logos; preload the Inter latin subset.
- Fix the footer's relative license link, which 404'd on any nested page.

Tests
- Retire tests/parity.test.mjs and its frozen baseline: it asserted the
  page had not changed, which is now the opposite of the intent.
- Add tests/seo.test.mjs covering headings, meta lengths, canonicals,
  social images, robots values, JSON-LD @id resolution, per-package facts,
  internal link integrity, image attributes, sitemap, robots.txt and the
  llms files.

Author: muhammetsafak

README.md

@@ -9,14 +9,56 @@ npm install
 npm run dev
 ```
 
+## Content model
+
+`src/data/libraries.ts` is the single source of truth for every package:
+name, slug, Composer name, repository, wiki, Packagist URL, description,
+minimum PHP version, latest version and release date, PSR interfaces,
+required extensions, dependencies and star count.
+
+Everything else is derived from it — the homepage cards, the category
+lists, the 27 pages under `/libraries/`, the JSON-LD, `llms.txt`,
+`llms-full.txt` and the sitemap. Nothing about a package may be restated in
+another file, so a package cannot disagree with itself between two sections
+of the site.
+
+- `src/data/categories.ts` holds category metadata only; membership comes
+  from each library's `category` field.
+- `src/data/faq.ts` backs both the visible FAQ and its `FAQPage` JSON-LD.
+- `src/data/site.ts` holds the origin, titles and social identities that end
+  up in canonicals and structured data.
+
+Archived Packagist packages (`initphp/cli-table`, `curl`, `event-emitter`,
+`http-client`, `http-factory`, `polyfill-php80`, `redis`,
+`redis-session-handler`, `var-dumper`) are deliberately absent from the
+catalogue: they are marked abandoned upstream and must not be advertised as
+installable.
+
+Star counts are the one number that changes without a commit:
+
+```sh
+npm run refresh:stars   # rewrites `stars:` in libraries.ts from the GitHub API
+```
+
+## Assets
+
+`public/` favicons, the PWA icons and the 1200x630 `og-image.png` are all
+generated from the single 700x700 master logo:
+
+```sh
+npm run icons           # scripts/generate-icons.mjs
+```
+
+Re-run it after replacing `public/logos/initphp-icon-700.png`. Do not hand-
+edit the generated files.
+
 ## Styling conventions
 
 - Two approaches exist today, split by component rather than by rule
   complexity: `Navbar.astro` and `Hero.astro` put Tailwind utilities on
-  their outer markup; the other seven components (`Stats`, `FeaturedCard`,
-  `CategoryCard`, `LibCard`, `Footer`, `Install`, `ScrollTop`) and the page
-  section shells in `index.astro` are scoped-CSS-only, even for
-  one-declaration rules. The codebase is not uniform.
+  their outer markup; the other components and the page section shells are
+  scoped-CSS-only, even for one-declaration rules. The codebase is not
+  uniform.
 - For new sections, follow the majority pattern: a scoped `<style>` rule per
   component, named for what it styles. Reserve utilities for one-off
   arbitrary values on an element that doesn't need a named rule.
@@ -33,21 +75,37 @@ npm run dev
 ## Test
 
 ```sh
-npm run build   # tests/parity.test.mjs reads dist/index.html
+npm run build   # tests/seo.test.mjs reads dist/
 npm test
 ```
 
 The suite has two parts:
 
-- `tests/parity.test.mjs` compares the built `dist/index.html` against
-  `tests/fixtures/baseline.html`, a frozen copy of the pre-Astro page, and fails on any
-  change to its title, meta tags, canonical/favicon, JSON-LD, headings, anchors, images
-  or rendered body text.
-- `tests/data.test.mjs` checks `src/data/*.ts` directly, independently of the build —
-  entry counts, required fields and their types, Iconify icon id format, that every
-  repo URL is on github.com, and uniqueness of library names and repos.
+- `tests/data.test.mjs` checks `src/data/*.ts` directly, independently of the
+  build — entry counts, required fields and their types, Iconify icon id
+  format, Composer/GitHub/Packagist URL agreement, that categories partition
+  the catalogue exactly, and uniqueness of names, slugs, packages and repos.
+- `tests/seo.test.mjs` asserts the crawlable surface of `dist/`: one h1 per
+  page and no skipped heading levels, title and meta-description lengths,
+  per-page canonicals and `og:url`, a 1200x630 social image, `robots` values
+  (including `noindex` on the 404), a resolvable JSON-LD `@graph` on every
+  page, the homepage `ItemList` and `FAQPage` matching the rendered content,
+  each library page stating its own install command and package facts, no
+  internal link pointing at something that was not built, `alt`/`width`/
+  `height` on every image, sitemap coverage and `lastmod` values, `robots.txt`,
+  and `llms.txt` / `llms-full.txt` covering every package.
+
+A third file, `tests/parity.test.mjs`, used to diff the build against a
+frozen copy of the pre-Astro page. It was retired once the page started
+diverging from that baseline on purpose; `tests/extract.mjs`, the HTML
+snapshot helper it was built around, is still used by the SEO suite.
 
 ## Deploy
 
 Pushing to `main` builds and publishes to GitHub Pages via
 `.github/workflows/deploy.yml`. The custom domain comes from `public/CNAME`.
+
+Repository **Settings → Pages → Source** must be set to **GitHub Actions**.
+With the older "Deploy from a branch" setting the workflow still reports
+success while Pages serves 404, because the branch root holds Astro sources
+rather than a built site.

astro.config.mjs

@@ -1,14 +1,48 @@
 import { defineConfig } from 'astro/config';
 import tailwindcss from '@tailwindcss/vite';
 import icon from 'astro-icon';
+import sitemap from '@astrojs/sitemap';
+// Astro loads this config through Vite, so the TypeScript catalogue can be
+// imported directly and the sitemap's lastmod can come from real release
+// dates instead of the build clock (which would mark all 29 URLs as changed
+// on every deploy, whether or not anything did).
+import { lastReleased, libraries } from './src/data/libraries.ts';
+
+const releasedBySlug = new Map(libraries.map((lib) => [lib.slug, lib.released]));
 
 export default defineConfig({
   site: 'https://initphp.org',
   output: 'static',
   // Astro 7 defaults compressHTML to 'jsx', which strips newline-adjacent
   // whitespace and would glue icons to their labels. Keep v6 behaviour.
   compressHTML: true,
-  integrations: [icon()],
+  integrations: [
+    icon(),
+    sitemap({
+      // 404.astro is rendered as a static page by the adapter but must never
+      // be advertised for crawling.
+      filter: (page) => !page.includes('/404'),
+      // The homepage is the entry point; /libraries/ is the hub for the 27
+      // package pages, which sit one level below both.
+      serialize(item) {
+        const path = new URL(item.url).pathname;
+        if (path === '/') {
+          return { ...item, changefreq: 'weekly', priority: 1.0, lastmod: new Date(lastReleased) };
+        }
+        if (path === '/libraries/') {
+          return { ...item, changefreq: 'weekly', priority: 0.9, lastmod: new Date(lastReleased) };
+        }
+        const slug = path.replace(/^\/libraries\/|\/$/g, '');
+        const released = releasedBySlug.get(slug);
+        return {
+          ...item,
+          changefreq: 'monthly',
+          priority: 0.8,
+          ...(released ? { lastmod: new Date(released) } : {}),
+        };
+      },
+    }),
+  ],
   vite: {
     plugins: [tailwindcss()],
   },

package-lock.json

@@ -6,7 +6,9 @@
     "dev": "astro dev",
     "build": "astro build",
     "preview": "astro preview",
-    "test": "node --test 'tests/**/*.test.mjs'"
+    "test": "node --test 'tests/**/*.test.mjs'",
+    "icons": "node scripts/generate-icons.mjs",
+    "refresh:stars": "node scripts/refresh-stars.mjs"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",
@@ -16,6 +18,7 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
+    "@astrojs/sitemap": "^3.7.3",
     "@fontsource-variable/inter": "^5.3.0",
     "@fontsource-variable/jetbrains-mono": "^5.3.0",
     "@tailwindcss/vite": "^4.3.3",