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