AGENTS.md

1# AGENTS.md
2 
3## Projektöversikt
4 
5Detta är ett utbildningscurriculum för att lära ut grunderna i webbutveckling till nybörjare. Curriculumet är en omfattande 12-veckorskurs utvecklad av Microsoft Cloud Advocates, med 24 praktiska lektioner som täcker JavaScript, CSS och HTML.
6 
7### Viktiga komponenter
8 
9- **Utbildningsinnehåll**: 24 strukturerade lektioner organiserade i projektbaserade moduler
10- **Praktiska projekt**: Terrarium, Skrivspel, Webbläsartillägg, Rymdspel, Bankapp, Kodredigerare och AI-chattassistent
11- **Interaktiva quiz**: 48 quiz med 3 frågor vardera (före- och efter-lektionsbedömningar)
12- **Flerspråkigt stöd**: Automatiska översättningar till 50+ språk via GitHub Actions
13- **Teknologier**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (för AI-projekt)
14 
15### Arkitektur
16 
17- Utbildningsrepository med lektionsbaserad struktur
18- Varje lektionsmapp innehåller README, kodexempel och lösningar
19- Självständiga projekt i separata kataloger (quiz-app, olika lektionsprojekt)
20- Översättningssystem som använder GitHub Actions (co-op-translator)
21- Dokumentation tillgänglig via Docsify och som PDF
22 
23## Installationskommandon
24 
25Detta repository är främst för konsumtion av utbildningsinnehåll. För arbete med specifika projekt:
26 
27### Huvudrepositoryinstallation
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Quiz App Installation (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Starta utvecklingsserver
40npm run build      # Bygg för produktion
41npm run lint       # Kör ESLint
42```
43 
44### Bankprojekt API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Starta API-server
50npm run lint       # Kör ESLint
51npm run format     # Formatera med Prettier
52```
53 
54### Webbläsartilläggsprojekt
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Följ webbläsarspecifika instruktioner för att ladda tillägg
60```
61 
62### Rymdspelsprojekt
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Öppna index.html i webbläsaren eller använd Live Server
68```
69 
70### Chattprojekt (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Sätt miljövariabeln GITHUB_TOKEN
76python api.py
77```
78 
79## Utvecklingsarbetsflöde
80 
81### För innehållsbidragare
82 
831. **Forka repositoryt** till ditt GitHub-konto
842. **Klona din fork** lokalt
853. **Skapa en ny branch** för dina ändringar
864. Gör ändringar av lektioninnehåll eller kodexempel
875. Testa kodändringar i relevanta projektmappar
886. Skicka pull requests enligt riktlinjerna för bidrag
89 
90### För elever
91 
921. Forka eller klona repositoryt
932. Navigera sekventiellt till lektionsmappar
943. Läs README-filer för varje lektion
954. Genomför quiz före lektioner på https://ff-quizzes.netlify.app/web/
965. Arbeta igenom kodexempel i lektionsmappar
976. Slutför uppgifter och utmaningar
987. Gör quiz efter lektioner
99 
100### Live-utveckling
101 
102- **Dokumentation**: Kör `docsify serve` i rotmappen (port 3000)
103- **Quiz App**: Kör `npm run dev` i quiz-app-katalogen
104- **Projekt**: Använd VS Code Live Server-tillägg för HTML-projekt
105- **API-projekt**: Kör `npm start` i respektive API-katalog
106 
107## Testinstruktioner
108 
109### Quiz App-testning
110 
111```bash
112cd quiz-app
113npm run lint       # Kontrollera kodstilproblem
114npm run build      # Verifiera att kompilering lyckas
115```
116 
117### Bank API-testning
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Kontrollera kodstilproblem
122node server.js     # Verifiera att servern startar utan fel
123```
124 
125### Allmän testmetod
126 
127- Detta är ett utbildningsrepository utan omfattande automatiserade tester
128- Manuell testning fokuserar på:
129  - Kodexempel körs utan fel
130  - Länkar i dokumentation fungerar korrekt
131  - Projekt bygger klart utan problem
132  - Exempel följer bästa praxis
133 
134### Kontroll före inskickning
135 
136- Kör `npm run lint` i kataloger med package.json
137- Verifiera att markdown-länkar är giltiga
138- Testa kodexempel i webbläsare eller Node.js
139- Kontrollera att översättningar behåller korrekt struktur
140 
141## Kodstilriktlinjer
142 
143### JavaScript
144 
145- Använd modern ES6+ syntax
146- Följ standard ESLint-konfigurationer i projekten
147- Använd meningsfulla variabel- och funktionsnamn för tydlighet i utbildningen
148- Lägg till kommentarer som förklarar koncept för elever
149- Formatera med Prettier där det är konfigurerat
150 
151### HTML/CSS
152 
153- Semantiska HTML5-element
154- Responsiva designprinciper
155- Klara och tydliga klassnamn
156- Kommentarer som förklarar CSS-tekniker för elever
157 
158### Python
159 
160- Följ PEP 8-stilriktlinjer
161- Tydliga, pedagogiska kodexempel
162- Typanvisningar där det är hjälpsamt för lärande
163 
164### Markdown-dokumentation
165 
166- Tydlig rubrikhierarki
167- Kodblock med språkangivelse
168- Länkar till ytterligare resurser
169- Skärmdumpar och bilder i `images/`-mappar
170- Alt-text för bilder för tillgänglighet
171 
172### Filorganisation
173 
174- Lektioner numrerade sekventiellt (1-getting-started-lessons, 2-js-basics, etc.)
175- Varje projekt har `solution/` och ofta `start/` eller `your-work/`-mappar
176- Bilder lagras i lektion-specifika `images/`-mappar
177- Översättningar i `translations/{language-code}/`-struktur
178 
179## Bygg och distribution
180 
181### Distribution av Quiz App (Azure Static Web Apps)
182 
183quiz-app är konfigurerad för deployment via Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Skapar dist/-mappen
188# Distribuerar via GitHub Actions arbetsflöde vid push till main
189```
190 
191Azure Static Web Apps-konfiguration:
192- **App-lokalisation**: `/quiz-app`
193- **Output-lokalisation**: `dist`
194- **Arbetsflöde**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### PDF-generering av dokumentation
197 
198```bash
199npm install                    # Installera docsify-to-pdf
200npm run convert               # Generera PDF från docs
201```
202 
203### Docsify-dokumentation
204 
205```bash
206npm install -g docsify-cli    # Installera Docsify globalt
207docsify serve                 # Servera på localhost:3000
208```
209 
210### Projekt-specifika byggprocesser
211 
212Varje projektkatalog kan ha sin egen byggprocess:
213- Vue-projekt: `npm run build` skapar produktionspaket
214- Statiska projekt: Ingen byggsteg, servera filer direkt
215 
216## Pull Request-riktlinjer
217 
218### Titelformat
219 
220Använd tydliga, beskrivande titlar som anger ändringsområde:
221- `[Quiz-app] Lägg till nytt quiz för lektion X`
222- `[Lesson-3] Åtgärda stavfel i terrariumprojekt`
223- `[Translation] Lägg till spansk översättning för lektion 5`
224- `[Docs] Uppdatera installationsinstruktioner`
225 
226### Obligatoriska kontroller
227 
228Innan PR skickas:
229 
2301. **Kodkvalitet**:
231   - Kör `npm run lint` i berörda projektmappar
232   - Åtgärda alla lintfel och varningar
233 
2342. **Byggverifiering**:
235   - Kör `npm run build` om tillämpligt
236   - Säkerställ att inga byggfel uppstår
237 
2383. **Länkvalidering**:
239   - Testa alla markdown-länkar
240   - Verifiera bildreferenser fungerar
241 
2424. **Innehållsgranskning**:
243   - Korrekturläs för stavning och grammatik
244   - Säkerställ kodexempel är korrekta och pedagogiska
245   - Kontrollera att översättningar bevarar ursprungligt budskap
246 
247### Bidragskrav
248 
249- Acceptera Microsoft CLA (automatisk kontroll vid första PR)
250- Följ [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- Se [CONTRIBUTING.md](./CONTRIBUTING.md) för detaljerade riktlinjer
252- Referera ärendenummer i PR-beskrivning om tillämpligt
253 
254### Granskningsprocess
255 
256- PR granskas av underhållare och community
257- Pedagogisk tydlighet prioriteras
258- Kodexempel ska följa aktuella bästa praxis
259- Översättningar granskas för korrekthet och kulturell anpassning
260 
261## Översättningssystem
262 
263### Automatisk översättning
264 
265- Använder GitHub Actions med co-op-translator arbetsflöde
266- Översätter automatiskt till 50+ språk
267- Källfiler i huvudkataloger
268- Översatta filer i `translations/{language-code}/`-mappar
269 
270### Lägga till manuella förbättringar
271 
2721. Lokalisera fil i `translations/{language-code}/`
2732. Gör förbättringar med bibehållen struktur
2743. Säkerställ att kodexempel fortsätter att fungera
2754. Testa lokaliserat quiz-innehåll
276 
277### Metadata för översättningar
278 
279Översatta filer inkluderar 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## Felsökning och problemlösning
293 
294### Vanliga problem
295 
296**Quiz app startar inte**:
297- Kontrollera Node.js-version (v14+ rekommenderas)
298- Ta bort `node_modules` och `package-lock.json`, kör `npm install` igen
299- Kontrollera portkonflikter (standard: Vite använder port 5173)
300 
301**API-server startar inte**:
302- Verifiera att Node.js-version uppfyller minimikrav (node >=10)
303- Kontrollera om port redan används
304- Se till att alla beroenden är installerade med `npm install`
305 
306**Webbläsartillägg laddas inte**:
307- Verifiera att manifest.json är korrekt formaterad
308- Kontrollera webbläsarkonsol för fel
309- Följ webbläsarspecifika installationsinstruktioner för tillägg
310 
311**Problem med Python-chattprojekt**:
312- Säkerställ att OpenAI-paket är installerat: `pip install openai`
313- Kontrollera att miljövariabeln GITHUB_TOKEN är satt
314- Kontrollera tillgång till GitHub Models
315 
316**Docsify serverar inte dokumentation**:
317- Installera docsify-cli globalt: `npm install -g docsify-cli`
318- Kör från repositories rotkatalog
319- Kontrollera att `docs/_sidebar.md` finns
320 
321### Tips för utvecklingsmiljö
322 
323- Använd VS Code med Live Server-tillägg för HTML-projekt
324- Installera ESLint och Prettier-tillägg för konsekvent formatering
325- Använd webbläsarens utvecklarverktyg för att felsöka JavaScript
326- För Vue-projekt, installera Vue DevTools webbläsartillägg
327 
328### Prestandaöverväganden
329 
330- Stort antal översatta filer (50+ språk) gör att fulla kloner blir stora
331- Använd shallow clone vid arbete enbart med innehåll: `git clone --depth 1`
332- Exkludera översättningar från sökningar vid arbete med engelskt innehåll
333- Byggprocesser kan vara långsamma vid första körning (npm install, Vite build)
334 
335## Säkerhetsöverväganden
336 
337### Miljövariabler
338 
339- API-nycklar ska aldrig committas till repositoryt
340- Använd `.env`-filer (är redan med i `.gitignore`)
341- Dokumentera nödvändiga miljövariabler i projekts README-filer
342 
343### Python-projekt
344 
345- Använd virtuella miljöer: `python -m venv venv`
346- Håll beroenden uppdaterade
347- GitHub-token bör ha minimala tillåtna behörigheter
348 
349### GitHub Models access
350 
351- Personliga Access Tokens (PAT) krävs för GitHub Models
352- Tokens bör lagras som miljövariabler
353- Aldrig commit tokens eller inloggningsuppgifter
354 
355## Ytterligare anteckningar
356 
357### Målgrupp
358 
359- Kompletta nybörjare i webbutveckling
360- Studenter och självstudenter
361- Lärare som använder curriculum i klassrum
362- Innehåll designat för tillgänglighet och gradvis kompetensuppbyggnad
363 
364### Pedagogisk filosofi
365 
366- Projektbaserat lärande
367- Frekventa kunskapskontroller (quiz)
368- Praktiska kodningsövningar
369- Exempel från verkliga applikationer
370- Fokus på grunder innan ramverk
371 
372### Repositoryunderhåll
373 
374- Aktiv community av elever och bidragsgivare
375- Regelbundna uppdateringar av beroenden och innehåll
376- Ärenden och diskussioner övervakas av underhållare
377- Översättningsuppdateringar automatiserade via GitHub Actions
378 
379### Relaterade resurser
380 
381- [Microsoft Learn-moduler](https://docs.microsoft.com/learn/)
382- [Student Hub-resurser](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) rekommenderas för elever
384- Ytterligare kurser: Generativ AI, Data Science, ML, IoT curriculum tillgängliga
385 
386### Arbeta med specifika projekt
387 
388För detaljerade instruktioner om individuella projekt, se README-filer i:
389- `quiz-app/README.md` - Vue 3 quizapplikation
390- `7-bank-project/README.md` - Bankapplikation med autentisering
391- `5-browser-extension/README.md` - Webbläsartilläggsutveckling
392- `6-space-game/README.md` - Canvas-baserat spel
393- `9-chat-project/README.md` - AI-chattassistentprojekt
394 
395### Monorepo-struktur
396 
397Även om det inte är ett traditionellt monorepo innehåller detta repository flera oberoende projekt:
398- Varje lektion är självständig
399- Projekt delar inte beroenden
400- Arbeta med individuella projekt utan påverkan på andra
401- Klona hela repositoryt för hela curriculum-upplevelsen
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Ansvarsfriskrivning**:
407Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, var vänlig notera att automatiska översättningar kan innehålla fel eller felaktigheter. Det ursprungliga dokumentet på dess modersmål bör betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår från användningen av denna översättning.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->