mirror of
https://github.com/prdlk/prdlk.git
synced 2026-11-03 05:27:41 +00:00
docs(docs): add AGENTS documentation and README files
This commit is contained in:
Prad Nukala committed
1 parent
bff9f9f999
commit
8a191f65cc
8 files changed
+364
-42
No files matched your search
@@ -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`, `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: -->
|
||||
@@ -0,0 +1,26 @@
|
||||
<!-- Parent: ../AGENTS.md -->
|
||||
<!-- Generated: 2026-06-30 | Updated: 2026-06-30 -->
|
||||
|
||||
# layouts
|
||||
|
||||
## Purpose
|
||||
Page shells that wrap route content with `<head>`, header, footer, and theming.
|
||||
|
||||
## Key Files
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `Base.astro` | Root shell for all pages. Renders `BaseHead`, `ThemeProvider`, `Header`, `<main class="mb-20">`, `Footer`, and prefetch speculation rules. Takes a `meta: SiteMeta` prop; `description` defaults to `siteConfig.description`. Sets `max-w-3xl`, `font-mono`, padding. |
|
||||
| `BlogPost.astro` | Layout for individual writing entries. Renders `Masthead`, optional `TOC`, the prose body, webmentions, and a back-to-top button. Builds the OG image URL as `/og-image/${post.id}.png`. |
|
||||
|
||||
## For AI Agents
|
||||
|
||||
### Working In This Directory
|
||||
- Every page should render inside `Base.astro` (directly or via `BlogPost.astro`) and pass a `meta` object (`title` required; `description`, `ogImage`, `articleDate` optional).
|
||||
- `<main>` carries `mb-20` to separate content from the footer's top border — adjust here for global content/footer spacing.
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Internal
|
||||
- `@/components/BaseHead.astro`, `@/components/layout/*`, `@/components/blog/*`, `@/site.config`, `@/types`.
|
||||
|
||||
<!-- MANUAL: -->
|
||||
@@ -0,0 +1,27 @@
|
||||
<!-- Parent: ../AGENTS.md -->
|
||||
<!-- Generated: 2026-06-30 | Updated: 2026-06-30 -->
|
||||
|
||||
# plugins
|
||||
|
||||
## Purpose
|
||||
Custom remark plugins wired into Astro's markdown pipeline (`astro.config.ts` → `markdown.remarkPlugins`).
|
||||
|
||||
## Key Files
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `remark-admonitions.ts` | Turns `:::tip`/`:::note`/`:::important`/`:::caution`/`:::warning` directives into styled admonition blocks. Types defined in `@/types` (`AdmonitionType`); styled by `src/styles/components/admonition.css`. |
|
||||
| `remark-github-card.ts` | Renders a GitHub repo card from a directive. Styled by `src/styles/components/github-card.css`. |
|
||||
| `remark-reading-time.ts` | Computes reading time (via `reading-time`) and injects it into frontmatter; surfaced as `remarkPluginFrontmatter.readingTime` in `BlogPost.astro`. |
|
||||
|
||||
## For AI Agents
|
||||
|
||||
### Working In This Directory
|
||||
- These use the unified/mdast ecosystem (`unist-util-visit`, `mdast-util-directive`, `hastscript`). Directive syntax requires `remark-directive` (already configured).
|
||||
- Adding/removing a plugin requires editing `astro.config.ts`. Add matching CSS under `src/styles/components/` for any new block type.
|
||||
|
||||
## Dependencies
|
||||
|
||||
### External
|
||||
- `unified`, `unist-util-visit`, `mdast-util-directive`, `mdast-util-to-string`, `hastscript`, `reading-time`.
|
||||
|
||||
<!-- MANUAL: -->
|
||||
@@ -0,0 +1,31 @@
|
||||
<!-- Parent: ../AGENTS.md -->
|
||||
<!-- Generated: 2026-06-30 | Updated: 2026-06-30 -->
|
||||
|
||||
# styles
|
||||
|
||||
## Purpose
|
||||
Global CSS and component/block styles. Tailwind v4 is configured via CSS (`global.css`) rather than a large JS config.
|
||||
|
||||
## Key Files
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `global.css` | Tailwind import + theme: color tokens (`--color-global-bg`, `--color-global-text`, `--color-accent`, `--color-link`, `--color-muted`, `--color-special-*`), dark/light variants, base element styles, and the `cactus-link` / `title` utility classes. |
|
||||
|
||||
## Subdirectories
|
||||
| Directory | Purpose |
|
||||
|-----------|---------|
|
||||
| `blocks/` | `search.css` — Pagefind search UI styling. |
|
||||
| `components/` | `admonition.css` and `github-card.css` — styles for the matching remark plugins. |
|
||||
|
||||
## For AI Agents
|
||||
|
||||
### Working In This Directory
|
||||
- Use the defined color tokens (e.g. `text-muted`, `bg-global-bg`, `border-global-text/15`) for theme consistency rather than hardcoded colors — they adapt to dark/light mode.
|
||||
- New markdown block plugins (in `src/plugins/`) should get their CSS here under `components/`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
### External
|
||||
- `tailwindcss` v4, `@tailwindcss/typography` (prose), `cssnano`, `autoprefixer`.
|
||||
|
||||
<!-- MANUAL: -->
|
||||
@@ -0,0 +1,29 @@
|
||||
<!-- Parent: ../AGENTS.md -->
|
||||
<!-- Generated: 2026-06-30 | Updated: 2026-06-30 -->
|
||||
|
||||
# utils
|
||||
|
||||
## Purpose
|
||||
Pure, framework-agnostic helper functions used across components, pages, and data helpers.
|
||||
|
||||
## Key Files
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `date.ts` | `getFormattedDate` (locale-aware, per `siteConfig.date`) and `collectionDateSort` — sorts `writing`/`projects`/`speaking`/etc. by `publishDate` descending. |
|
||||
| `generateToc.ts` | Builds a nested table-of-contents tree from Astro markdown headings (used by `TOC.astro`). |
|
||||
| `remark.ts` | Shared remark/markdown helpers. |
|
||||
| `domElement.ts` | Small DOM helpers for client-side scripts. |
|
||||
| `webmentions.ts` | Fetches and caches webmentions from webmention.io for the webmention components. |
|
||||
|
||||
## For AI Agents
|
||||
|
||||
### Working In This Directory
|
||||
- `collectionDateSort` is typed for entries with a `publishDate`; experience entries (which use `startDate`/`endDate`) are sorted in `@/data/experience.ts` instead.
|
||||
- Keep these pure and side-effect-free where possible; `webmentions.ts` is the exception (network + cache).
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Internal
|
||||
- `@/site.config` (date locale), `@/types`.
|
||||
|
||||
<!-- MANUAL: -->
|
||||
Reference in new issue
Block a user