dataviz-portfolio/README.md

# Портфоліо · шаблон

Сайт для ваших робіт із курсу «Візуалізація даних». Хто відкриє
посилання, одразу бачить самі роботи — без проміжних сторінок.
Вбудовує графіки й дашборди з **Tableau Public** і специфікації
**Vega-Lite**.

Одна робота — це **один файл** у теці `_works/`. Пишете звичайним
текстом. HTML не потрібен ніде.

Установлювати нічого не треба. Усе робиться в браузері.

> **Сайт публічний.** Його бачить будь-хто в інтернеті, і ваше ім'я
> стоїть на ньому. Беріть навчальні або відкриті дані. Якщо графік
> зроблено на робочих даних, заберіть назви клієнтів і справжні суми
> або візьміть інший графік. У Tableau Public вимкніть **Allow
> Access**: інакше книгу з даними можна завантажити.

---

## Крок 1. Зробіть із шаблону свій репозиторій

1. Угорі натисніть зелену кнопку **Use this template**.
2. Виберіть **Create a new repository**.
3. У полі **Repository name** напишіть `dataviz-portfolio`.
4. Виберіть **Public**. Приватний репозиторій не публікується.
5. Натисніть **Create repository**.

Далі ви працюєте у своєму репозиторії, не в цьому.

## Крок 2. Увімкніть публікацію

1. У своєму репозиторії відкрийте вкладку **Settings**.
2. Зліва виберіть **Pages**.
3. У полі **Source** виберіть `Deploy from a branch`.
4. У полі **Branch** виберіть `main` і теку `/ (root)`.
5. Натисніть **Save**.
6. Зачекайте одну-дві хвилини й оновіть **Settings → Pages**.

Угорі з'явиться адреса вашого сайту:

```
https://ВАШ-ЛОГІН.github.io/dataviz-portfolio/
```

Відкрийте її. Сайт уже працює: дві роботи-приклади і список робіт
у бічній панелі.

## Крок 3. Підпишіть сайт своїм іменем

Ім'я стоїть в одному місці — у файлі `_config.yml`.

1. Відкрийте `_config.yml`.
2. Замініть `title`, `role` і `tagline`.
3. Натисніть **Commit changes**.

```yaml
title: "Олена Ковальчук"
role: "Аналітик даних"
tagline: "Роботи з курсу «Візуалізація даних» KSE, 2026."
```

Через хвилину сайт оновиться сам.

Лапки навколо тексту обов'язкові. Якщо в тексті потрібні лапки,
беріть «такі».

---

## Як додати роботу

Одна робота — один файл у теці `_works/`.

1. Відкрийте теку `_works`.
2. Натисніть **Add file → Create new file**.
3. Напишіть ім'я файлу латиницею, з `.md` на кінці: `03-facets.md`.
4. Вставте текст нижче і замініть його своїм.
5. Натисніть **Commit changes**.

Робота з **Tableau Public**:

```markdown
---
title: "Назва роботи"
card: "Один рядок для картки на головній."
tableau: "https://public.tableau.com/app/profile/ваш.профіль/viz/Книга/Аркуш"
---

**Питання:** на яке питання відповідає графік.

**Рішення:** що ви вирішили і чому.

**Що видно:** що з цього побачив читач.
```

Робота з **Vega-Lite**:

```markdown
---
title: "Назва роботи"
card: "Один рядок для картки на головній."
spec: "specs/my-chart.json"
---

**Питання:** на яке питання відповідає графік.
```

Файл специфікації покладіть у теку `specs`: **Add file → Upload
files** → перетягніть файл → **Commit changes**. Ім'я файлу —
латиницею, без пробілів.

Роботи стоять на сторінці за іменем файлу, за абеткою. Тому ставте
число попереду: `01-`, `02-`, `03-`. Пункт у бічній панелі
з'являється сам.

Найсильнішу роботу ставте першою. Її побачать усі, решту —
не обов'язково.

### Що можна написати в шапці

| Поле | Навіщо |
|---|---|
| `title` | заголовок роботи. Обов'язкове |
| `card` | короткий опис. Знадобиться, якщо додасте окрему головну |
| `tableau` | адреса графіка з адресного рядка Tableau Public |
| `spec` | ім'я файлу специфікації в теці `specs` |
| `before` | картинка «було» над графіком. Для розборів «до/після» |
| `steps` | кілька картинок-спроб перед графіком. Для розборів у кілька кроків |
| `wide: true` | графік на всю ширину сторінки. Для дашбордів |
| `height: 1150` | висота рамки в пікселях. Для дашбордів |

