js/website
1
0
Fork 0
mirror of https://github.com/prdlk/website.git synced 2026-08-02 17:31:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(agents): add AGENTS.md documentation files for site agents

Browse Source
This commit is contained in:
Prad Nukala
2026-06-30 13:05:16 -04:00
parent 2178cef232
commit 241442e772
6 changed files with 206 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/AGENTS.md
+50
View File
@@ -0,0 +1,50 @@
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2026-06-30 | Updated: 2026-06-30 -->
# src
## Purpose
All application source: configuration, content collections, pages/routes, layouts, components, data helpers, styles, and build plugins.
## Key Files
| File | Description |
|------|-------------|
| `site.config.ts` | Site metadata (`siteConfig`), `socialLinks`, `streamOrigin` (Cloudflare Stream origin), `menuLinks`, and Expressive Code options. Primary place to edit site-wide settings. |
| `content.config.ts` | Content Collection definitions + Zod schemas for `writing`, `projects`, `experience`, `speaking`. Experience refs are validated via `reference("experience")`. |
| `types.ts` | Shared TS types (`SiteConfig`, `SiteMeta`, webmention types, `AdmonitionType`). |
| `env.d.ts` | Ambient type declarations. |
## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `assets/` | Build-time assets, currently OG fonts (see `assets/AGENTS.md`). |
| `components/` | Reusable `.astro` components (see `components/AGENTS.md`). |
| `content/` | Markdown content for the four collections (see `content/AGENTS.md`). |
| `data/` | Collection query helpers (see `data/AGENTS.md`). |
| `layouts/` | Page shells (see `layouts/AGENTS.md`). |
| `pages/` | File-based routes + endpoints. **No `AGENTS.md` here** — any `.md` under `src/pages` becomes a public route, so docs for this dir live in this file (see "Routing & OG images" below). |
| `plugins/` | Custom remark plugins (see `plugins/AGENTS.md`). |
| `styles/` | Global CSS + block/component styles (see `styles/AGENTS.md`). |
| `utils/` | Pure helper functions (see `utils/AGENTS.md`). |
## For AI Agents
### Working In This Directory
- Collection **keys match their content dir and route**: `writing`→`/writing`, `projects`→`/projects`, `experience`→`/experience`, `speaking`→`/speaking`.
- When changing a collection schema in `content.config.ts`, run `pnpm build` to regenerate `astro:content` types and catch frontmatter mismatches.
### Routing & OG images (`src/pages`)
- Any `.md`/`.mdx`/`.astro` under `src/pages` becomes a route — do **not** put `AGENTS.md` or other docs there (they'd ship as public pages). Document `pages/` here instead.
- Each section has `[...page].astro` (paginated list) + `[...slug].astro` (detail); plus `rss.xml.ts` feeds and a dynamic OG-image endpoint.
- `og-image/[...slug].png.ts` generates per-entry social images for **all** collections (namespaced `/og-image/<type>/<id>.png`) via Satori + Sharp, cached by `_cacheUtil.ts` (bump `CACHE_VERSION` when changing `_ogMarkup.ts`). Files prefixed `_` are private modules, not routes.
- The `/experience/[...slug]` page is the taxonomy hub (`getContentForExperience`), listing related projects/writing/talks.
### Common Patterns
- The `experiences` frontmatter array (on projects/writing/speaking) holds `reference("experience")` entries, resolved with `getEntries`.
## Dependencies
### Internal
- Nearly everything imports `@/site.config` and `@/content.config`-derived collection types.
<!-- MANUAL: -->