basil
/
personal-homepage
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
personal-homepage/AGENTS.md

2.7 KiB
Raw Blame History

Repository Guidelines

Project Structure & Module Organization

This repo is an Astro-based personal homepage with build-time data syncing. Main app code lives in src/: reusable UI in src/components, page routes in src/pages, layouts in src/layouts, shared helpers in src/utils, and site/data config in src/config.ts, src/content.config.ts, and src/data/. Editable content lives under src/content/ (logs/, projects/, shares/, seafile/, static-assets/). Generated sync output is written to src/data/generated/; treat it as build output. Static public files belong in public/, deployment assets in docker/, and operational notes in docs/.

Build, Test, and Development Commands

  • npm install — install dependencies (Node >=22.12.0).
  • npm run dev — start the Astro dev server.
  • npm run build — create a production build in dist/.
  • npm run preview — serve the built site locally.
  • npm run content:sync — pull remote content and refresh generated JSON.
  • npm run assets:sync — download static assets listed in src/content/static-assets/index.json.
  • npm run rebuild — full validation path: sync content, then build.

Coding Style & Naming Conventions

Use TypeScript ESM and Astro components with 2-space indentation. Keep components in PascalCase (ProjectCard.astro), utilities in camelCase (datetime.ts), and CSS classes in kebab-case with BEM-style modifiers when helpful (activity-item__meta). Prefer small, focused modules and reuse existing loaders/schemas before adding new abstractions. Keep content JSON filenames stable as index.json within each content folder.

Testing Guidelines

There is no dedicated test framework configured yet. For code or content changes, run npm run build; for sync-related work, run npm run rebuild. Treat a clean build as the minimum acceptance check, and verify changed pages in npm run preview when UI or content rendering changes.

Commit & Pull Request Guidelines

Recent history favors short, intent-first commit subjects in either English or Chinese. For new commits, keep the subject concise and explain why the change exists; include Lore trailers when applicable (Constraint:, Rejected:, Confidence:, Tested:). Pull requests should summarize the user-visible change, list affected paths, note any .env or content-schema updates, and include screenshots for visual changes. Always report which validation commands you ran.

Security & Configuration Tips

Copy .env.example to .env for local setup, and never commit secrets such as Gitea or Seafile tokens. When editing sync scripts in scripts/, document any new environment variables or external dependencies in README.md or docs/.