107 lines
12 KiB
Markdown
107 lines
12 KiB
Markdown
# Структура навчальної програми
|
||
|
||
Наш основний навчальний контент знаходиться у каталозі під назвою `навчальна програма`. На цій сторінці буде детально описано, як ці файли організовані.
|
||
|
||
## Термінологія
|
||
|
||
При обговоренні навчальної програми важливо знати декілька термінів.
|
||
|
||
- `certification` : Коли йдеться про сертифікацію, мається на увазі сертифікати, які отримують користувачі. Це не те саме, що й superBlock.
|
||
- `superBlock` : superBlock — це збірка найскладніших завдань. Кожен суперблок відповідає сертифікату в навчальній програмі (наприклад, Адаптивний вебдизайн).
|
||
- `block` : Блок — це розділ у межах superblock. Блок відповідає групі завдань у даній сертифікації (наприклад, Базовий HTML та HTML5)
|
||
- `challenge` : Завдання — це окремий урок у навчальній програмі (наприклад, Ознайомтесь з HTML елементами)
|
||
|
||
## Дерево файлів
|
||
|
||
Ось як буде виглядати структура файлів з цими термінами:
|
||
|
||
<!-- prettier-ignore -->
|
||
```md
|
||
|
||
curriculum/
|
||
├─ _meta/
|
||
│ ├─ {block}/
|
||
│ │ ├─ meta.json
|
||
├─ {language}/
|
||
│ ├─ {superBlock}/
|
||
│ │ ├─ {block}/
|
||
│ │ │ ├─ {challenge}.md
|
||
```
|
||
|
||
## Каталог `_meta`
|
||
|
||
Каталог `_meta` — це особливий каталог, який містить `.json` файли. Ці файли відповідають кожному окремому блоку в навчальній програмі та використовуються, щоб визначити до якого суперблоку належить блок та порядок завдань у цьому блоці.
|
||
|
||
## Перейменування файлів
|
||
|
||
Інколи вам потрібно перейменувати сертифікат, суперблок, блок чи завдання. У цьому розділі будуть описані важливі кроки, які допоможуть вам уникнути помилок збірки.
|
||
|
||
> [!УВАГА] Перейменування файлів у структурі навчальної програми часто змінює шлях (або URL-адресу) контенту на головній вебсторінці. Робити це слід з обережністю, оскільки перенаправлення потрібно налаштовувати для кожної внесеної зміни.
|
||
|
||
### Перейменування сертифікату
|
||
|
||
Під час перейменування сертифікату ви, ймовірно, захочете перейменувати пов’язаний із ним суперблок. Виконуйте наступні дії, щоб перейменувати лише сертифікат:
|
||
|
||
1. Оберіть нову назву для теки `curriculum/challenges/_meta/{superBlock}-certificate`.
|
||
1. У файлі `meta.json` тієї теки, змініть значення в `name`, `dashedName` і `challengeOrder` на нову назву.
|
||
1. У `curriculum/challenges/english/12-certificate`, перейменуйте теку `{superBlock}-certificate` і YAML файл у ній.
|
||
1. У YAML файлі, змініть `title` на нову назву.
|
||
1. Перейменуйте файл і теку з третього кроку для інших мов навчальної програми.
|
||
1. Оновіть `client/src/redux/index.ts`, щоб використовувати правильний `title`.
|
||
1. За бажанням оновіть і `certSlug` для суперблока в цьому ж файлі. **Зауважте**, що перейменування `certSlug` змінить URL-адресу для сертифікатів, тому це слід робити обачно.
|
||
1. Оновіть `title` в `client/src/resources/cert-and-project-map.ts` до нових значень. **Зверніть увагу**, що зміна `title` тут **зруйнує** superBlock сторінку для відповідної сертифікації. Це пов'язано із тим, що назва superBlock має відповідати назві сертифікації. Бажано одночасно змінити й назву суперблоку.
|
||
1. Якщо Ви перейменували `certSlug` у сьомому кроці, змініть його тут для сертифіката і вкладених `projects` значень.
|
||
1. У `config/certification-settings.js`, оновіть значення `certTypeTitleMap` на нову назву.
|
||
1. Якщо Ви перейменували `certSlug` у сьомому кроці, оновіть ключ доступу `certSlugTypeMap` в цьому ж файлі.
|
||
1. За необхідності оновіть ім'я сертифікату в масиві `legacyCerts` з `client/src/client-only-routes/show-project-links.tsx`.
|
||
1. Оновіть основний файл `README.md` до нового імені.
|
||
|
||
### Перейменування суперблоку
|
||
|
||
> [!NOTE] Під час перейменування суперблоку, нове ім’я теки використовується як шлях і його слід вважати «вірним» ім’ям. Усі інші значення слід оновити, щоб показати цю зміну.
|
||
|
||
Крім того, ви, ймовірно, захочете перейменувати сертифікат та блок `{superBlock}-projects` одночасно із superBlock, оскільки всі вони мають спільну назву. Виконайте наступні кроки, щоб перейменувати лише superBlock:
|
||
|
||
1. Перейменуйте теку superBlock у каталозі `curriculum/challenges/english`.
|
||
1. Перейменуйте теку superBlock у _всіх_ інших каталогах `curriculum/challenges/{language}`.
|
||
1. Для кожного блоку в цьому суперблоці оновіть значення `superBlock` в `meta.json` файлі на його ж dashedName. Вам не потрібно перейменовувати теки тут. Зробіть це при перейменуванні блоку.
|
||
1. Перейменуйте теку суперблоку в `client/src/pages/learn`.
|
||
1. Оновіть файл `index.md` у вищевказаній теці, змінивши `title` та `superBlock` значення на нове ім'я.
|
||
1. Для кожної вищезазначеної теки у блоці, оновіть `index.md`, щоб використовувати її за правильним `superBlock` значенням.
|
||
1. У файлі `client/src/resources/cert-and-project-map.ts`, оновіть алгоритм дій до сертифіката на початку файлу і значення `title` для цього суперблоку. **Зверніть увагу:** зміна `title` тут **забере у Вас** можливість переглядати дійсні сертифікати для цього суперблоку. Це пов'язано із тим, що назва superBlock має відповідати назві сертифікації. Бажано одночасно змінити й назву сертифіката.
|
||
1. Оновіть `superBlockCertTypeMap` ключ у `config/certification-settings.js` до нової назви суперблоку.
|
||
1. Оновіть значення шляху в `client/src/assets/icons/index.tsx`.
|
||
1. Оновіть `intro.json` файл для кожної мови в `client/i18n/locales`, щоб мати змогу використати новий суперблок `dashedName`. В англійському файлі також оновіть `title`.
|
||
1. Перевірте `config/i18n/all-langs.js` файл, щоб побачити чи надав суперблок можливість конвертації. Оновіть усі значення, де він використовується.
|
||
1. Оновіть назву головного `README.md` файлу.
|
||
|
||
### Перейменування блоку
|
||
|
||
При перейменуванні блоку навчальної програми, вам варто:
|
||
|
||
1. Змінити назву теки блоку в каталозі `curriculum/challenges/english/{superBlock}`.
|
||
1. Змінити назву тієї ж самої теки блоку в _усіх_ іншомовних каталогах, аби вони збігалися. Вони повинні бути такі ж самі як і в англійській теці, інакше буде помилка збірки.
|
||
1. Змінити назву теки блоку в `_meta` каталозі.
|
||
1. Оновити властивості `name` та `dashedName` для `meta.json` файлу цього блоку.
|
||
1. Оновити `client/utils/help-category-map.json`, щоб використати нову назву блоку як основну.
|
||
1. Оновити теку блоку в `client/src/pages/learn/{superBlock}`.
|
||
1. Оновити `block` значення в титульному елементі в файлі `index.md` з вищезгаданої теки.
|
||
1. У файлах `client/i18n/locales/{language}/intro.json` оновіть назву блоку до нової для всіх мов. В англійському файлі `intro.json` також оновіть `title`.
|
||
1. Оновити основний `README.md` файл до нового імені.
|
||
|
||
### Перейменування завдання
|
||
|
||
Під час перейменування окремого файлу завдання Вам необхідно:
|
||
|
||
1. Змінити назву файлу завдання в каталозі `curriculum/challenges/english`.
|
||
1. Змінити назву `title` і `dashedName` у цьому файлі.
|
||
1. Змінити назву файлу та `dashedName` у цих файлах для _всіх_ каталогів мов так, щоб вони збігалися.
|
||
1. Оновити назву завдання у відповідному файлі `meta.json`. Ці назви завдань не використовуються у збірці, але забезпечують зручний спосіб ідентифікації порядку завдань.
|
||
1. Якщо за це завдання передбачений сертифікат, то оновіть назву файлу YAML у `curriculum/english/12-certificates/<superBlock>`.
|
||
1. Якщо за це завдання передбачений сертифікат, оновіть `title` та `link` в `client/src/resources/cert-and-project-map.ts`
|
||
1. Якщо за це завдання передбачений сертифікат, оновіть основний файл `README.md` до нового імені.
|
||
|
||
## Властивість `dashedName`
|
||
|
||
The `dashedName` property is used to generate the URL path for the superblock, block, or challenge. These should generally match what the `/utils/slugs.js` helper would output for the file name.
|