Тема 5, урок 2 з 2. Другий і останній підхід до бази знань продукту
На минулому уроці ти зробив вісім атомарних нотаток із front-matter і поклав
їх у ~/www/kb/. Формально база є. Практично — це вісім окремих
текстів, які нічого одне про одного не знають. Відкрий будь-який із них і спробуй
відповісти: що ще в моїй базі стосується цієї думки? Зараз відповідь дає
тільки твоя памʼять, а вона стирається за два тижні.
Сьогодні ти робиш три речі. Звʼязуєш нотатки одну з одною —
для цього досить написати назву сусідньої нотатки у подвійних дужках:
[[назва]]. Складаєш карту: файл kb/index.md,
з якого починають читати базу. Публікуєш — перетворюєш
.md на звичайні сторінки сайту. Після цього база знань
відкривається з твого сабдомену, як і решта проєкту.
kb/index.md — сторінку, з якої видно всю базу
за пів хвилини;.md на сторінки сайту й відкривати їх
за адресою 91.219.61.4/s/<логін>/kb/;| Етап | Хв | Що робимо |
|---|---|---|
| Вхідний зріз | 10 | Граф класу: у кого скільки сиріт і битих лінків |
| Зв'язність і сироти | 15 | Чому нотатка без вхідних посилань фактично не існує |
| Вікі-зв'язки | 30 | Розставляємо ≥12 посилань [[…]], доводимо биті лінки до 0 |
| MOC і гігієна бази | 15 | Що таке карта змісту і чим вона краща за пошук навмання |
kb/index.md | 20 | Пишемо карту змісту зі 100% покриттям нотаток |
| Генерація і публікація | 20 | mdbuild → index.html і сторінки нотаток, перевірка з сабдомену |
| Автоперевірка й підсумок | 10 | check11 5 повністю |
| Разом | 120 |
Слова «вікі-посилання», «граф» і MOC поки нічого не означають — розберемо кожне тоді, коли воно знадобиться.
| Було після уроку 7 | Стане після уроку 8 |
|---|---|
8 файлів .md у теці | граф із ≥ 12 звʼязків, у якому видно структуру дослідження |
| знайти нотатку можна пошуком, якщо памʼятаєш слово | у кожну нотатку веде хоча б один вхід — випадкових знахідок більше нема |
| теки немає точки входу | kb/index.md — карта змісту з розділами, а не список файлів |
| файли читає тільки Obsidian у тебе на компʼютері | http://91.219.61.4/s/<логін>/kb/ відкриває будь-хто, кому ти даси посилання |
.md і згенеровані
.html. Жодних скриншотів графа: граф ти показуєш очно на своєму
екрані, а на сервері живуть сторінки.На цій сторінці дві майстерні, які можна покрутити руками.
У першій ти тягнеш звʼязок між нотатками й одразу бачиш, який рядок і в який
файл дописати. У другій вставляєш свої .md і отримуєш готовий
код kb/index.html.
Одна нотатка може належати трьом темам одразу. Файл — одній теці
Тека — це фізичне місце. Файл лежить у ній, і більше ніде. Поки нотаток
десять, це не болить. Але нотатка pricing-idea.md — «гіпотеза ціни» —
чесно стосується ринку (ціни конкурентів), економіки (маржа)
і користувачів (скільки вони готові платити). Куди її класти?
Хоч би що ти обрав, ти обираєш за себе майбутнього. Через місяць ти шукатимеш цю нотатку в іншій теці — бо тоді думатимеш про неї з іншого боку. Копіювати файл у три теки ще гірше: три копії розʼїдуться, і жодна не буде правдою.
Синтаксис прийшов із вікі-рушіїв і живе в Obsidian, Logseq, Foam, Quartz та інших інструментах. У Obsidian це формат за замовчуванням саме тому, що він коротший за звичайне посилання Markdown.
| Пишеш | Що це значить |
|---|---|
[[competitors]] | посилання на файл competitors.md у тій самій базі; підпис — сама назва |
[[competitors|три прямі конкуренти]] | той самий файл, але в тексті видно людський підпис після вертикальної риски |
[[competitors#Ціни]] | посилання на конкретний заголовок усередині нотатки |
[Конкуренти](competitors.md) | те саме звичайним Markdown — довше, але зрозуміле будь-якому інструменту |
Всередині квадратних дужок — імʼя файлу без розширення, а не заголовок
із front-matter. Це головне джерело битих посилань: заголовок у тебе українською
(«Конкуренти»), а файл названий за правилом уроку 7 — competitors.md,
латиницею в kebab-case.
[[Competitors]]
і [[competitors]] — два різні файли, і один із них не існує.
На твоєму Windows-ноутбуці обидва варіанти можуть «працювати» в Obsidian,
а після заливки на сервер сторінка віддасть 404. Пиши так само, як зветься
файл: малими, латиницею, через дефіс.Нотатка «гіпотеза ціни» чесно стосується конкурентів, юніт-економіки й аудиторії. У теках ти маєш покласти файл кудись один. Що буде далі?
У нотатці ти написав [[Конкуренти]], бо саме так називається
нотатка в заголовку. Файл при цьому зветься competitors.md.
Ти впевнений, що звʼязок є. Що сталося насправді?
Пряме посилання ти ставиш сам. Зворотне зʼявляється саме — і саме воно рятує
Коли в нотатці pricing-idea.md ти написав [[competitors]],
ти зробив пряме посилання: із ціни на конкурентів. Але програма при цьому
безкоштовно робить друге — зворотне: тепер у нотатці
competitors.md видно, що на неї послалася нотатка про ціну. Ти цього
рядка не писав. Він порахований із твоєї бази.
| Пряме посилання | Зворотне посилання | |
|---|---|---|
| Хто створює | ти, руками, у момент письма | програма, автоматично, з усієї бази |
| Що показує | куди ти свідомо послався | звідки на цю думку послалися — зокрема те, про що ти забув |
| Коли корисне | коли читаєш нотатку послідовно | коли збираєшся щось у ній змінити |
| Чи можна помилитися | так: помилка в назві дає битий лінк | ні: воно похідне від прямих, окремо не ламається |
Практичне правило: перш ніж міняти число в нотатці — подивись, хто на неї
посилається. Змінив обсяг ринку в market-size.md — панель
зворотних посилань покаже, що на нього спираються pricing-idea
і index. Саме ці два файли доведеться перечитати. Без панелі ти
дізнаєшся про це на Demo Day, коли журі спитає, чому в двох місцях різні цифри.
Ідея не нова: у Вікіпедії те саме зветься «Посилання сюди» (What links here) і є в кожної статті. Obsidian, Logseq і Roam зробили цю панель постійно видимою збоку — і саме через неї нотатки перестали бути окремими файлами.
Ти зібрався виправити обсяг ринку в market-size.md — знайшов
свіжіші дані. Перш ніж міняти число, треба знати, які твої висновки на нього
спираються. Куди дивишся?
Тягнеш звʼязок — сторінка каже, який рядок і в який файл дописати
Нижче — демонстраційна база з девʼяти вузлів: карта index
і вісім нотаток. Стан навмисно хворий: шість звʼязків, пʼять сиріт і один битий
лінк. Твоє завдання — довести граф до здорового: ≥ 12 звʼязків, 0 битих,
0 сиріт, карта покриває 100 %. Рівно ті самі числа перевіряє
check11 5 у твоїй справжній базі.
Перетягни від одного вузла до іншого, щоб додати звʼязок. Клацни по вузлу — побачиш його прямі й зворотні посилання. Червоні вузли, що пульсують, — сироти.
Коли граф стане здоровим, тут зʼявиться
чернетка kb/index.md, зібрана з поточних звʼязків і тегів —
її можна взяти за основу своєї карти.
.md. Перевірка на сервері
читає файли, а не цю сторінку.Ти написав нотатку про ризик проєкту й за місяць про неї забув. На неї не
посилається жоден файл, у index.md її немає. Що це означає
практично?
Пошук працює, коли ти знаєш слово. Карта потрібна, коли не знаєш
Уяви нотатку, у якій немає жодного власного дослідження. Вона тільки збирає тему: усередині розділи, а в розділах — посилання на інші нотатки. Біля кожного посилання один рядок про те, навіщо туди йти.
Таку нотатку називають картою змісту, англійською map of content, скорочено MOC. Термін популяризував Нік Міло у підході Linking Your Thinking. Сама ідея старша: так само влаштовані оглядові статті у Вікіпедії.
Чим це краще за просте «зміст»? Зміст перелічує, що є. Карта показує, як воно повʼязане і з чого починати. Різниця стає видимою на двадцятій нотатці. Плоский список із двадцяти рядків не читається взагалі. А карта з чотирьох розділів по пʼять читається за пів хвилини.
kb/index.md--- title: База знань продукту tags: [moc, індекс] date: 2026-09-22 --- # База знань «TrackIt» Карта дослідження. Кожен розділ — питання, на яке ми шукали відповідь. ## Кому і навіщо - [[problem-statement]] — яку саме проблему беремо, одним абзацом - [[target-audience]] — хто наш користувач і чим він зайнятий зараз ## Ринок і гроші - [[competitors]] — три прямі конкуренти й де вони слабкі - [[market-size]] — обсяг ринку, числа з `data/market.csv` - [[pricing-idea]] — гіпотеза ціни й чому саме 149 грн ## Продукт - [[feature-reminders]] — ідея нагадувань, найдорожча за розробкою ## Ризики й джерела - [[risk-churn]] — користувачі йдуть після першого тижня - [[source-dou-survey]] — звідки взяті цифри про аудиторію
Зверни увагу на три речі. Розділи названі питаннями теми, а не типами файлів. Після кожного посилання — рядок про те, навіщо ця нотатка. І посилань рівно стільки, скільки нотаток у базі: карта покриває 100 %, інакше частина бази лишається за межами будь-якого маршруту.
[[index]]), у неї є front-matter,
вона потрапляє в граф. Коли база виросте, MOC-ів стане кілька: карта ринку,
карта продукту — і одна головна карта, що посилається на них. Для восьми нотаток
вистачить однієї.У базі 24 нотатки. Ти зробив index.md — плоский список із
24 рядків в алфавітному порядку. Однокласник каже, що це не MOC.
Чому він правий?
Ти повертаєшся до проєкту після двох тижнів канікул і не памʼятаєш, що взагалі встиг дослідити. Пошук по базі тут майже не допомагає. Чому?
Усі три не видно в теці з файлами. Усі три видно в графі
| Метрика | Норма | Що означає провал |
|---|---|---|
| Сироти — нотатки без вхідних посилань | 0 | частина бази недосяжна маршрутом: до неї не дійти ані з карти, ані з іншої нотатки |
| Глухі кути — нотатки без вихідних посилань | рідко | думка ні на що не спирається; часто це знак, що нотатку не дочитали й не додумали |
| Биті посилання | 0 | помилка в назві файлу; на сайті це прямий 404 у публічній базі знань |
| Покриття картою | 100 % | у index.md згадані не всі нотатки — решта живе поза будь-яким маршрутом |
| Розподіл тегів | ≥ 4 теги, жоден > 60 % | тег, що стоїть на всьому, нічого не фільтрує — це той самий шум, що й звалище |
Як помітити хвороби без графа? Три команди в SSH-сесії роблять те саме. Перша рахує всі вікі-посилання в базі:
Друга шукає биті: бере ціль кожного посилання й перевіряє, чи існує такий файл. Третя шукає сиріт: для кожного файлу дивиться, чи згадує його хоч хтось інший.
# биті: ціль посилання, для якої немає файлу cd ~/www/kb grep -oh '\[\[[^]|#]*' *.md | sed 's/^\[\[//' | sort -u | while read n; do test -f "$n.md" || echo "БИТЕ: [[$n]]" done # сироти: файл, на який не посилається жоден інший файл for f in *.md; do n=${f%.md} c=$(grep -l "\[\[$n" *.md | grep -cv "^$f$") test "$c" -gt 0 || echo "СИРОТА: $f" done
Обидва фрагменти — для шелла на сервері (bash). У PowerShell на
твоєму ноутбуці вони не запрацюють: там інший синтаксис циклів і немає
grep. Тому запускай їх у SSH-сесії, а не в локальному терміналі.
Щоб швидко закрити перевірку, учень поставив у кожній нотатці посилання на всі інші. Сиріт немає, битих немає, посилань 56. Що з цим не так?
Учитель просить показати шлях від index.md до будь-якої
нотатки за два кліки. У тебе до source-dou-survey виходить
за чотири. Про що це говорить?
.md зробити сторінки сайтуГенератор статичного сайту: один прохід — і замість файлів у тебе сторінки
Браузер не вміє читати Markdown. Якщо покласти competitors.md
у ~/www/kb/ і відкрити його за посиланням, побачиш сирий текст із
дужками й дефісами — або взагалі діалог «зберегти файл». Між нотатками
й сайтом потрібен перетворювач.
Клас інструментів, що це роблять, зветься генератори статичного сайту
(static site generator, SSG). Найвідоміші — Jekyll, Hugo, Eleventy, MkDocs,
Quartz. Усі вони роблять по суті одне: беруть теку з текстовими файлами
й шаблон, а віддають теку з готовими .html.
mdbuild на сервері. Змінюються шаблони й швидкість —
ідея та сама.Статичний сайт із .md | Сайт із базою даних (CMS) | |
|---|---|---|
| Коли будується сторінка | один раз, після зміни файлів | щоразу, коли хтось відкриває |
| Що лежить на сервері | готові .html, .css | код, база даних, середовище виконання |
| Що ламається | практично нічого: файли не мають логіки | оновлення, доступ до бази, вразливості коду |
| Джерело правди | твої .md — можна відкрити хоч у «Блокноті» через 10 років | рядки в базі; без цієї CMS вони мало що варті |
| Ціна помилки в назві файлу | битий лінк видно одразу, на збірці | помилка виявиться в браузері користувача |
На сервері збірку робить утиліта mdbuild. Вона робить рівно
те, що на схемі. А ще друкує попередження про биті посилання. Тому її вивід
варто прочитати, а не прогорнути.
Вивід ілюстративний: у тебе будуть свої імена й свої попередження. Але формат саме такий — спершу попередження, потім результат. «Готово» наприкінці не означає, що все добре: збірка завершується навіть із битими посиланнями, просто сторінка потім віддає 404.
Публічна база знань — це не «ще одна сторінка». Це відповідь на питання,
яке журі й перші користувачі ставлять завжди: звідки ви це взяли?
Поклади поруч із лендингом теку /kb/. У ній видно джерела цифр,
перелічені ризики й записано, чому ціна саме така. Після цього продукт
перестає бути презентацією й стає роботою, яку можна перевірити.
Це працює і в дорослих продуктах: розділи «Docs», «Handbook», «Changelog», «Engineering blog» існують не для краси. Вони показують, що всередині є думка, і знімають половину питань ще до розмови.
Ти виправив одну нотатку й хочеш, щоб сайт бази оновився. Що робить генератор статичного сайту — і чого він не робить?
На Demo Day журі відкриває твій лендинг і бачить посилання «База знань».
Навіщо взагалі публікувати kb на сайті продукту, а не тримати
її в Obsidian у себе на ноутбуці?
Вставляєш свої .md — отримуєш готовий код kb/index.html
Нижче — той самий конвеєр, тільки в браузері. Він читає front-matter,
перетворює вікі-посилання на HTML-лінки, групує нотатки за тегами, перевіряє
биті посилання й віддає готовий код. Формат вводу: перед кожним файлом рядок
=== імʼя-файлу.md ===, далі — вміст файлу як є.
kb/index.html у кодуванні UTF-8
і залий по SFTP у ~/www/kb/. Або, якщо працюєш у SSH-сесії,
просто запусти mdbuild ~/www/kb — результат буде той самий,
тільки ще й сторінки окремих нотаток згенеруються. Ця майстерня потрібна,
щоб ти побачив, що саме робить генератор, а не сприймав його як
чорну скриньку.index.html у Windows-1251 або в UTF-16, кирилиця
в браузері перетвориться на «кракозябри». У PowerShell це класична пастка:
… > index.html пише UTF-16. Зберігай редактором у UTF-8
або пиши
[IO.File]::WriteAllText($p,$t,(New-Object Text.UTF8Encoding $false)).Генератор зібрав index.html, але одна нотатка потрапила
в розділ «без тегу», хоча ти теги їй ставив. Де шукати причину?
Коротко, але це найдорожчий блок уроку
Тека ~/www/kb/ публічна. Усе, що туди потрапило, віддається
будь-кому, хто знає адресу, — а адресу знає той, кому ти надіслав посилання
на Demo Day. Перед заливкою база проходить через фільтр із трьох питань.
| Не публікуємо | Чому | Що робимо натомість |
|---|---|---|
| Чернетки інтервʼю з іменами, телефонами, місцем роботи респондентів | це персональні дані інших людей; вони погоджувалися на розмову, а не на публікацію | у kb/ лишається знеособлений висновок: «троє з пʼятьох згадали X»; сирі записи — у ~/notes/ |
| Внутрішні домовленості: хто кому винен, оцінки однокласників, суперечки | це не інформація про продукт, і читати її буде хтось, кого ти не мав на увазі | тримати поза kb/; у базі — рішення, а не хід сварки |
| Ключі, токени, паролі, рядки підключення, адреси службових панелей | публічний файл індексується й читається ботами за хвилини; ключ у файлі — це вже витік | виносиш у ~/notes/ і міняєш ключ — старий вважай скомпрометованим |
| Чужі тексти й зображення, скопійовані цілком | публікація чужого без дозволу — вже не «нотатка для себе» | цитата на 2–3 речення + посилання на джерело у front-matter |
~/www/kb/ не витирає його з кеша пошуковика,
зі скриншотів і з чиєїсь відкритої вкладки. Тому єдина надійна дія з
оприлюдненим паролем — змінити пароль, а не видалити файл. Для
масштабу: за даними GitGuardian, лише за 2025 рік у публічних комітах на
GitHub зʼявилося понад 28 мільйонів захардкоджених секретів. І це люди,
які добре знають, що так робити не можна.У чернетці interview-2.md є імʼя, телефон і місце роботи
людини, яку ти опитував, а в deploy.md — пароль до FTP.
Ти збираєшся залити kb/ у ~/www/kb/. Що робиш?
Виконуй по черзі. Галочки зберігаються — сторінку можна закрити.
[[…]] і kb/index.md ти пишеш у себе на
компʼютері — у редакторі або в Obsidian, зберігаючи файли в UTF-8.
По SFTP у ~/upload/ → ~/www/kb/ їдуть тільки оновлені
.md та index.html. Збірку mdbuild
запускаєш уже в SSH-сесії. Скриншоти графа на сервер не завантажуються —
граф учитель дивиться очно на твоєму екрані.Обидві команди набирають у вікні сервера, тобто
в SSH-сесії. У PowerShell на твоєму ноутбуці вони не спрацюють: там немає
ані grep, ані mdbuild. І &&
між командами PowerShell теж не розуміє.
check11 5Система прочитає твої .md, побудує граф і зробить
реальний запит на /kb/. Спроби не обмежені.
Демонстраційний режим: результат згенеровано для показу.
На сервері ця кнопка запускає check11 5 від імені учня
і читає ~/.progress/11-5.json.
no_secrets і no_media блокують оцінку. Перший — тому
що публічна тека з чужими персональними даними чи ключем це не «недоробка»,
а шкода іншій людині. Другий діє наскрізно весь модуль. У ~/www/
і ~/upload/ не має бути відео й звуку: .mp4 .mov .avi .mkv
.webm .mp3 .wav .flac. Файлів понад 2 МБ там теж бути не повинно.
На уроці 14 check11 8 прожене все це повторно.index.md до будь-якої названої вчителем нотатки
за два кліки;~/notes/: що саме ти не поклав у публічну
базу і чому.Це те, що бачить учитель, коли виставляє оцінку.
| Складник | Вага | Результат |
|---|
data/market.csv і юніт-економіка з analytics.html.
Кожна з валідним front-matter і назвою в kebab-case.kb/index.md. Сиріт після цього бути не повинно.mdbuild ~/www/kb) і перевір, що всі
посилання на /kb/ відкриваються — 0 битих.CHANGELOG.md один рядок: скільки звʼязків стало
і яку хворобу бази ти в себе знайшов.feature-*.md, підуть на дошку й згрупуються в кластери.
З них вийде машинозчитуваний файл tasks.json — беклог запуску
твого продукту.Усе, що на цій сторінці подано як факт, має посилання. Перевіряти дозволено й корисно.
[[назва]], підпис через |,
посилання на заголовок через #; формат за замовчуванням —
офіційна довідка.
help.obsidian.md · Internal links.md + шаблон → готові
.html, без бази даних під час перегляду — документація
трьох типових інструментів.
jekyllrb.com,
gohugo.io,
11ty.dev[[…]], зворотні посилання й граф —
quartz.jzhao.xyz,
help.obsidian.md · Publish,
mkdocs.org[[Competitors]] і [[competitors]] це різні цілі —
FHS 3.0,
path_resolution(7)Числа у виводі mdbuild, назви демонстраційних
нотаток і вміст графа на цій сторінці складені як типові для навчальної
бази. У твоєму ~/www/kb/ вони будуть свої. Утиліта mdbuild —
навчальна обгортка над тим самим конвеєром, що описаний у документації
генераторів вище. Повний список джерел із поясненнями —
у файлі urok-08-джерела.md поруч із цією сторінкою.