13 KiB

Raw Blame History

AGENTS.md

Projectoverzicht

Dit is een educatieve curriculumrepository voor het onderwijzen van de basisprincipes van webontwikkeling aan beginners. Het curriculum is een uitgebreide 12-weekse cursus ontwikkeld door Microsoft Cloud Advocates, met 24 praktische lessen over JavaScript, CSS en HTML.

Belangrijke onderdelen

Educatieve inhoud: 24 gestructureerde lessen georganiseerd in projectgebaseerde modules
Praktische projecten: Terrarium, Typingspel, Browserextensie, Ruimtespel, Bankapp, Code-editor en AI-chatassistent
Interactieve quizzen: 48 quizzen met elk 3 vragen (voorafgaande/naderhandse lesbeoordelingen)
Meertalige ondersteuning: Geautomatiseerde vertalingen in meer dan 50 talen via GitHub Actions
Technologieën: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (voor AI-projecten)

Architectuur

Educatieve repository met lesgebaseerde structuur
Elke lesmap bevat een README, codevoorbeelden en oplossingen
Zelfstandige projecten in aparte mappen (quiz-app, diverse lesprojecten)
Vertalingssysteem met GitHub Actions (co-op-translator)
Documentatie beschikbaar via Docsify en als PDF

Setup-commando's

Deze repository is primair bedoeld voor het consumeren van educatieve inhoud. Voor het werken met specifieke projecten:

Hoofdrepository instellen

git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners

