AGENTS.md

1# AGENTS.md
2 
3## Project Overview
4 
5This is an educational curriculum repository for teaching web development fundamentals to beginners. The curriculum is a comprehensive 12-week course developed by Microsoft Cloud Advocates, featuring 24 hands-on lessons covering JavaScript, CSS, and HTML.
6 
7### Key Components
8 
9- **Educational Content**: 24 structured lessons organized into project-based modules
10- **Practical Projects**: Terrarium, Typing Game, Browser Extension, Space Game, Banking App, Code Editor, and AI Chat Assistant
11- **Interactive Quizzes**: 48 quizzes with 3 questions each (pre/post-lesson assessments)
12- **Multi-language Support**: Automated translations for 50+ languages via GitHub Actions
13- **Technologies**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (for AI projects)
14 
15### Architecture
16 
17- Educational repository with lesson-based structure
18- Each lesson folder contains README, code examples, and solutions
19- Standalone projects in separate directories (quiz-app, various lesson projects)
20- Translation system using GitHub Actions (co-op-translator)
21- Documentation served via Docsify and available as PDF
22 
23## Setup Commands
24 
25This repository is primarily for educational content consumption. For working with specific projects:
26 
27### Main Repository Setup
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Quiz App Setup (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Start development server
40npm run build      # Build for production
41npm run lint       # Run ESLint
42```
43 
44### Bank Project API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Start API server
50npm run lint       # Run ESLint
51npm run format     # Format with Prettier
52```
53 
54### Browser Extension Projects
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Follow browser-specific extension loading instructions
60```
61 
62### Space Game Projects
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Open index.html in browser or use Live Server
68```
69 
70### Chat Project (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Set GITHUB_TOKEN environment variable
76python api.py
77```
78 
79## Development Workflow
80 
81### For Content Contributors
82 
831. **Fork the repository** to your GitHub account
842. **Clone your fork** locally
853. **Create a new branch** for your changes
864. Make changes to lesson content or code examples
875. Test any code changes in relevant project directories
886. Submit pull requests following contribution guidelines
89 
90### For Learners
91 
921. Fork or clone the repository
932. Navigate to lesson directories sequentially
943. Read README files for each lesson
954. Complete pre-lesson quizzes at https://ff-quizzes.netlify.app/web/
965. Work through code examples in lesson folders
976. Complete assignments and challenges
987. Take post-lesson quizzes
99 
100### Live Development
101 
102- **Documentation**: Run `docsify serve` in root (port 3000)
103- **Quiz App**: Run `npm run dev` in quiz-app directory
104- **Projects**: Use VS Code Live Server extension for HTML projects
105- **API Projects**: Run `npm start` in respective API directories
106 
107## Testing Instructions
108 
109### Quiz App Testing
110 
111```bash
112cd quiz-app
113npm run lint       # Check for code style issues
114npm run build      # Verify build succeeds
115```
116 
117### Bank API Testing
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Check for code style issues
122node server.js     # Verify server starts without errors
123```
124 
125### General Testing Approach
126 
127- This is an educational repository without comprehensive automated tests
128- Manual testing focuses on:
129  - Code examples run without errors
130  - Links in documentation work correctly
131  - Project builds complete successfully
132  - Examples follow best practices
133 
134### Pre-submission Checks
135 
136- Run `npm run lint` in directories with package.json
137- Verify markdown links are valid
138- Test code examples in browser or Node.js
139- Check that translations maintain proper structure
140 
141## Code Style Guidelines
142 
143### JavaScript
144 
145- Use modern ES6+ syntax
146- Follow standard ESLint configurations provided in projects
147- Use meaningful variable and function names for educational clarity
148- Add comments explaining concepts for learners
149- Format using Prettier where configured
150 
151### HTML/CSS
152 
153- Semantic HTML5 elements
154- Responsive design principles
155- Clear class naming conventions
156- Comments explaining CSS techniques for learners
157 
158### Python
159 
160- PEP 8 style guidelines
161- Clear, educational code examples
162- Type hints where helpful for learning
163 
164### Markdown Documentation
165 
166- Clear heading hierarchy
167- Code blocks with language specification
168- Links to additional resources
169- Screenshots and images in `images/` directories
170- Alt text for images for accessibility
171 
172### File Organization
173 
174- Lessons numbered sequentially (1-getting-started-lessons, 2-js-basics, etc.)
175- Each project has `solution/` and often `start/` or `your-work/` directories
176- Images stored in lesson-specific `images/` folders
177- Translations in `translations/{language-code}/` structure
178 
179## Build and Deployment
180 
181### Quiz App Deployment (Azure Static Web Apps)
182 
183The quiz-app is configured for Azure Static Web Apps deployment:
184 
185```bash
186cd quiz-app
187npm run build      # Creates dist/ folder
188# Deploys via GitHub Actions workflow on push to main
189```
190 
191Azure Static Web Apps configuration:
192- **App location**: `/quiz-app`
193- **Output location**: `dist`
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Documentation PDF Generation
197 
198```bash
199npm install                    # Install docsify-to-pdf
200npm run convert               # Generate PDF from docs
201```
202 
203### Docsify Documentation
204 
205```bash
206npm install -g docsify-cli    # Install Docsify globally
207docsify serve                 # Serve on localhost:3000
208```
209 
210### Project-specific Builds
211 
212Each project directory may have its own build process:
213- Vue projects: `npm run build` creates production bundles
214- Static projects: No build step, serve files directly
215 
216## Pull Request Guidelines
217 
218### Title Format
219 
220Use clear, descriptive titles indicating the area of change:
221- `[Quiz-app] Add new quiz for lesson X`
222- `[Lesson-3] Fix typo in terrarium project`
223- `[Translation] Add Spanish translation for lesson 5`
224- `[Docs] Update setup instructions`
225 
226### Required Checks
227 
228Before submitting a PR:
229 
2301. **Code Quality**:
231   - Run `npm run lint` in affected project directories
232   - Fix all linting errors and warnings
233 
2342. **Build Verification**:
235   - Run `npm run build` if applicable
236   - Ensure no build errors
237 
2383. **Link Validation**:
239   - Test all markdown links
240   - Verify image references work
241 
2424. **Content Review**:
243   - Proofread for spelling and grammar
244   - Ensure code examples are correct and educational
245   - Verify translations maintain original meaning
246 
247### Contribution Requirements
248 
249- Agree to Microsoft CLA (automated check on first PR)
250- Follow the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines
252- Reference issue numbers in PR description if applicable
253 
254### Review Process
255 
256- PRs reviewed by maintainers and community
257- Educational clarity is prioritized
258- Code examples should follow current best practices
259- Translations reviewed for accuracy and cultural appropriateness
260 
261## Translation System
262 
263### Automated Translation
264 
265- Uses GitHub Actions with co-op-translator workflow
266- Translates to 50+ languages automatically
267- Source files in main directories
268- Translated files in `translations/{language-code}/` directories
269 
270### Adding Manual Translation Improvements
271 
2721. Locate file in `translations/{language-code}/`
2732. Make improvements while preserving structure
2743. Ensure code examples remain functional
2754. Test any localized quiz content
276 
277### Translation Metadata
278 
279Translated files include metadata header:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Debugging and Troubleshooting
293 
294### Common Issues
295 
296**Quiz app fails to start**:
297- Check Node.js version (v14+ recommended)
298- Delete `node_modules` and `package-lock.json`, run `npm install` again
299- Check for port conflicts (default: Vite uses port 5173)
300 
301**API server won't start**:
302- Verify Node.js version meets minimum (node >=10)
303- Check if port is already in use
304- Ensure all dependencies installed with `npm install`
305 
306**Browser extension won't load**:
307- Verify manifest.json is properly formatted
308- Check browser console for errors
309- Follow browser-specific extension installation instructions
310 
311**Python chat project issues**:
312- Ensure OpenAI package installed: `pip install openai`
313- Verify GITHUB_TOKEN environment variable is set
314- Check GitHub Models access permissions
315 
316**Docsify not serving docs**:
317- Install docsify-cli globally: `npm install -g docsify-cli`
318- Run from repository root directory
319- Check that `docs/_sidebar.md` exists
320 
321### Development Environment Tips
322 
323- Use VS Code with Live Server extension for HTML projects
324- Install ESLint and Prettier extensions for consistent formatting
325- Use browser DevTools for debugging JavaScript
326- For Vue projects, install Vue DevTools browser extension
327 
328### Performance Considerations
329 
330- Large number of translated files (50+ languages) means full clones are large
331- Use shallow clone if only working on content: `git clone --depth 1`
332- Exclude translations from searches when working on English content
333- Build processes may be slow on first run (npm install, Vite build)
334 
335## Security Considerations
336 
337### Environment Variables
338 
339- API keys should never be committed to repository
340- Use `.env` files (already in `.gitignore`)
341- Document required environment variables in project READMEs
342 
343### Python Projects
344 
345- Use virtual environments: `python -m venv venv`
346- Keep dependencies updated
347- GitHub tokens should have minimal required permissions
348 
349### GitHub Models Access
350 
351- Personal Access Tokens (PAT) required for GitHub Models
352- Tokens should be stored as environment variables
353- Never commit tokens or credentials
354 
355## Additional Notes
356 
357### Target Audience
358 
359- Complete beginners to web development
360- Students and self-learners
361- Teachers using the curriculum in classrooms
362- Content is designed for accessibility and gradual skill building
363 
364### Educational Philosophy
365 
366- Project-based learning approach
367- Frequent knowledge checks (quizzes)
368- Hands-on coding exercises
369- Real-world application examples
370- Focus on fundamentals before frameworks
371 
372### Repository Maintenance
373 
374- Active community of learners and contributors
375- Regular updates to dependencies and content
376- Issues and discussions monitored by maintainers
377- Translation updates automated via GitHub Actions
378 
379### Related Resources
380 
381- [Microsoft Learn modules](https://docs.microsoft.com/learn/)
382- [Student Hub resources](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) recommended for learners
384- Additional courses: Generative AI, Data Science, ML, IoT curricula available
385 
386### Working with Specific Projects
387 
388For detailed instructions on individual projects, refer to the README files in:
389- `quiz-app/README.md` - Vue 3 quiz application
390- `7-bank-project/README.md` - Banking application with authentication
391- `5-browser-extension/README.md` - Browser extension development
392- `6-space-game/README.md` - Canvas-based game development
393- `9-chat-project/README.md` - AI chat assistant project
394 
395### Monorepo Structure
396 
397While not a traditional monorepo, this repository contains multiple independent projects:
398- Each lesson is self-contained
399- Projects don't share dependencies
400- Work on individual projects without affecting others
401- Clone entire repo for the full curriculum experience
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Disclaimer**:
407This document has been translated using AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->