|
| 1 | + |
| 2 | +# Copilot Agent Instructions for rishikc.com |
| 3 | + |
| 4 | +## 🚀 Quick Start for Copilot |
| 5 | + |
| 6 | +**Always follow these rules:** |
| 7 | + |
| 8 | +- Only use Astro, TypeScript, and Tailwind CSS. Never add other frameworks or client-side JS libraries. |
| 9 | +- UI components must be `.astro` files in `src/components/`. |
| 10 | +- Use `content/assets/` for images referenced in markdown/content, `src/assets/` for images imported in components, and `public/` only for files that must be directly accessible by URL. |
| 11 | +- Never move, duplicate, or reference assets/scripts outside their intended folders. |
| 12 | +- All content/components must be accessible (WCAG 2.1 AA) and SEO-friendly. |
| 13 | +- Validate every change: `yarn dev`, check Problems panel, `yarn build`. |
| 14 | + |
| 15 | +--- |
| 16 | + |
| 17 | +## Purpose |
| 18 | + |
| 19 | +These instructions ensure all code and content contributions maintain the highest standards of quality, consistency, and maintainability for the project. |
| 20 | + |
| 21 | +## Project Overview |
| 22 | + |
| 23 | +This repository is a personal website built with Astro, TypeScript, and Tailwind CSS. It features articles, a gallery, open source contributions, and project showcases. The content is organized in markdown, JSON, and image assets, with custom components and layouts for rendering. |
| 24 | + |
| 25 | +## Key Technologies |
| 26 | + |
| 27 | +- **Astro**: Static site generator for building fast websites. |
| 28 | +- **TypeScript**: Used for configuration and some scripts. |
| 29 | +- **Tailwind CSS**: Utility-first CSS framework for styling. |
| 30 | +- **PostCSS**: Used for CSS processing. |
| 31 | +- **Node.js**: For running scripts and build processes. |
| 32 | + |
| 33 | +## Directory Structure |
| 34 | + |
| 35 | +- `astro.config.mjs`, `tsconfig.json`, `tailwind.config.mjs`, `postcss.config.cjs`: Project configuration files. |
| 36 | +- `package.json`: Lists dependencies and scripts. |
| 37 | +- `content/`: Contains all site content, including articles (markdown), assets (images, SVGs), gallery, projects, and quotes. |
| 38 | + - `about/`: Profile and services info. |
| 39 | + - `articles/`: Markdown articles, each in its own folder. |
| 40 | + - `assets/`: Images and SVGs for the site. **This folder is for content assets referenced in markdown or site content, not for direct public serving.** |
| 41 | + - *Example*: If an article references an image, place it here and use a relative path in the markdown. |
| 42 | + - `gallery/`: Gallery images and update script. |
| 43 | + - `projects/`: Project data and scripts. |
| 44 | + - `reads/`: Quotes and related scripts. |
| 45 | +- `design/`: Design assets (PNGs, not web-served; for design reference only). |
| 46 | +- `public/`: Publicly served static files (e.g., favicon). **Assets here are directly accessible via URL.** |
| 47 | +- `src/`: Source code for the site. |
| 48 | + - `content.config.ts`: Content collections configuration. |
| 49 | + - `assets/`: Source SVGs and images for use in components. **Not for direct public serving; use for imports in Astro components.** |
| 50 | + - *Example*: If a `.astro` component imports an SVG or image, place it here and import it directly in the component. |
| 51 | + |
| 52 | +## Updating Existing Content or Assets |
| 53 | + |
| 54 | +- To update an article, edit the markdown file in its folder under `content/articles/`. |
| 55 | +- To update an asset, replace or edit the file in its correct folder (`content/assets/`, `src/assets/`, or `public/`). Never move assets between these folders unless explicitly instructed. |
| 56 | +- For gallery, projects, or quotes, use the provided scripts to update metadata or data files. |
| 57 | + |
| 58 | +## Handling Breaking Changes or Major Refactors |
| 59 | + |
| 60 | +- Do not perform breaking changes or major refactors (e.g., changing folder structure, renaming core files, or altering build configuration) unless explicitly instructed or confirmed by the user. |
| 61 | +- For any significant change, summarize the impact and request user confirmation before proceeding. |
| 62 | + |
| 63 | + - `components/`: Astro components for UI (e.g., footer, LinkCard, search bar, SEO, article, gallery, etc.). |
| 64 | + - `layouts/`, `pages/`, `plugins/`, `styles/`, `utils/`: Standard Astro project structure for layouts, pages, plugins, styles, and utility functions. |
| 65 | + - `plugins/`: Custom Astro/remark plugins (e.g., `remark-reading-time.mjs`). |
| 66 | + |
| 67 | +## Content Management |
| 68 | + |
| 69 | +- Articles and profile info are in markdown and JSON under `content/`. |
| 70 | +- Gallery images are organized by category, with a shell script to update JSON metadata. |
| 71 | +- Projects and quotes are managed via JSON and JS scripts. |
| 72 | + |
| 73 | +## Build & Development |
| 74 | + |
| 75 | +- Use `yarn` to install dependencies. |
| 76 | +- Use `yarn dev` to start the development server. |
| 77 | +- Use `yarn build` to build the site for production. |
| 78 | +- Use `yarn preview` to preview the production build. |
| 79 | + |
| 80 | +## Coding Conventions |
| 81 | + |
| 82 | +- **Do not create React, Vue, Svelte, or other non-Astro components unless explicitly instructed to set up such frameworks.** |
| 83 | +- **Do not create UI components in `.js`, `.ts`, `.jsx`, `.tsx`, `.vue`, or `.svelte` files. All UI components must be `.astro` files in `src/components/`.** |
| 84 | +- **Do not add any client-side JavaScript frameworks or libraries (e.g., React, Vue, Svelte, Angular, Alpine.js, etc.) unless explicitly requested.** |
| 85 | +- Use TypeScript (`.ts`) for configuration and scripts where possible. Prefer `.ts` over `.js` for new scripts unless otherwise required for compatibility. |
| 86 | +- Use Tailwind CSS classes for styling components. |
| 87 | +- Organize content and assets semantically in the `content/` directory. |
| 88 | +- Use markdown for articles and documentation. |
| 89 | + |
| 90 | +## Special Scripts |
| 91 | + |
| 92 | +- `content/gallery/update_gallery_json.sh`: Updates gallery metadata. |
| 93 | +- `content/projects/generate_contributions.js`: Generates open source contributions data. |
| 94 | +- `content/reads/quotes.js`: Manages quotes data. |
| 95 | + |
| 96 | +## Best Practices for Copilot Agent |
| 97 | + |
| 98 | +- Strictly adhere to the Astro, TypeScript, and Tailwind CSS architecture. **Do not introduce any other frameworks or libraries unless explicitly requested.** |
| 99 | +- Follow the existing directory and file naming conventions for all edits and new content. |
| 100 | +- For new articles, always create a new folder under `content/articles/` and include a markdown file. Do not place articles elsewhere. |
| 101 | +- For new UI components, use `.astro` files in `src/components/` only. **Never create UI components in `.js`, `.ts`, `.jsx`, `.tsx`, `.vue`, or `.svelte` files.** |
| 102 | +- For new images or assets, place them in the appropriate `content/assets/` (for content referenced in markdown) or `src/assets/` (for component imports) subfolder. Use `public/` only for files that must be directly accessible via URL. **Never move, duplicate, or reference assets/scripts outside their intended folders.** |
| 103 | +- When updating configuration, ensure consistency with TypeScript and Astro conventions. Use `.ts` for new scripts unless compatibility requires `.js`. |
| 104 | +- Use the provided scripts for updating gallery, projects, and quotes data. **Do not replace, duplicate, or move these scripts; only extend them if necessary.** |
| 105 | +- All content and assets must be accessible, optimized for performance, and follow SEO best practices (e.g., alt text for images, semantic HTML, descriptive titles). |
| 106 | +- All components and content must be accessible (e.g., proper ARIA attributes, keyboard navigation, color contrast). |
| 107 | +- Always validate changes by: |
| 108 | + |
| 109 | + - Running `yarn dev` to check the development server for errors. |
| 110 | + - Checking the VS Code Problems panel for any reported issues, and fixing **all** problems before ending your task. Never consider a task complete if there are any errors or warnings in the Problems panel. |
| 111 | + - Ensuring the site builds successfully with `yarn build`. |
| 112 | + |
| 113 | +## Contribution & Pull Request Guidelines |
| 114 | + |
| 115 | +- Ensure your changes follow all instructions in this document. |
| 116 | +- For code changes, ensure code is clean, well-commented, and follows project conventions. |
| 117 | + |
| 118 | +## Accessibility & SEO |
| 119 | + |
| 120 | +- All new content and components must be accessible (WCAG 2.1 AA or better) and SEO-friendly. |
| 121 | +- Use semantic HTML, descriptive alt text, and proper heading structure. |
| 122 | +- Avoid using color as the only means of conveying information. |
| 123 | + |
| 124 | +## Validation Checklist |
| 125 | + |
| 126 | +Before submitting changes, always: |
| 127 | + |
| 128 | +- [ ] Run `yarn dev` and verify there are no errors or warnings. |
| 129 | +- [ ] Check the Problems panel in VS Code for issues. |
| 130 | +- [ ] Run `yarn build` to ensure the site builds successfully. |
| 131 | + |
| 132 | +--- |
| 133 | + |
| 134 | +## Additional Notes |
| 135 | + |
| 136 | +- The site is designed to be accessible and SEO-friendly. |
| 137 | +- Contributions should maintain the clean, organized structure of the repository. |
| 138 | +- Refer to `README.md` for more details on setup and contribution guidelines. |
0 commit comments