diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..39b278c8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,260 @@ +# AGENTS.md + +This file provides guidance to AI agents when working with code in this repository. + +## Communication Style + +- Use direct, concise language without unnecessary adjectives or adverbs +- Avoid flowery or marketing-style language ("tremendous", "dramatically", "revolutionary", etc.) +- Don't use vague superlatives ("comprehensive", "complete", "full", "entire", "thorough", "detailed") +- Don't include flattery or excessive praise ("excellent!", "perfect!", "great job!") +- State facts and findings directly without embellishment +- Skip introductory phrases like "I'm excited to", "I'd be happy to", "Let me dive into" +- Avoid concluding with summary statements unless specifically requested +- When presenting options or analysis, lead with the core information, not commentary about it + +## Project Overview + +This is the source code for ddev.com, a static website built with Astro and hosted on Cloudflare Pages. The site features a blog, documentation, sponsor information, and project resources for DDEV, a local development environment tool. + +## Development Commands + +Use DDEV for all development tasks: + +- `ddev start` - Start project with all dependencies +- `ddev npm run dev` - Start development server with hot reloading +- `ddev npm run build` - Build production site to `./dist/` +- `ddev npm run preview` - Preview built site locally +- `ddev npm run prettier` - Check code formatting +- `ddev npm run prettier:fix` - Auto-fix formatting issues +- `ddev npm run textlint` - Check content for writing issues +- `ddev npm run textlint:fix` - Auto-fix content issues + +### Site Access + +- Dev server: https://.ddev.site:4321 +- Built site: https://.ddev.site + +### Testing and Quality + +Before committing changes, always run: + +1. `ddev npm run prettier:fix` - Fix formatting +2. `ddev npm run textlint:fix` - Check content quality +3. `ddev start` - Ensure environment is working +4. Spellcheck and check links in any new content + +### Commits + +When making commits after major changes, use AI-assisted commit messages that include: + +- Clear description of changes made +- End with: `🤖 Developed with assistance from [Claude Code](https://claude.ai/code)` +- Include: `Co-Authored-By: Claude ` + +Only commit when explicitly requested by the user. + +## Working with Claude Code + +### Branch Naming + +Use descriptive branch names that include: + +- Date in YYYYMMDD format +- Your GitHub username +- Brief description of the work + +Format: `YYYYMMDD__` + +Examples: + +- `20250919_rfay_update_quickstart` +- `20250919_username_fix_blog_styling` +- `20250919_contributor_add_sponsor` + +### Whitespace and Formatting + +- **Never add trailing whitespace** - Blank lines must be completely empty (no spaces or tabs) +- Match existing indentation style exactly (spaces vs tabs, indentation depth) +- Preserve the file's existing line ending style +- Run linting tools to catch whitespace issues before committing + +## Architecture + +### Technology Stack + +- **[Astro](https://astro.build)** - Static site generator +- **[Tailwind CSS](https://tailwindcss.com)** - Utility-first CSS framework +- **[Tailwind Typography](https://tailwindcss.com/docs/typography-plugin)** - Typography plugin +- **[Heroicons](https://heroicons.com)** - Icon library +- **[Textlint](https://textlint.github.io)** - Content linting +- **[Giscus](https://giscus.app)** - GitHub-based commenting system + +### Project Structure + +``` +├── cache/ # GitHub API response cache for local development +├── public/ # Static assets copied to dist/ +│ ├── logos/ # Sponsor and technology logos (prefer SVG) +│ └── _redirects # Cloudflare Pages redirects +├── src/ +│ ├── components/ # Reusable Astro components +│ ├── content/ # Content collections (blog, authors) +│ ├── layouts/ # Page layout wrapper +│ ├── lib/ # Utilities (GitHub API, search, read time) +│ ├── pages/ # Direct route mapping (.astro files) +│ └── styles/ # Global PostCSS styles +├── .env.example # Environment variables template +├── astro.config.mjs # Astro configuration +├── package.json # Dependencies and scripts +└── tailwind.config.cjs # Tailwind configuration +``` + +### Content Management + +The site uses Astro's Content Collections with strict schema validation: + +- **Blog posts**: `src/content/blog/*.md` - Markdown with frontmatter, validated against categories and author schemas +- **Authors**: `src/content/authors/*.md` - Author profiles with name, firstName, and optional avatarUrl +- **Static pages**: `src/pages/*.astro` - Direct route mapping + +### Content Schema + +Blog posts require: + +- Valid author (must exist in authors collection) +- Categories from predefined list: Announcements, Community, DevOps, Performance, Guides, TechNotes, Training, Videos +- pubDate as Date object +- Optional featureImage with alt text + +### Content Linking + +- **Internal blog links**: Use markdown filename references (e.g., `[link text](filename.md)`) for links between blog posts. Astro automatically resolves these to proper URLs. +- **Other internal links**: Use root-relative paths (e.g., `[Contact](/contact)`) for links to other site pages +- **External links**: Use full URLs for links outside the site + +### GitHub Integration + +The site fetches dynamic data from GitHub API: + +- Requires `GITHUB_TOKEN` environment variable +- Uses local `cache/` directory to reduce API calls during development +- Token needs: `repo`, `read:org`, `read:user`, `read:project` scopes + +### Sponsor Management + +Featured sponsors are managed in `src/featured-sponsors.json` with specific schema for logos, URLs, and types. This data generates sponsor displays and SVG badges used in the main DDEV repository. + +## Development Setup + +### DDEV Setup (Recommended) + +1. Run `ddev start` to start and set up the project's dependencies +2. Open https://.ddev.site:4321 in your browser +3. To rebuild static site: `ddev npm run build` +4. Static site available at: https://.ddev.site + +### Setup Without DDEV + +1. Run `nvm use` to use appropriate Node.js version +2. Run `npm install` to install dependencies +3. Run `npm run dev` to start development server +4. Visit `http://localhost:4321/` + +### GitHub Token Setup + +For dynamic GitHub data (not required for blog posts): + +1. Run `cp .env.example .env` +2. Create [classic GitHub access token](https://github.com/settings/tokens) with scopes: `repo`, `read:org`, `read:user`, `read:project` +3. Add token to `.env` as `GITHUB_TOKEN=your_token_here` + +## Content Creation + +### Blog Posts + +Template for new blog posts in `src/content/blog/`: + +```markdown +--- +title: "Post Title" +pubDate: 2023-01-01 +summary: Brief description +author: Author Name +featureImage: + src: /img/blog/kebab-case.jpg + alt: Descriptive alt text + caption: Optional caption + credit: Optional credit +categories: + - Category Name +--- + +Post content here... +``` + +**Categories**: Announcements, Community, DevOps, Performance, Guides, TechNotes, Training, Videos + +**Images**: Production-ready, <2MB, reasonable dimensions, optimized + +### Authors + +Add new authors to `src/content/authors/` with schema: + +- name (must match blog post frontmatter) +- firstName +- avatarUrl (optional) + +### Pages + +Add `.astro` files to `src/pages/` where filename becomes URL slug. + +## Quality Control + +### Textlint + +- Configuration in `.textlintrc` +- Runs against `src/content/**` +- Enforces consistent language and terminology +- Run `ddev npm run textlint` before committing + +### Prettier + +- Configuration in `.prettierrc` +- Auto-formats code +- Run `ddev npm run prettier:fix` before committing +- VS Code: Auto-format on save enabled + +### Recommended VS Code Extensions + +- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) +- [EditorConfig](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) +- [Astro](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode) + +## Build & Deployment + +- GitHub Actions tests on every push to main +- Cloudflare Pages automatically builds and deploys from main branch +- Preview builds created for all PR branches +- Redirects managed via `public/_redirects` file + +### Secrets + +Production requires `GITHUB_TOKEN` environment variable in Cloudflare Pages settings. + +## Important Notes + +- Always preserve existing code style and component patterns +- Blog images should be production-ready: optimized, < 2MB, reasonable dimensions +- All content goes through textlint validation for consistency +- The site is configured for DDEV development with special CORS and host settings +- Use kebab-case for blog post filenames +- Prefer SVG logos in `public/logos/` +- Internal blog links use markdown filename references +- External links use full URLs + +## Resources + +- [Astro Documentation](https://docs.astro.build) +- [DDEV Documentation](https://ddev.readthedocs.io/) +- [Contributing to ddev.com Training](https://ddev.com/blog/ddev-website-for-contributors/) diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 674e5250..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,103 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -This is the source code for ddev.com, a static website built with Astro and hosted on Cloudflare Pages. The site features a blog, documentation, sponsor information, and project resources for DDEV, a local development environment tool. - -## Development Commands - -Use DDEV for all development tasks: - -- `ddev start` - Start project with all dependencies -- `ddev npm run dev` - Start development server with hot reloading -- `ddev npm run build` - Build production site to `./dist/` -- `ddev npm run preview` - Preview built site locally -- `ddev npm run prettier` - Check code formatting -- `ddev npm run prettier:fix` - Auto-fix formatting issues -- `ddev npm run textlint` - Check content for writing issues -- `ddev npm run textlint:fix` - Auto-fix content issues - -### Site Access - -- Dev server: https://.ddev.site:4321 -- Built site: https://.ddev.site - -### Testing and Quality - -Before committing changes, always run: - -1. `ddev npm run prettier:fix` - Fix formatting -2. `ddev npm run textlint:fix` - Check content quality -3. `ddev start` - Ensure environment is working -4. Spellcheck and check links in any new content - -### Commits - -When making commits after major changes, use AI-assisted commit messages that include: - -- Clear description of changes made -- End with: `🤖 Developed with assistance from [Claude Code](https://claude.ai/code)` -- Include: `Co-Authored-By: Claude ` - -Only commit when explicitly requested by the user. - -## Architecture - -### Content Management - -The site uses Astro's Content Collections with strict schema validation: - -- **Blog posts**: `src/content/blog/*.md` - Markdown with frontmatter, validated against categories and author schemas -- **Authors**: `src/content/authors/*.md` - Author profiles with name, firstName, and optional avatarUrl -- **Static pages**: `src/pages/*.astro` - Direct route mapping - -### Key Directories - -- `src/components/` - Reusable Astro components -- `src/layouts/` - Page layout wrapper -- `src/lib/` - Utilities for GitHub API, search indexing, reading time calculation -- `public/` - Static assets and redirects file -- `public/logos/` - Sponsor and technology logos (prefer SVG) - -### Content Schema - -Blog posts require: - -- Valid author (must exist in authors collection) -- Categories from predefined list: Announcements, Community, DevOps, Performance, Guides, TechNotes, Training, Videos -- pubDate as Date object -- Optional featureImage with alt text - -### Content Linking - -- **Internal blog links**: Use markdown filename references (e.g., `[link text](filename.md)`) for links between blog posts. Astro automatically resolves these to proper URLs. -- **Other internal links**: Use root-relative paths (e.g., `[Contact](/contact)`) for links to other site pages -- **External links**: Use full URLs for links outside the site - -### GitHub Integration - -The site fetches dynamic data from GitHub API: - -- Requires `GITHUB_TOKEN` environment variable -- Uses local `cache/` directory to reduce API calls during development -- Token needs: `repo`, `read:org`, `read:user`, `read:project` scopes - -### Sponsor Management - -Featured sponsors are managed in `src/featured-sponsors.json` with specific schema for logos, URLs, and types. This data generates sponsor displays and SVG badges used in the main DDEV repository. - -### Build & Deployment - -- GitHub Actions tests on every push to main -- Cloudflare Pages automatically builds and deploys from main branch -- Preview builds created for all PR branches -- Redirects managed via `public/_redirects` file - -## Important Notes - -- Always preserve existing code style and component patterns -- Blog images should be production-ready: optimized, < 2MB, reasonable dimensions -- All content goes through textlint validation for consistency -- The site is configured for DDEV development with special CORS and host settings diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 00000000..47dc3e3d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file