AGENTS.md

1# AGENTS.md
2 
3## Projectoverzicht
4 
5Dit is een educatieve curriculumrepository voor het onderwijzen van de basisprincipes van webontwikkeling aan beginners. Het curriculum is een uitgebreide cursus van 12 weken, ontwikkeld door Microsoft Cloud Advocates, met 24 praktische lessen over JavaScript, CSS en HTML.
6 
7### Belangrijkste Componenten
8 
9- **Educatieve Inhoud**: 24 gestructureerde lessen georganiseerd in projectgebaseerde modules
10- **Praktische Projecten**: Terrarium, Typwedstrijd, Browserextensie, Ruimtegame, Bankapp, Code-editor en AI Chatassistent
11- **Interactieve Quizzen**: 48 quizzen met elk 3 vragen (voor-/nabesprekingen)
12- **Meertalige Ondersteuning**: Geautomatiseerde vertalingen voor meer dan 50 talen via GitHub Actions
13- **Technologieën**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (voor AI-projecten)
14 
15### Architectuur
16 
17- Educatieve repository met op lessen gebaseerde structuur
18- Elke lesmap bevat README, codevoorbeelden en oplossingen
19- Losstaande projecten in aparte mappen (quiz-app, diverse lesprojecten)
20- Vertalingssysteem via GitHub Actions (co-op-translator)
21- Documentatie verzorgd via Docsify en beschikbaar als PDF
22 
23## Setup Commando's
24 
25Deze repository is hoofdzakelijk bedoeld voor het consumeren van educatieve inhoud. Voor het werken met specifieke projecten:
26 
27### Hoofdrepository 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 ontwikkelserver
40npm run build      # Bouw voor productie
41npm run lint       # Voer ESLint uit
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       # Voer ESLint uit
51npm run format     # Opmaak met Prettier
52```
53 
54### Browserextensie Projecten
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Volg browser-specifieke instructies voor het laden van extensies
60```
61 
62### Ruimtegame Projecten
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Open index.html in de browser of gebruik Live Server
68```
69 
70### Chat Project (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Stel de omgevingsvariabele GITHUB_TOKEN in
76python api.py
77```
78 
79## Ontwikkelworkflow
80 
81### Voor Inhoudbijdragers
82 
831. **Fork de repository** naar je GitHub-account
842. **Clone je fork** lokaal
853. **Maak een nieuwe branch** voor je wijzigingen
864. Breng wijzigingen aan in lesinhoud of codevoorbeelden
875. Test eventuele codewijzigingen in relevante projectmappen
886. Dien pull requests in volgens de bijdrage-richtlijnen
89 
90### Voor Leerlingen
91 
921. Fork of clone de repository
932. Navigeer sequentieel door lesmappen
943. Lees README-bestanden voor elke les
954. Maak pre-les quizzen via https://ff-quizzes.netlify.app/web/
965. Doorloop codevoorbeelden in lesmappen
976. Maak opdrachten en uitdagingen
987. Maak post-les quizzen
99 
100### Live Ontwikkeling
101 
102- **Documentatie**: Run `docsify serve` in root (poort 3000)
103- **Quiz App**: Run `npm run dev` in quiz-app map
104- **Projecten**: Gebruik VS Code Live Server extensie voor HTML-projecten
105- **API Projecten**: Run `npm start` in respectievelijke API mappen
106 
107## Testinstructies
108 
109### Quiz App Testen
110 
111```bash
112cd quiz-app
113npm run lint       # Controleer op codeerstijlfouten
114npm run build      # Verifieer dat de build slaagt
115```
116 
117### Bank API Testen
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Controleer op problemen met de code-stijl
122node server.js     # Controleer of de server zonder fouten start
123```
124 
125### Algemene Testaanpak
126 
127- Dit is een educatieve repository zonder uitgebreide geautomatiseerde tests
128- Handmatig testen richt zich op:
129  - Codevoorbeelden draaien zonder fouten
130  - Links in documentatie werken correct
131  - Projectbuilds worden succesvol afgerond
132  - Voorbeelden volgen best practices
133 
134### Pre-submissie Controles
135 
136- Run `npm run lint` in mappen met package.json
137- Controleer of markdown links geldig zijn
138- Test codevoorbeelden in browser of Node.js
139- Controleer dat vertalingen juiste structuur behouden
140 
141## Code Stijlgids
142 
143### JavaScript
144 
145- Gebruik moderne ES6+ syntax
146- Volg standaard ESLint configuraties die in projecten zijn opgenomen
147- Gebruik betekenisvolle variabele- en functienamen om educatief inzicht te bieden
148- Voeg commentaar toe ter uitleg van concepten voor leerlingen
149- Formatteer met Prettier waar geconfigureerd
150 
151### HTML/CSS
152 
153- Semantische HTML5 elementen
154- Responsive design principes
155- Duidelijke class naamgevingsconventies
156- Commentaar met uitleg over CSS-technieken voor leerlingen
157 
158### Python
159 
160- PEP 8 stijlrichtlijnen
161- Duidelijke, educatieve codevoorbeelden
162- Type hints waar nuttig voor het leren
163 
164### Markdown Documentatie
165 
166- Duidelijke kopjeshiërarchie
167- Codeblokken met taal specificatie
168- Links naar aanvullende bronnen
169- Screenshots en afbeeldingen in `images/` mappen
170- Alt-tekst voor afbeeldingen voor toegankelijkheid
171 
172### Bestandsorganisatie
173 
174- Lessen genummerd in volgorde (1-getting-started-lessons, 2-js-basics, etc.)
175- Elk project heeft `solution/` en vaak `start/` of `your-work/` mappen
176- Afbeeldingen opgeslagen in les-specifieke `images/` mappen
177- Vertalingen in `translations/{language-code}/` structuur
178 
179## Build en Deployment
180 
181### Quiz App Deployment (Azure Static Web Apps)
182 
183De quiz-app is geconfigureerd voor Azure Static Web Apps deployment:
184 
185```bash
186cd quiz-app
187npm run build      # Maakt de dist/ map aan
188# Zet uit via GitHub Actions workflow bij push naar main
189```
190 
191Azure Static Web Apps configuratie:
192- **App-locatie**: `/quiz-app`
193- **Output-locatie**: `dist`
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Documentatie PDF Generatie
197 
198```bash
199npm install                    # Installeer docsify-to-pdf
200npm run convert               # Genereer PDF van docs
201```
202 
203### Docsify Documentatie
204 
205```bash
206npm install -g docsify-cli    # Installeer Docsify globaal
207docsify serve                 # Serveer op localhost:3000
208```
209 
210### Project-specifieke Builds
211 
212Elke projectmap kan een eigen buildproces hebben:
213- Vue-projecten: `npm run build` maakt productiebundels
214- Statische projecten: Geen build-stap, bestanden direct serveren
215 
216## Pull Request Richtlijnen
217 
218### Titel Formaat
219 
220Gebruik duidelijke, beschrijvende titels die het wijzigingsgebied aangeven:
221- `[Quiz-app] Nieuwe quiz toegevoegd voor les X`
222- `[Lesson-3] Typfout opgelost in terrarium-project`
223- `[Translation] Spaanse vertaling toegevoegd voor les 5`
224- `[Docs] Setup instructies bijgewerkt`
225 
226### Vereiste Controles
227 
228Voor het indienen van een PR:
229 
2301. **Codekwaliteit**:
231   - Run `npm run lint` in de betrokken projectmappen
232   - Los alle lintfouten en waarschuwingen op
233 
2342. **Buildverificatie**:
235   - Run `npm run build` indien van toepassing
236   - Zorg dat er geen buildfouten zijn
237 
2383. **Link Validatie**:
239   - Test alle markdown links
240   - Controleer of afbeeldingsreferenties werken
241 
2424. **Inhoud Review**:
243   - Controleer spelling en grammatica
244   - Zorg dat codevoorbeelden correct en educatief zijn
245   - Controleer dat vertalingen oorspronkelijke betekenis behouden
246 
247### Bijdragereisen
248 
249- Akkoord gaan met Microsoft CLA (geautomatiseerde check bij eerste PR)
250- Volg de [Microsoft Open Source Gedragscode](https://opensource.microsoft.com/codeofconduct/)
251- Zie [CONTRIBUTING.md](./CONTRIBUTING.md) voor gedetailleerde richtlijnen
252- Verwijs naar issue nummers in PR-omschrijving indien van toepassing
253 
254### Reviewproces
255 
256- PR's worden beoordeeld door maintainers en community
257- Educatieve helderheid krijgt prioriteit
258- Codevoorbeelden volgen huidige best practices
259- Vertalingen worden beoordeeld op nauwkeurigheid en culturele relevantie
260 
261## Vertalingssysteem
262 
263### Geautomatiseerde Vertaling
264 
265- Maakt gebruik van GitHub Actions met co-op-translator workflow
266- Vertalingen in meer dan 50 talen automatisch
267- Bronbestanden in hoofdmappen
268- Vertaalde bestanden in `translations/{language-code}/` mappen
269 
270### Manuele Vertaalverbeteringen Toevoegen
271 
2721. Zoek bestand in `translations/{language-code}/`
2732. Breng verbeteringen aan en behoud de structuur
2743. Zorg dat codevoorbeelden functioneel blijven
2754. Test alle gelokaliseerde quizinhoud
276 
277### Vertaalmetadata
278 
279Vertaalde bestanden bevatten 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 en Probleemoplossing
293 
294### Veelvoorkomende Problemen
295 
296**Quiz-app start niet**:
297- Controleer Node.js versie (v14+ aanbevolen)
298- Verwijder `node_modules` en `package-lock.json`, run `npm install` opnieuw
299- Controleer op poortconflicten (standaard: Vite gebruikt poort 5173)
300 
301**API-server start niet**:
302- Controleer Node.js versie (node >=10 vereist)
303- Controleer of poort al in gebruik is
304- Zorg dat alle dependencies geïnstalleerd zijn met `npm install`
305 
306**Browserextensie laadt niet**:
307- Controleer of manifest.json correct is geformatteerd
308- Check browserconsole op fouten
309- Volg browser-specifieke installatie-instructies voor extensies
310 
311**Problemen met Python chat project**:
312- Zorg dat OpenAI package is geïnstalleerd: `pip install openai`
313- Controleer of GITHUB_TOKEN omgevingsvariabele is ingesteld
314- Controleer toegangsrechten voor GitHub Models
315 
316**Docsify serveert geen documentatie**:
317- Installeer docsify-cli globaal: `npm install -g docsify-cli`
318- Run vanuit root van repository
319- Controleer dat `docs/_sidebar.md` bestaat
320 
321### Tips Ontwikkelomgeving
322 
323- Gebruik VS Code met Live Server extensie voor HTML-projecten
324- Installeer ESLint en Prettier extensies voor consistente formattering
325- Gebruik browser DevTools voor debugging van JavaScript
326- Voor Vue-projecten: installeer Vue DevTools browser extensie
327 
328### Prestatie-overwegingen
329 
330- Groot aantal vertaalde bestanden (50+ talen) betekent grote klonen
331- Gebruik shallow clone als je alleen aan inhoud werkt: `git clone --depth 1`
332- Sluit vertalingen uit bij zoekopdrachten tijdens Engels werken
333- Buildprocessen kunnen traag zijn bij eerste run (npm install, Vite build)
334 
335## Beveiligingsoverwegingen
336 
337### Omgevingsvariabelen
338 
339- API-sleutels nooit aan repository toevoegen
340- Gebruik `.env` bestanden (staan al in `.gitignore`)
341- Documenteer benodigde omgevingsvariabelen in project-READMEs
342 
343### Python Projecten
344 
345- Gebruik virtuele omgevingen: `python -m venv venv`
346- Houd dependencies up-to-date
347- GitHub tokens met minimale benodigde rechten
348 
349### GitHub Models Toegang
350 
351- Persoonlijke Toegangstokens (PAT) vereist voor GitHub Models
352- Tokens opslaan als omgevingsvariabelen
353- Nooit tokens of inloggegevens committen
354 
355## Aanvullende Notities
356 
357### Doelgroep
358 
359- Volledig beginners in webontwikkeling
360- Studenten en zelflerenden
361- Docenten die het curriculum in klassen gebruiken
362- Inhoud ontworpen voor toegankelijkheid en geleidelijke vaardigheidsopbouw
363 
364### Educatieve Filosofie
365 
366- Projectgebaseerde leerbenadering
367- Regelmatige kennischecks (quizzen)
368- Praktische code-oefeningen
369- Voorbeelden van toepassingen uit de echte wereld
370- Focus op basisprincipes voor frameworks
371 
372### Repository Onderhoud
373 
374- Actieve gemeenschap van leerlingen en bijdragers
375- Regelmatige updates van dependencies en inhoud
376- Issues en discussies worden door maintainers gemonitord
377- Vertaalupdates geautomatiseerd via GitHub Actions
378 
379### Gerelateerde Bronnen
380 
381- [Microsoft Learn modules](https://docs.microsoft.com/learn/)
382- [Student Hub bronnen](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) aanbevolen voor leerlingen
384- Extra cursussen: Generative AI, Data Science, ML, IoT curricula beschikbaar
385 
386### Werken met Specifieke Projecten
387 
388Voor gedetailleerde instructies over individuele projecten, zie de README-bestanden in:
389- `quiz-app/README.md` - Vue 3 quizapplicatie
390- `7-bank-project/README.md` - Banking app met authenticatie
391- `5-browser-extension/README.md` - Browserextensie ontwikkeling
392- `6-space-game/README.md` - Canvas-gebaseerde gameontwikkeling
393- `9-chat-project/README.md` - AI chatassistent project
394 
395### Monorepo Structuur
396 
397Hoewel het geen traditionele monorepo is, bevat deze repository meerdere onafhankelijke projecten:
398- Elke les is zelfstandig
399- Projecten delen geen dependencies
400- Werk aan individuele projecten zonder anderen te beïnvloeden
401- Clone de gehele repo voor de volledige curriculumervaring
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Disclaimer**:  
407Dit document is vertaald met behulp van de AI-vertalingsservice [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, dient u er rekening mee te houden dat automatische vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het oorspronkelijke document in de oorspronkelijke taal moet als de gezaghebbende bron worden beschouwd. Voor kritieke informatie wordt een professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->