Кожна робота на сторінці згортається: читач може закрити зайве й
лишити тільки те, що хоче роздивитись. За замовчуванням усі роботи
розгорнуті. У бічній панелі є кнопка «Згорнути всі».

Текст під шапкою — звичайний Markdown. `**жирний**`, списки,
посилання працюють.

### Перед тим як вбудовувати графік Tableau

1. Відкрийте свій графік на Tableau Public.
2. Натисніть шестерню у верхньому правому куті.
3. Вимкніть **Show Sheets**.

Інакше поруч із графіком видно всі аркуші книги, зокрема чернетки.
У тому самому меню вимкніть **Allow Access**, якщо графік зроблено на
робочих даних.

### Дашборд ширший за графік

Дашборд вищий і ширший за окремий графік, тому в текстовій колонці
його обріже. Найпростіший шлях — виправити розмір у Tableau:

1. Відкрийте дашборд у Tableau.
2. У полі **Size** виберіть **Automatic**.

Якщо розмір змінити не можна, допишіть у шапку роботи два рядки:

```yaml
wide: true
height: 1150
```

Висоту підберіть на око. Якщо низ дашборда обрізаний, збільшуйте
число, поки дашборд не вміститься.

### Розбір «до / стало»

Найсильніша робота в портфоліо — не картинка, а хід думки. Покладіть
скріншот вихідного графіка в теку `specs` (або в будь-яку іншу) і
допишіть у шапку:

```yaml
before: "specs/vacancies-before.png"
```

Над графіком з'явиться картинка з підписом «Було», під нею — ваш
графік із підписом «Стало».

Якщо спроб було кілька, покажіть їх усі — так видно хід думки, а не
тільки результат:

```yaml
steps:
  - img: "specs/step1.png"
    label: "Спроба 1"
    note: "два ряди окремо"
  - img: "specs/step2.png"
    label: "Спроба 2"
    note: "подвійна вісь"
final_label: "Що вийшло"
```

Кожна спроба має пояснити, **чому** вона не підійшла. Тупик без
діагнозу — просто чернетка; тупик із діагнозом — доказ, що ви
розуміли, що робите.

У шаблоні є два готові розбори: «Скільки кандидатів на одну вакансію»
(`_works/01-candidates-per-vacancy.md`) і «Чи заробляємо ми на цьому
обороті» (`_works/02-margin-case.md`). Подивіться, як він
побудований, і напишіть свій за тією ж рамкою:

- **Питання** — на що читач хотів відповіді;
- **Що не працювало** — чому попередній графік не відповідав;
- **Рішення** — що ви зробили і чому саме так;
- **Що я відкинув** — варіант, який ви розглянули й не взяли. Один
  такий абзац доводить, що рішення було свідоме;
- **Що стало видно** — конкретна знахідка, з числом;
- **Що я б ще змінив** — те, що лишилось слабким. Робота, яка
  вдає завершеність, читається як навчальна вправа.

Один такий розбір у портфоліо коштує більше, ніж п'ять акуратних
графіків без пояснень.

---

## Як додати ще одну сторінку

Наприклад, `about.md` — про себе.

1. Натисніть **Add file → Create new file**. Ім'я — `about.md`.
2. Вставте текст:

   ```markdown
   ---
   heading: "Про мене"
   ---

   Аналітик у ритейлі. Тут коротко про досвід і контакти.
   ```

3. Натисніть **Commit changes**.

   Щоб вставити графік на такій сторінці, напишіть один рядок:

   ```liquid
   {% include viz.html tableau="https://public.tableau.com/app/profile/…/viz/Книга/Аркуш" %}
   ```

   або `{% include viz.html spec="specs/my-chart.json" %}`.

4. Відкрийте `_config.yml` і допишіть сторінку в список `nav`:

   ```yaml
   nav:
     - name: "Про мене"
       file: "about.html"
   ```

5. Натисніть **Commit changes**.

