14 KiB

Raw Permalink Blame History

AGENTS.md

Přehled projektu

Toto je vzdělávací repozitář kurikula pro výuku základů webového vývoje pro začátečníky. Kurikulum je komplexní 12týdenní kurz vyvinutý Microsoft Cloud Advocates, obsahující 24 praktických lekcí pokrývajících JavaScript, CSS a HTML.

Klíčové součásti

Vzdělávací obsah: 24 strukturovaných lekcí uspořádaných v modulech založených na projektech
Praktické projekty: Terrárium, Typovací hra, Rozšíření pro prohlížeč, Vesmírná hra, Bankovní aplikace, Editor kódu a AI chat asistent
Interaktivní kvízy: 48 kvízů po 3 otázkách (před a po lekci)
Podpora více jazyků: Automatické překlady do 50+ jazyků pomocí GitHub Actions
Technologie: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (pro AI projekty)

Architektura

Vzdělávací repozitář se strukturou založenou na lekcích
Každá složka lekce obsahuje README, ukázky kódu a řešení
Samostatné projekty v oddělených adresářích (quiz-app, různé projekty lekcí)
Překladový systém využívající GitHub Actions (co-op-translator)
Dokumentace servírovaná přes Docsify a dostupná jako PDF

Příkazy pro nastavení

Tento repozitář je primárně určen ke konzumaci vzdělávacího obsahu. Pro práci s konkrétními projekty:

Nastavení hlavního repozitáře

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

