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