Skip to content

Commit 75a346c

Browse files
josecelanojosecelano
committed
docs: add comprehensive AGENTS.md file
Add detailed AGENTS.md file for AI coding agents with: - Complete project overview with tech stack details - Detailed component organization (atoms/molecules/organisms/singletons) - Build process documentation - Blog post management workflow - Deployment information - Common tasks and conventions This file provides AI coding agents with comprehensive context about the project structure, dependencies, and development workflow.
1 parent 261054f commit 75a346c

File tree

1 file changed

+322
-0
lines changed

1 file changed

+322
-0
lines changed

‎AGENTS.md‎

Lines changed: 322 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,322 @@
1+
# AGENTS.md
2+
3+
This file provides context and instructions for AI coding agents working on the Torrust website.
4+
5+
## Project Overview
6+
7+
The Torrust website is a static site built with SvelteKit, featuring:
8+
9+
- Information about the Torrust project and its BitTorrent tracker and index implementations
10+
- Blog posts about BitTorrent technology, development guides, and project updates
11+
- Community resources and contributor profiles
12+
- Responsive, privacy-friendly design with no external tracking or analytics
13+
- Image optimization with automatic WebP/AVIF conversion
14+
- Search functionality using FlexSearch
15+
16+
**Tech Stack:**
17+
18+
- SvelteKit with @sveltejs/adapter-static
19+
- TypeScript (strict mode enabled)
20+
- Tailwind CSS with plugins (@tailwindcss/typography, @tailwindcss/forms, @tailwindcss/container-queries)
21+
- MDsveX for Markdown processing with Svelte components
22+
- Vite 6.x for bundling
23+
- Histoire for component development and isolation
24+
- Sass for advanced styling (variables, mixins, functions)
25+
- Rehype plugins for enhanced HTML processing (autolink-headings, external-links, slug)
26+
- rehype-pretty-code for syntax highlighting
27+
- vite-plugin-imagemin for image optimization
28+
- svelte-sitemap for sitemap generation
29+
30+
**Key Dependencies:**
31+
32+
- Svelte 5 (using runes syntax: `$state`, `$derived`, `$effect`)
33+
- highlight.js for code syntax highlighting
34+
- dateformat for date/time formatting
35+
- reading-time for post reading time estimation
36+
- FlexSearch for client-side search
37+
- @iconify/svelte for SVG icons
38+
- @melt-ui/svelte for accessible UI components
39+
40+
## Setup Commands
41+
42+
```bash
43+
# Install dependencies
44+
npm install
45+
46+
# Start development server
47+
npm run dev
48+
# Available at http://localhost:5173/
49+
50+
# Build for production
51+
npm run build
52+
53+
# Preview production build
54+
npm run preview
55+
56+
# Open component storybook (Histoire)
57+
npm run story:dev
58+
```
59+
60+
## Code Quality Commands
61+
62+
```bash
63+
# Run all checks (TypeScript + Svelte)
64+
npm run check
65+
66+
# Watch mode for checks
67+
npm run check:watch
68+
69+
# Format code
70+
npm run format
71+
72+
# Lint code (includes Prettier check + ESLint)
73+
npm run lint
74+
```
75+
76+
**Before committing:** Always run `npm run lint` to ensure code quality standards are met.
77+
78+
## Code Style Guidelines
79+
80+
- **TypeScript:** Strict mode enabled, always type function parameters and return types
81+
- **Formatting:** Prettier handles all formatting (single quotes, no semicolons for TypeScript/JavaScript)
82+
- **Svelte:** Use Svelte 5 runes syntax (`$state`, `$derived`, `$effect`, etc.)
83+
- **CSS:** Use Tailwind utility classes; custom CSS only when necessary
84+
- **File naming:** kebab-case for files and directories
85+
86+
## Project Structure
87+
88+
```text
89+
src/
90+
lib/
91+
components/
92+
atoms/ # Basic UI elements (Button, Card, Image, Tag, etc.)
93+
molecules/ # Composed components (BlogPostCard, Callout, CodeBlock)
94+
organisms/ # Complex sections (Header, Footer, Hero, Post)
95+
singletons/ # Unique, one-off components
96+
constants/ # Application constants
97+
data/ # Static data (features, metadata, posts)
98+
icons/ # SVG icon components
99+
socials/ # Social media icons
100+
scss/ # Sass stylesheets (variables, mixins, functions)
101+
stores/ # Svelte stores (contributorsStore)
102+
utils/ # Utility functions (cache, date, search, types)
103+
routes/
104+
(home)/ # Home page layout and content
105+
(pages)/ # Static pages (about, community, self-host, etc.)
106+
api/ # API endpoints (server-side)
107+
blog/ # Blog posts (MDsveX files) and listings
108+
[post-slug]/
109+
+page.svelte # Post display component
110+
+page.server.ts # Server-side data loading
111+
metadata.ts # Post metadata
112+
contributor/ # Contributor profile pages
113+
tags/ # Tag filtering pages
114+
app.css # Global CSS and Tailwind directives
115+
app.html # HTML template
116+
static/
117+
favicons/ # Favicon files
118+
images/
119+
contributors/ # Contributor photos
120+
posts/ # Blog post images
121+
blogMetadata.json # Generated blog metadata (created during build)
122+
scripts/
123+
generateMetadata.ts # Generates blog post metadata
124+
.github/
125+
workflows/
126+
deploy.yml # GitHub Pages deployment
127+
test.yml # CI testing workflow
128+
```
129+
130+
**Component Organization:**
131+
132+
- **Atoms:** Basic building blocks (Button, Card, Image, Tag)
133+
- **Molecules:** Combinations of atoms (BlogPostCard, Callout)
134+
- **Organisms:** Complex sections (Header, Footer, Hero)
135+
- **Singletons:** Unique components (SearchBar, ShareButton)
136+
137+
## Managing Blog Posts
138+
139+
**File Structure:**
140+
141+
- Blog posts are in `src/routes/blog/[post-slug]/` directories
142+
- Each post has:
143+
- `+page.svelte` - Main content (MDsveX)
144+
- `+page.server.ts` - Server-side data loading
145+
- `metadata.ts` - Post metadata export
146+
147+
**Front Matter (YAML):**
148+
Required fields:
149+
150+
```yaml
151+
---
152+
title: 'Post Title'
153+
date: '2024-01-15'
154+
excerpt: 'Brief description for listings and SEO'
155+
categories: ['Development', 'BitTorrent']
156+
cover_image: '/images/posts/post-slug/cover.webp'
157+
author: 'Author Name'
158+
---
159+
```
160+
161+
Optional fields:
162+
163+
- `updated`: "2024-01-20" - Last update date
164+
- `tags`: ["rust", "tracker"] - Additional tags
165+
166+
**Workflow:**
167+
168+
1. Use Front Matter VS Code extension for easier management
169+
2. Create post directory: `src/routes/blog/my-new-post/`
170+
3. Add front matter and content
171+
4. Place images in `static/images/posts/my-new-post/`
172+
5. Reference images: `/images/posts/my-new-post/image.png`
173+
6. Use `<Image />` component for automatic optimization
174+
7. Run `npm run dev` to preview
175+
8. Metadata is auto-generated during build
176+
177+
**Supported Content:**
178+
179+
- Standard Markdown syntax
180+
- Svelte components inline
181+
- Code blocks with syntax highlighting
182+
- Images with automatic optimization
183+
- Links with automatic external link handling
184+
185+
## Image Optimization
186+
187+
- Use the `<Image />` component instead of `<img />` for automatic optimization
188+
- Images are converted to WebP and AVIF formats during build
189+
- Source images can be PNG, JPG, etc. (optimization happens at build time)
190+
191+
## Testing Instructions
192+
193+
Currently, the project uses:
194+
195+
- Type checking via `npm run check`
196+
- Linting via `npm run lint`
197+
- Manual testing in development mode
198+
199+
**When making changes:**
200+
201+
1. Run `npm run dev` and test locally
202+
2. Run `npm run check` to verify types
203+
3. Run `npm run lint` to verify code style
204+
4. Build with `npm run build` to ensure production build works
205+
5. Test the production build with `npm run preview`
206+
207+
## Build Process
208+
209+
The build process:
210+
211+
1. Generates blog metadata (`tsx scripts/generateMetadata.ts`)
212+
- Creates `static/blogMetadata.json` with post metadata
213+
- Extracts front matter from blog posts
214+
- Calculates reading times
215+
2. Builds static site with Vite
216+
- SvelteKit adapter-static generates HTML pages
217+
- Processes MDsveX files (Markdown with Svelte)
218+
- Applies Tailwind CSS
219+
3. Optimizes images with vite-plugin-imagemin
220+
- Converts images to WebP and AVIF formats
221+
- Only when using `<Image />` component
222+
4. Generates sitemap for SEO (`svelte-sitemap`)
223+
- Domain: <https://torrust.com/>
224+
- Includes all static pages and blog posts
225+
226+
Output directory: `build/`
227+
228+
**Build artifacts:**
229+
230+
- Static HTML pages
231+
- Optimized images in WebP/AVIF
232+
- JavaScript bundles (app, immutable chunks)
233+
- `sitemap.xml` for search engines
234+
- `blogMetadata.json` for search functionality
235+
236+
## Deployment
237+
238+
**GitHub Pages (Automatic):**
239+
240+
- Deployment triggered on push to `develop` branch
241+
- Workflow: `.github/workflows/deploy.yml`
242+
- Build artifact is uploaded and deployed to GitHub Pages
243+
- URL: <https://torrust.com/> (via CNAME)
244+
245+
**Workflow Steps:**
246+
247+
1. Checkout code
248+
2. Install dependencies with npm
249+
3. Run build (`npm run build`)
250+
4. Create `.nojekyll` file in `build/` directory
251+
5. Upload artifacts to GitHub Pages
252+
6. Deploy to production environment
253+
254+
**Manual Deployment:**
255+
256+
```bash
257+
npm run build && npm run deploy
258+
```
259+
260+
**Deployment Requirements:**
261+
262+
- GitHub Pages must be enabled in repository settings
263+
- CNAME file must exist in root for custom domain
264+
- Workflow has `pages: write` and `id-token: write` permissions
265+
266+
## Blog Metadata Generation
267+
268+
The `scripts/generateMetadata.ts` script:
269+
270+
- Scans all blog posts in `src/routes/blog/`
271+
- Extracts front matter (title, date, excerpt, etc.)
272+
- Calculates reading time for each post
273+
- Generates `static/blogMetadata.json`
274+
- Runs automatically during `npm run build`
275+
276+
**Usage:**
277+
278+
```bash
279+
tsx scripts/generateMetadata.ts
280+
```
281+
282+
This metadata is used for:
283+
284+
- Blog post listings
285+
- Search functionality (FlexSearch)
286+
- RSS feed generation
287+
- SEO meta tags
288+
289+
## Common Tasks
290+
291+
### Adding a new blog post
292+
293+
1. Create a new `.md` file in `src/routes/blog/`
294+
2. Add required front matter (title, date, excerpt, etc.)
295+
3. Write content using Markdown and Svelte components as needed
296+
4. Add cover image to `static/images/blog/`
297+
5. Test locally with `npm run dev`
298+
299+
### Adding a new component
300+
301+
1. Create component in `src/lib/components/`
302+
2. Consider adding a story in `src/lib/components/*.story.svelte` for Histoire
303+
3. Export from `src/lib/index.ts` if it should be publicly available
304+
305+
### Updating styles
306+
307+
- Modify `src/app.css` for global styles
308+
- Update `tailwind.config.ts` for Tailwind configuration
309+
- Most styling should be done with Tailwind utilities
310+
311+
## Security Considerations
312+
313+
- No external tracking or analytics
314+
- No external resource loading (privacy-friendly)
315+
- Static site generation means no server-side vulnerabilities
316+
- Keep dependencies updated regularly
317+
318+
## Conventions
319+
320+
- **Commits:** Use conventional commits format (e.g., `feat:`, `fix:`, `docs:`, `chore:`)
321+
- **Branches:** Use descriptive names (e.g., `feature/add-blog-post`, `fix/navigation-bug`)
322+
- **PRs:** Provide clear description of changes and reference any related issues

0 commit comments

Comments
 (0)