Nastavení Quiz App (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Spustit vývojový server
npm run build      # Sestavit pro produkci
npm run lint       # Spustit ESLint

API projektu banky (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Spustit API server
npm run lint       # Spustit ESLint
npm run format     # Formátovat pomocí Prettier

Projekty Rozšíření prohlížeče

cd 5-browser-extension/solution
npm install
# Postupujte podle pokynů pro načítání rozšíření specifických pro prohlížeč

Projekty Vesmírné hry

cd 6-space-game/solution
npm install
# Otevřete index.html v prohlížeči nebo použijte Live Server

Chat projekt (Python Backend)

cd 9-chat-project/solution/backend/python
pip install openai
# Nastavte proměnnou prostředí GITHUB_TOKEN
python api.py

Vývojový workflow

Pro přispěvatele obsahu

Vytvořte fork tohoto repozitáře na svůj GitHub účet
Naklonujte svůj fork lokálně
Vytvořte novou větev pro své změny
Proveďte změny obsahu lekcí nebo ukázek kódu
Otestujte všechny změny kódu v relevantních projektech
Odešlete pull request podle pokynů pro přispívání

Pro studenty

Forkněte nebo naklonujte repozitář
Procházejte složky lekcí postupně
Čtěte README soubory ke každé lekci
Vyplňte předlekční kvízy na https://ff-quizzes.netlify.app/web/
Procházejte ukázky kódu v adresářích lekcí
Vyplňujte úkoly a výzvy
Vyplňte poválečné kvízy

Živý vývoj

Dokumentace: Spusťte docsify serve v kořenovém adresáři (port 3000)
Quiz App: Spusťte npm run dev ve složce quiz-app
Projekty: Použijte VS Code Live Server rozšíření pro HTML projekty
API Projekty: Spusťte npm start v odpovídajících API složkách

Instrukce pro testování

Testování Quiz App

cd quiz-app
npm run lint       # Zkontrolujte problémy se stylem kódu
npm run build      # Ověřte úspěšnost sestavení

Testování Bank API

cd 7-bank-project/api
npm run lint       # Zkontrolujte problémy se stylem kódu
node server.js     # Ověřte, že server startuje bez chyb

Obecný přístup k testování

Jedná se o vzdělávací repozitář bez komplexních automatických testů
Manuální testování zahrnuje:
- Ukázky kódu fungují bez chyb
- Odkazy v dokumentaci jsou funkční
- Projektové sestavení proběhne úspěšně
- Ukázky dodržují nejlepší postupy

Kontroly před odesláním

Spusťte npm run lint ve složkách s package.json
Ověřte platnost markdown odkazů
Otestujte ukázky kódu v prohlížeči nebo Node.js
Zkontrolujte, že překlady zachovávají správnou strukturu

Pravidla stylu kódu

JavaScript

Používejte moderní syntaxi ES6+
Dodržujte standardní ESLint konfigurace uváděné v projektech
Používejte smysluplné názvy proměnných a funkcí pro lepší vzdělávací srozumitelnost
Přidávejte komentáře vysvětlující koncepty pro studenty
Formátujte pomocí Prettier tam, kde je nastaven

HTML/CSS

Sémantické HTML5 prvky
Principy responzivního designu
Jasná pravidla pojmenování tříd
Komentáře vysvětlující CSS techniky pro studenty

Python

Dodržujte stylové zásady PEP 8
Jasné vzdělávací příklady kódu
Typové anotace kde pomáhají s učením

Markdown dokumentace

Jasná hierarchie nadpisů
Kódové bloky s uvedením jazyka
Odkazy na doplňkové zdroje
Screenshoty a obrázky ve složkách images/
Alternativní texty obrázků pro přístupnost

Organizace souborů

Lekce číslené pořadově (1-getting-started-lessons, 2-js-basics, atd.)
Každý projekt má složky solution/ a často start/ nebo your-work/
Obrázky uchovávány ve složkách images/ specifických pro lekci
Překlady ve struktuře translations/{language-code}/

Sestavení a nasazení

Nasazení Quiz App (Azure Static Web Apps)

Quiz-app je nakonfigurován pro nasazení v Azure Static Web Apps:

cd quiz-app
npm run build      # Vytváří složku dist/
# Nasazuje pomocí pracovního postupu GitHub Actions při pushi do větve main

Konfigurace Azure Static Web Apps:

Umístění aplikace: /quiz-app
Výstupní složka: dist
Workflow: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Generování PDF dokumentace

npm install                    # Nainstalujte docsify-to-pdf
npm run convert               # Vygenerujte PDF z docs

Dokumentace v Docsify

npm install -g docsify-cli    # Nainstalujte Docsify globálně
docsify serve                 # Spusťte na localhost:3000

Sestavení specifické pro projekty

Každý projekt může mít vlastní build proces:

Vue projekty: npm run build vytváří produkční balíčky
Statické projekty: Nemají sestavení, soubory se servírují přímo

Pravidla pro pull requesty

Formát názvu

Používejte jasné, popisné názvy indikující oblast změny:

[Quiz-app] Přidat nový kvíz pro lekci X
[Lesson-3] Opravit překlep v projektu terrárium
[Translation] Přidat španělský překlad pro lekci 5
[Docs] Aktualizovat instrukce pro nastavení

Požadované kontroly

Před odesláním PR:

Kvalita kódu:
- Spusťte npm run lint v ovlivněných složkách
- Opravte všechny linting chyby a varování
Ověření sestavení:
- Spusťte npm run build pokud je relevantní
- Zajistěte, že nejsou chyby při sestavení
Validace odkazů:
- Otestujte všechny markdown odkazy
- Ověřte, že obrázky jsou dostupné
Kontrola obsahu:
- Korektura pravopisu a gramatiky
- Ověření správnosti a vzdělávací hodnoty kódových příkladů
- Kontrola, že překlady zachovávají původní význam

Požadavky na přispívání

Souhlas s Microsoft CLA (automatická kontrola při prvním PR)
Dodržování Microsoft Open Source Code of Conduct
Podrobné pokyny v CONTRIBUTING.md
Pokud relevantní, odkazování na čísla issue v popisu PR

Proces recenze

PR jsou recenzovány správci a komunitou
Priorita vzdělávací srozumitelnosti
Příklady kódu by měly odpovídat aktuálním nejlepším praktikám
Překlady jsou kontrolovány z hlediska přesnosti a kulturní vhodnosti

Překladový systém

Automatický překlad

Použití GitHub Actions s workflow co-op-translator
Překlady do 50+ jazyků automaticky
Zdrojové soubory v hlavních adresářích
Přeložené soubory ve složkách translations/{language-code}/

Úpravy manuálních překladů

Najděte soubor v translations/{language-code}/
Proveďte vylepšení při zachování struktury
Zajistěte funkčnost kódových ukázek
Testujte lokalizovaný obsah kvízů

Metadata překladu

Přeložené soubory obsahují hlavičku s metadaty:

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

Ladění a řešení problémů

Běžné problémy

Quiz app se nespouští:

Zkontrolujte verzi Node.js (doporučeno v14+)
Smažte node_modules a package-lock.json, spusťte npm install znovu
Zkontrolujte konflikt portů (výchozí: Vite používá port 5173)

API server nenastartuje:

Ověřte, že verze Node.js je minimálně (node >=10)
Zkontrolujte, jestli port není obsazen
Ujistěte se, že jsou všechny závislosti nainstalovány přes npm install

Rozšíření prohlížeče se nenačte:

Ověřte správné formátování manifest.json
Zkontrolujte konzoli prohlížeče pro chyby
Postupujte podle pokynů pro instalaci rozšíření v daném prohlížeči

Problémy s Python chat projektem:

Ujistěte se, že balíček OpenAI je nainstalován: pip install openai
Zkontrolujte, že je nastavená proměnná prostředí GITHUB_TOKEN
Překontrolujte přístupová práva GitHub Models

Docsify nenačítá dokumentaci:

Globálně nainstalujte docsify-cli: npm install -g docsify-cli
Spusťte z kořenového adresáře repozitáře
Ověřte, že existuje docs/_sidebar.md

Tipy pro vývojové prostředí

Používejte VS Code s rozšířením Live Server pro HTML projekty
Nainstalujte si ESLint a Prettier rozšíření pro konzistentní formátování
Používejte nástroje pro vývojáře v prohlížeči pro ladění JavaScriptu
Pro Vue projekty nainstalujte Vue DevTools rozšíření do prohlížeče

Výkonové poznámky

Velké množství přeložených souborů (50+ jazyků) znamená, že plné klony jsou velké
Použijte shallow clone, pokud pracujete pouze s obsahem: git clone --depth 1
Vylučujte překlady z vyhledávání při práci na anglickém obsahu
Build procesy mohou být při prvním spuštění pomalé (npm install, Vite build)

Bezpečnostní aspekty

Proměnné prostředí

API klíče nikdy necommitujte do repozitáře
Používejte .env soubory (jsou v .gitignore)
Dokumentujte požadované proměnné prostředí v README souborech projektů

Python projekty

Používejte virtuální prostředí: python -m venv venv
Udržujte závislosti aktualizované
GitHub tokeny by měly mít minimální požadovaná oprávnění

Přístup k GitHub Models

Pro GitHub Models jsou vyžadovány Personal Access Tokeny (PAT)
Tokeny ukládejte jako proměnné prostředí
Nikdy necommitujte tokeny nebo přihlašovací údaje

Další poznámky

Cílová skupina

Kompletní začátečníci ve webovém vývoji
Studenti a samouci
Učitelé používající kurikulum ve třídách
Obsah navržený pro přístupnost a postupné budování dovedností

Vzdělávací filozofie

Přístup založený na projektech
Časté kontroly znalostí (kvízy)
Praktická cvičení v kódování
Ukázky reálných aplikací
Zaměření na základy před frameworky

Údržba repozitáře

Aktivní komunita studentů a přispěvatelů
Pravidelné aktualizace závislostí a obsahu
Problémy a diskuse sledovány správci
Aktualizace překladů automatizovány GitHub Actions

Související zdroje

Microsoft Learn moduly
Student Hub zdroje
GitHub Copilot doporučený pro studenty
Další kurzy: Generativní AI, Data Science, ML, IoT kurikula k dispozici

Práce s konkrétními projekty

Pro podrobné instrukce k jednotlivým projektům odkazujte na README soubory v:

quiz-app/README.md - Vue 3 aplikace kvízu
7-bank-project/README.md - Bankovní aplikace s autentizací
5-browser-extension/README.md - Vývoj rozšíření prohlížeče
6-space-game/README.md - Vývoj hry založené na Canvasu
9-chat-project/README.md - Projekt AI chat asistenta

Struktura monorepa

I když se nejedná o tradiční monorepo, tento repozitář obsahuje několik nezávislých projektů:

Každá lekce je samostatná
Projekty nesdílejí závislosti
Pracujte na jednotlivých projektech bez ovlivnění ostatních
Naklonujte celý repozitář pro plný zážitek kurikula

Prohlášení o vyloučení odpovědnosti:
Tento dokument byl přeložen pomocí AI překladatelské služby Co-op Translator. I když usilujeme o přesnost, uvědomte si, že automatické překlady mohou obsahovat chyby nebo nepřesnosti. Původní dokument v jeho rodném jazyce by měl být považován za autoritativní zdroj. Pro kritické informace se doporučuje profesionální lidský překlad. Nejsme odpovědní za jakékoli nedorozumění nebo nesprávné výklady vzniklé použitím tohoto překladu.

14 KiB Raw Permalink Blame History