21 KiB

Raw Permalink Blame History Unescape Escape

AGENTS.md

Огляд проєкту

Це репозиторій навчальної програми для викладання основ веб-розробки для початківців. Програма є комплексним 12-тижневим курсом, розробленим Microsoft Cloud Advocates, і включає 24 практичні уроки, що охоплюють JavaScript, CSS та HTML.

Основні компоненти

Навчальний контент: 24 структуровані уроки, організовані в модулі на основі проєктів
Практичні проєкти: Тераріум, гра на швидкість набору тексту, розширення для браузера, космічна гра, банківський додаток, редактор коду та AI чат-асистент
Інтерактивні вікторини: 48 вікторин по 3 питання кожна (оцінювання до/після уроку)
Підтримка багатомовності: Автоматичні переклади на 50+ мов за допомогою GitHub Actions
Технології: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (для AI проєктів)

Архітектура

Навчальний репозиторій зі структурою на основі уроків
Кожна папка уроку містить README, приклади коду та рішення
Окремі проєкти в окремих каталогах (quiz-app, різні проєкти уроків)
Система перекладу за допомогою GitHub Actions (co-op-translator)
Документація доступна через Docsify та у форматі PDF

Команди для налаштування

Цей репозиторій призначений переважно для споживання навчального контенту. Для роботи з конкретними проєктами:

Налаштування основного репозиторію

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

