directory site

the directory site is a static Astro site that reads JSON from the indexer repo and renders public directory pages.

---

stack

• Astro 4 -- static site generator, TypeScript
• Tailwind CSS -- utility CSS
• Pagefind -- client-side full-text search, generated at build time
• GitHub Pages -- hosting

---

data flow

at build time:

1. Astro fetches data/people.json, data/orgs.json, data/projects.json from the raw GitHub URL of declared-md/index
2. if the fetch fails (index not yet public, network error), the build continues with empty arrays -- no pages are generated for the empty kind, but the directory pages themselves still render
3. getStaticPaths generates one HTML page per profile handle
4. Pagefind indexes the built HTML and generates a search index in dist/pagefind/

---

routes

route	content
/	landing page
/people	directory of all whoami.md profiles
/people/:handle	individual whoami.md profile
/orgs	directory of all whois.md profiles
/orgs/:handle	individual whois.md profile
/projects	directory of all whatis.md profiles
/projects/:handle	individual whatis.md profile

---

filtering

directory pages support URL query params for filtering:

• /people?tag=typescript -- filter by tag
• /people?location=brazil -- filter by location
• /projects?status=stable -- filter by status

filtering is done client-side with a small inline JavaScript snippet. all profiles are pre-rendered in the HTML; the script hides non-matching cards on page load.

---

rebuilding

the site rebuilds automatically on push to main. to rebuild when the index updates, the index repo can send a repository_dispatch event to trigger the site workflow. this trigger is commented out by default in the deploy workflow.

---