declared-md site

the public directory site for declared-md. built with Astro, deployed to GitHub Pages at declared-md.github.io.

---

running locally

cd site/
npm install
npm run dev       # starts dev server at localhost:4321

the dev server starts instantly. search (Pagefind) does not work in dev because the index is only built after npm run build. everything else works.

---

building

npm run build     # astro build + pagefind index

output goes to dist/. Pagefind indexes the HTML in dist/ and writes its index to dist/pagefind/.

to preview the production build locally:

npm run preview   # serves dist/ at localhost:4321

---

how data loading works

at build time, the site fetches three JSON files from the declared-md/index repo:

https://raw.githubusercontent.com/declared-md/index/main/data/people.json
https://raw.githubusercontent.com/declared-md/index/main/data/orgs.json
https://raw.githubusercontent.com/declared-md/index/main/data/projects.json

if the remote fetch fails (e.g. the index repo is not yet public, or you're offline), the build continues with empty data. empty states are shown on each directory page.

individual profile pages (/people/:handle, /orgs/:handle, /projects/:handle) are only generated for profiles that appear in the index. if the index is empty, these pages don't exist.

---

design system

the site uses CSS variables from DESIGN.md. all tokens are defined in src/styles/tokens.css. the Tailwind config extends the default theme with these variables.

dark mode is the default. the user's prefers-color-scheme preference is respected on first visit. preference is saved to localStorage after the first manual toggle.

logos are served from public/assets/. the Logo.astro and landing page components switch between dark and light variants based on the current theme class.

---

adding a new feature

1. new page: add a .astro file in src/pages/. follow the pattern of the existing directory pages.

2. new component: add a .astro file in src/components/. use inline CSS variables (style="color:var(--text)") for colors to respect the theme.

3. new data field: the data schema is defined in src/lib/types.ts. helper functions are in src/lib/data.ts. ProfileDetail.astro shows how to render all known fields.

4. new route type: update src/lib/handle.ts if you need new URL helpers.

---

deploy workflow

the site deploys automatically via GitHub Actions on push to main. the workflow is in .github/workflows/deploy.yml.

it uses the official GitHub Pages Actions:

• actions/upload-pages-artifact@v3
• actions/deploy-pages@v4

to trigger manually: go to the Actions tab and dispatch the deploy workflow.

to rebuild when the index updates, uncomment the repository_dispatch trigger in deploy.yml. the declared-md/index repo can send a dispatch event after each successful crawl.

---

reference

• design system: ../DESIGN.md
• spec: ../spec/
• validator: ../validator/
• indexer: ../index/