Quiz-app instellen (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Start development server
npm run build      # Build for production
npm run lint       # Run ESLint

Bankproject-API (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Start API server
npm run lint       # Run ESLint
npm run format     # Format with Prettier

Browserextensieprojecten

cd 5-browser-extension/solution
npm install
# Follow browser-specific extension loading instructions

Ruimtespelprojecten

cd 6-space-game/solution
npm install
# Open index.html in browser or use Live Server

Chatproject (Python-backend)

cd 9-chat-project/solution/backend/python
pip install openai
# Set GITHUB_TOKEN environment variable
python api.py

Ontwikkelworkflow

Voor inhoudsbijdraaiers

Fork de repository naar je GitHub-account
Clone je fork lokaal
Maak een nieuwe branch voor je wijzigingen
Breng wijzigingen aan in lesinhoud of codevoorbeelden
Test eventuele codewijzigingen in relevante projectmappen
Dien pull requests in volgens de richtlijnen voor bijdragen

Voor leerlingen

Fork of clone de repository
Navigeer naar lesmappen in volgorde
Lees README-bestanden voor elke les
Maak voorafgaande quizzen op https://ff-quizzes.netlify.app/web/
Werk door codevoorbeelden in lesmappen
Voltooi opdrachten en uitdagingen
Maak naderhandse quizzen

Live ontwikkeling

Documentatie: Voer docsify serve uit in de root (poort 3000)
Quiz-app: Voer npm run dev uit in de quiz-app-map
Projecten: Gebruik de Live Server-extensie van VS Code voor HTML-projecten
API-projecten: Voer npm start uit in de respectieve API-mappen

Testinstructies

Quiz-app testen

cd quiz-app
npm run lint       # Check for code style issues
npm run build      # Verify build succeeds

Bank-API testen

cd 7-bank-project/api
npm run lint       # Check for code style issues
node server.js     # Verify server starts without errors

Algemene testaanpak

Dit is een educatieve repository zonder uitgebreide geautomatiseerde tests
Handmatige tests richten zich op:
- Codevoorbeelden draaien zonder fouten
- Links in documentatie werken correct
- Projecten bouwen succesvol
- Voorbeelden volgen best practices

Controle vóór indiening

Voer npm run lint uit in mappen met package.json
Controleer of markdown-links geldig zijn
Test codevoorbeelden in de browser of Node.js
Controleer of vertalingen de juiste structuur behouden

Richtlijnen voor codestijl

JavaScript

Gebruik moderne ES6+ syntax
Volg standaard ESLint-configuraties die in projecten worden geleverd
Gebruik betekenisvolle variabele- en functienamen voor educatieve duidelijkheid
Voeg opmerkingen toe die concepten uitleggen voor leerlingen
Formatteer met Prettier waar geconfigureerd

HTML/CSS

Semantische HTML5-elementen
Responsieve ontwerpprincipes
Duidelijke klassennaamgeving
Opmerkingen die CSS-technieken uitleggen voor leerlingen

Python

PEP 8-stijlrichtlijnen
Duidelijke, educatieve codevoorbeelden
Type hints waar nuttig voor leren

Markdown-documentatie

Duidelijke koppenhiërarchie
Codeblokken met taalspecificatie
Links naar aanvullende bronnen
Screenshots en afbeeldingen in images/-mappen
Alt-tekst voor afbeeldingen voor toegankelijkheid

Bestandsorganisatie

Lessen genummerd in volgorde (1-getting-started-lessons, 2-js-basics, enz.)
Elk project heeft solution/ en vaak start/ of your-work/-mappen
Afbeeldingen opgeslagen in les-specifieke images/-mappen
Vertalingen in translations/{language-code}/-structuur

Build en deployment

Quiz-app deployment (Azure Static Web Apps)

De quiz-app is geconfigureerd voor Azure Static Web Apps deployment:

cd quiz-app
npm run build      # Creates dist/ folder
# Deploys via GitHub Actions workflow on push to main

Azure Static Web Apps-configuratie:

App-locatie: /quiz-app
Output-locatie: dist
Workflow: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Documentatie PDF-generatie

npm install                    # Install docsify-to-pdf
npm run convert               # Generate PDF from docs

Docsify-documentatie

npm install -g docsify-cli    # Install Docsify globally
docsify serve                 # Serve on localhost:3000

Projectspecifieke builds

Elke projectmap kan zijn eigen buildproces hebben:

Vue-projecten: npm run build maakt productie-bundels
Statische projecten: Geen buildstap, bestanden direct serveren

Richtlijnen voor pull requests

Titelindeling

Gebruik duidelijke, beschrijvende titels die het gebied van wijziging aangeven:

[Quiz-app] Nieuwe quiz toevoegen voor les X
[Les-3] Typfout corrigeren in terrariumproject
[Vertaling] Spaanse vertaling toevoegen voor les 5
[Docs] Setup-instructies bijwerken

Vereiste controles

Voordat je een PR indient:

Codekwaliteit:
- Voer npm run lint uit in de getroffen projectmappen
- Los alle lintingfouten en -waarschuwingen op
Buildverificatie:
- Voer npm run build uit indien van toepassing
- Zorg ervoor dat er geen buildfouten zijn
Linkvalidatie:
- Test alle markdown-links
- Controleer of afbeeldingsverwijzingen werken
Inhoudscontrole:
- Controleer op spelling en grammatica
- Zorg ervoor dat codevoorbeelden correct en educatief zijn
- Controleer of vertalingen de oorspronkelijke betekenis behouden

Bijdragevereisten

Ga akkoord met Microsoft CLA (automatische controle bij eerste PR)
Volg de Microsoft Open Source Code of Conduct
Zie CONTRIBUTING.md voor gedetailleerde richtlijnen
Verwijs naar issuetickets in de PR-beschrijving indien van toepassing

Reviewproces

PR's worden beoordeeld door maintainers en de community
Educatieve duidelijkheid heeft prioriteit
Codevoorbeelden moeten huidige best practices volgen
Vertalingen worden beoordeeld op nauwkeurigheid en culturele geschiktheid

Vertalingssysteem

Geautomatiseerde vertaling

Gebruikt GitHub Actions met co-op-translator workflow
Vertaalt automatisch naar meer dan 50 talen
Bronbestanden in hoofdmap
Vertaalde bestanden in translations/{language-code}/-mappen

Handmatige verbeteringen aan vertalingen toevoegen

Zoek bestand in translations/{language-code}/
Breng verbeteringen aan terwijl je de structuur behoudt
Zorg ervoor dat codevoorbeelden functioneel blijven
Test eventuele gelokaliseerde quizinhoud

Metadata van vertalingen

Vertaalde bestanden bevatten een metadata-header:

<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->

Debugging en probleemoplossing

Veelvoorkomende problemen

Quiz-app start niet:

Controleer Node.js-versie (v14+ aanbevolen)
Verwijder node_modules en package-lock.json, voer npm install opnieuw uit
Controleer op poortconflicten (standaard: Vite gebruikt poort 5173)

API-server start niet:

Controleer of Node.js-versie voldoet aan minimumvereisten (node >=10)
Controleer of poort al in gebruik is
Zorg ervoor dat alle afhankelijkheden zijn geïnstalleerd met npm install

Browserextensie laadt niet:

Controleer of manifest.json correct is geformatteerd
Controleer browserconsole op fouten
Volg browser-specifieke installatie-instructies voor extensies

Python-chatprojectproblemen:

Zorg ervoor dat OpenAI-pakket is geïnstalleerd: pip install openai
Controleer of GITHUB_TOKEN-omgevingsvariabele is ingesteld
Controleer toegangsmachtigingen voor GitHub Models

Docsify serveert geen docs:

Installeer docsify-cli globaal: npm install -g docsify-cli
Voer uit vanuit de rootmap van de repository
Controleer of docs/_sidebar.md bestaat

Tips voor ontwikkelomgeving

Gebruik VS Code met Live Server-extensie voor HTML-projecten
Installeer ESLint- en Prettier-extensies voor consistente opmaak
Gebruik browser DevTools voor het debuggen van JavaScript
Voor Vue-projecten, installeer Vue DevTools-browserextensie

Prestatieoverwegingen

Groot aantal vertaalde bestanden (50+ talen) betekent dat volledige clones groot zijn
Gebruik een shallow clone als je alleen aan inhoud werkt: git clone --depth 1
Sluit vertalingen uit van zoekopdrachten bij het werken aan Engelse inhoud
Buildprocessen kunnen traag zijn bij de eerste run (npm install, Vite build)

Veiligheidsoverwegingen

Omgevingsvariabelen

API-sleutels mogen nooit in de repository worden opgenomen
Gebruik .env-bestanden (al in .gitignore)
Documenteer vereiste omgevingsvariabelen in project-README's

Python-projecten

Gebruik virtuele omgevingen: python -m venv venv
Houd afhankelijkheden up-to-date
GitHub-tokens moeten minimale vereiste machtigingen hebben

Toegang tot GitHub Models

Persoonlijke toegangstokens (PAT) vereist voor GitHub Models
Tokens moeten worden opgeslagen als omgevingsvariabelen
Nooit tokens of inloggegevens opnemen in de repository

Aanvullende opmerkingen

Doelgroep

Volledige beginners in webontwikkeling
Studenten en zelflerenden
Docenten die het curriculum in klaslokalen gebruiken
Inhoud is ontworpen voor toegankelijkheid en geleidelijke vaardigheidsopbouw

Educatieve filosofie

Projectgebaseerde leerbenadering
Regelmatige kenniscontroles (quizzen)
Praktische codeoefeningen
Voorbeelden van toepassingen in de echte wereld
Focus op basisprincipes vóór frameworks

Onderhoud van de repository

Actieve community van leerlingen en bijdragers
Regelmatige updates van afhankelijkheden en inhoud
Issues en discussies worden gemonitord door maintainers
Vertalingsupdates geautomatiseerd via GitHub Actions

Gerelateerde bronnen

Microsoft Learn-modules
Student Hub-bronnen
GitHub Copilot aanbevolen voor leerlingen
Aanvullende cursussen: Generatieve AI, Data Science, ML, IoT-curricula beschikbaar

Werken met specifieke projecten

Voor gedetailleerde instructies over individuele projecten, raadpleeg de README-bestanden in:

quiz-app/README.md - Vue 3 quiz-applicatie
7-bank-project/README.md - Bankapplicatie met authenticatie
5-browser-extension/README.md - Ontwikkeling van browserextensies
6-space-game/README.md - Canvas-gebaseerde spelontwikkeling
9-chat-project/README.md - AI-chatassistentproject

Monorepo-structuur

Hoewel geen traditionele monorepo, bevat deze repository meerdere onafhankelijke projecten:

Elke les is zelfstandig
Projecten delen geen afhankelijkheden
Werk aan individuele projecten zonder anderen te beïnvloeden
Clone de volledige repo voor de volledige curriculumervaring

Disclaimer:
Dit document is vertaald met behulp van de AI-vertalingsservice Co-op Translator. Hoewel we streven naar nauwkeurigheid, dient u zich ervan bewust te zijn dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal moet worden beschouwd als de gezaghebbende bron. Voor cruciale informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling.

13 KiB Raw Blame History