У полі `file` пишіть ім'я з `.html`, навіть якщо файл має `.md`.
Поки список `nav` порожній, у бічній панелі немає розділу сторінок.
Щойно ви додасте першу сторінку, поруч з'явиться і посилання
«Роботи» на головну.

---

## Якщо щось не показується

Спершу подивіться на вкладку **Actions** у своєму репозиторії.
Зелена галочка — сайт зібрано. Червоний хрестик — у якомусь файлі
помилка, і сайт лишився таким, яким був до неї.

| Що бачите | Що робити |
|---|---|
| Червоний хрестик в **Actions** | Відкрийте останній запис і прочитайте рядок з `Error:`. Найчастіше — лапки або відступ у шапці роботи |
| «Не вдалося прочитати адресу Tableau» | Відкрийте графік на Tableau Public і скопіюйте адресу з адресного рядка заново |
| У рамці англійське «Where's the viz?» | Адресу прочитано, графіка за нею немає. Ви перейменували, приховали або видалили книгу чи аркуш |
| «Файл … не знайдено» | Перевірте, що файл лежить у теці `specs`, а ім'я в полі `spec:` збігається |
| «Специфікація не читається як JSON» | Вставте специфікацію у Vega Editor. Він покаже, де зайва або пропущена кома |
| Дашборд обрізаний | Виберіть **Size → Automatic** у Tableau або допишіть `wide: true` і `height:` |
| Робота не з'явилась | Перевірте, що файл лежить у теці `_works` і має `.md` на кінці |
| Роботи стоять не в тому порядку | Вони йдуть за іменем файлу. Перейменуйте: `01-`, `02-`, `03-` |
| Сайт не оновився | Зачекайте хвилину й оновіть сторінку через `Ctrl`/`Cmd` + `Shift` + `R` |

### Якщо не виходить — спитайте ШІ

Скопіюйте текст нижче в ChatGPT, Claude або Gemini. Він описує, як
влаштований сайт, тому модель відповідатиме по суті, а не навмання.
Свою проблему допишіть у кінці.

```text
Допоможи розібратися з моїм сайтом-портфоліо. Відповідай українською,
покроково, і пам'ятай: я працюю тільки через сайт github.com у
браузері, без командного рядка і без програм на комп'ютері.

Як влаштований сайт:
- Це GitHub Pages з Jekyll. Репозиторій публічний, гілка main, тека
  публікації — корінь.
- Налаштування сайту в _config.yml: title, role, tagline, footer і
  список сторінок nav (у кожної name і file).
- Головна сторінка — index.md, вона показує всі роботи одразу.
  Розмітка одна: _layouts/default.html.
- Кожна робота портфоліо — окремий файл у теці _works/. У його шапці
  між --- стоять поля: title, card, а також tableau (адреса графіка
  Tableau Public) або spec (ім'я файлу в теці specs/). Необов'язкові
  поля: wide: true і height (число).
- Текст роботи під шапкою — звичайний Markdown.
- Кожна робота на сторінці — це <details class="work">, тобто її можна
  згорнути. Розгорнуті за замовчуванням.
- На вільній сторінці графік вставляється через {% include viz.html %}.
- Файли специфікацій Vega-Lite лежать у теці specs/.
- Оформлення в assets/style.css, вбудовування графіків — у
  assets/embed.js. Ці два файли я не змінюю.
- Сторінка сама збирає список робіт і бічну панель.

Що мені треба:
[опишіть, що ви робили, що очікували побачити і що побачили насправді]

Текст помилки з вкладки Actions, якщо він є:
[вставте сюди]
```

Якщо модель радить встановити Ruby, Jekyll, Node або запустити щось
у терміналі — скажіть їй, що ви працюєте тільки в браузері на
github.com, і попросіть інший шлях.

---

## Що в теці

| Файл або тека | Навіщо |
|---|---|
| `_config.yml` | ім'я, підпис, список сторінок |
| `_works/` | ваші роботи, по одному файлу на кожну |
| `specs/` | файли специфікацій Vega-Lite |
| `index.md` | сторінка з роботами. Її бачать першою |
| `_layouts/default.html` | спільна розмітка сторінок. Правити не треба |
| `assets/style.css` | оформлення. Кольори — у змінних на початку файлу |
| `assets/embed.js` | вбудовує графіки. Правити не треба |