Налаштування додатку для вікторин (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

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

Проєкти розширень для браузера

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

Проєкти космічної гри

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

Проєкт чату (Python Backend)

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

Робочий процес розробки

Для контрибуторів контенту

Форкніть репозиторій у свій обліковий запис GitHub
Клонуйте форк локально
Створіть нову гілку для своїх змін
Внесіть зміни до контенту уроків або прикладів коду
Протестуйте будь-які зміни коду у відповідних каталогах проєктів
Надішліть pull request відповідно до рекомендацій щодо внеску

Для учнів

Форкніть або клонуйте репозиторій
Переміщайтеся по каталогах уроків послідовно
Читайте файли README для кожного уроку
Виконуйте вікторини перед уроком на https://ff-quizzes.netlify.app/web/
Працюйте з прикладами коду в папках уроків
Виконуйте завдання та виклики
Проходьте вікторини після уроку

Жива розробка

Документація: Запустіть docsify serve у кореневій папці (порт 3000)
Додаток для вікторин: Запустіть npm run dev у папці quiz-app
Проєкти: Використовуйте розширення Live Server у VS Code для HTML-проєктів
API-проєкти: Запустіть npm start у відповідних каталогах API

Інструкції з тестування

Тестування додатку для вікторин

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

Тестування API банківського проєкту

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

Загальний підхід до тестування

Це навчальний репозиторій без комплексних автоматизованих тестів
Ручне тестування зосереджене на:
- Виконанні прикладів коду без помилок
- Коректній роботі посилань у документації
- Успішному завершенні збірки проєктів
- Дотриманні найкращих практик у прикладах

Перевірки перед відправкою

Запустіть npm run lint у каталогах із package.json
Перевірте валідність посилань у markdown
Протестуйте приклади коду в браузері або Node.js
Переконайтеся, що переклади зберігають правильну структуру

Збірка та розгортання

Розгортання додатку для вікторин (Azure Static Web Apps)

Додаток quiz-app налаштований для розгортання в Azure Static Web Apps:

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

Конфігурація Azure Static Web Apps:

Розташування додатку: /quiz-app
Розташування вихідних файлів: dist
Робочий процес: .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml

Генерація документації у форматі PDF

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

Документація Docsify

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

Збірки, специфічні для проєктів

Кожен каталог проєкту може мати власний процес збірки:

Проєкти на Vue: npm run build створює продакшн-бандли
Статичні проєкти: Немає етапу збірки, файли можна використовувати напряму

Система перекладу

Автоматичний переклад

Використовує GitHub Actions із робочим процесом co-op-translator
Автоматично перекладає на 50+ мов
Вихідні файли в основних каталогах
Перекладені файли в translations/{language-code}/

Додавання покращень до ручного перекладу

Знайдіть файл у translations/{language-code}/
Внесіть покращення, зберігаючи структуру
Переконайтеся, що приклади коду залишаються функціональними
Протестуйте будь-який локалізований контент вікторин

Метадані перекладу

Перекладені файли включають заголовок метаданих:

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

Виправлення помилок і усунення несправностей

Поширені проблеми

Додаток для вікторин не запускається:

Перевірте версію Node.js (рекомендовано v14+)
Видаліть node_modules і package-lock.json, запустіть npm install знову
Перевірте конфлікти портів (за замовчуванням: Vite використовує порт 5173)

Сервер API не запускається:

Переконайтеся, що версія Node.js відповідає мінімальним вимогам (node >=10)
Перевірте, чи порт уже використовується
Переконайтеся, що всі залежності встановлені за допомогою npm install

Розширення для браузера не завантажується:

Перевірте, чи файл manifest.json правильно відформатований
Перевірте консоль браузера на наявність помилок
Дотримуйтесь інструкцій з встановлення розширень для конкретного браузера

Проблеми з проєктом чату на Python:

Переконайтеся, що пакет OpenAI встановлений: pip install openai
Перевірте, чи встановлена змінна середовища GITHUB_TOKEN
Перевірте дозволи доступу до GitHub Models

Docsify не обслуговує документацію:

Встановіть docsify-cli глобально: npm install -g docsify-cli
Запустіть із кореневого каталогу репозиторію
Перевірте, чи існує файл docs/_sidebar.md

Поради щодо середовища розробки

Використовуйте VS Code із розширенням Live Server для HTML-проєктів
Встановіть розширення ESLint і Prettier для узгодженого форматування
Використовуйте DevTools браузера для налагодження JavaScript
Для проєктів на Vue встановіть розширення Vue DevTools для браузера

Міркування щодо продуктивності

Велика кількість перекладених файлів (50+ мов) означає, що повні клонування є великими
Використовуйте неглибоке клонування, якщо працюєте лише над контентом: git clone --depth 1
Виключайте переклади з пошуку, якщо працюєте над англійським контентом
Процеси збірки можуть бути повільними при першому запуску (npm install, Vite build)

Міркування щодо безпеки

Змінні середовища

API-ключі ніколи не повинні бути закомічені в репозиторій
Використовуйте .env файли (вже в .gitignore)
Документуйте необхідні змінні середовища в README проєктів

Проєкти на Python

Використовуйте віртуальні середовища: python -m venv venv
Підтримуйте залежності в актуальному стані
Токени GitHub повинні мати мінімально необхідні дозволи

Доступ до GitHub Models

Потрібні персональні токени доступу (PAT) для GitHub Models
Токени повинні зберігатися як змінні середовища
Ніколи не комітьте токени або облікові дані

Додаткові примітки

Цільова аудиторія

Повні новачки у веб-розробці
Студенти та самонавчальники
Викладачі, які використовують програму в класах
Контент розроблений для доступності та поступового нарощування навичок

Освітня філософія

Підхід на основі проєктів
Часті перевірки знань (вікторини)
Практичні вправи з кодування
Приклади реального застосування
Фокус на основах перед переходом до фреймворків

Підтримка репозиторію

Активна спільнота учнів і контрибуторів
Регулярні оновлення залежностей і контенту
Проблеми та обговорення контролюються мейнтейнерами
Оновлення перекладів автоматизовані через GitHub Actions

Супутні ресурси

Модулі Microsoft Learn
Ресурси Student Hub
GitHub Copilot рекомендований для учнів
Додаткові курси: Генеративний AI, Data Science, ML, IoT навчальні програми доступні

Робота з конкретними проєктами

Для детальних інструкцій щодо окремих проєктів звертайтеся до файлів README у:

quiz-app/README.md - додаток для вікторин на Vue 3
7-bank-project/README.md - банківський додаток із аутентифікацією
5-browser-extension/README.md - розробка розширень для браузера
6-space-game/README.md - розробка гри на Canvas
9-chat-project/README.md - проєкт AI чат-асистента

Структура монорепозиторію

Хоча це не традиційний монорепозиторій, цей репозиторій містить кілька незалежних проєктів:

Кожен урок є самостійним
Проєкти не мають спільних залежностей
Працюйте над окремими проєктами, не впливаючи на інші
Клонуйте весь репозиторій для повного навчального досвіду

Відмова від відповідальності:
Цей документ було перекладено за допомогою сервісу автоматичного перекладу Co-op Translator. Хоча ми прагнемо до точності, звертаємо вашу увагу, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ мовою оригіналу слід вважати авторитетним джерелом. Для критично важливої інформації рекомендується професійний переклад людиною. Ми не несемо відповідальності за будь-які непорозуміння або неправильне тлумачення, що виникли внаслідок використання цього перекладу.

21 KiB Raw Permalink Blame History Unescape Escape