Кому це

Зберігати документацію API з цілим кодом

Довідник – це переважно код, і саме його більшість розширень губить дорогою. Clean Clipper зчитує мову з розмітки самої сторінки – з класу огорожі, з батьківського елемента або з розмітки підсвічувача – і записує її в блок. Вставлений фрагмент підсвічується в Obsidian, VS Code і на GitHub без жодної правки руками.

Що ламається на документації

Ви зберігаєте сторінку довідника, відкриваєте нотатку – і бачите сірі прямокутники замість коду. Огорожа стоїть, але вона гола: мітки мови немає, тож підсвічування не вмикається ні в редакторі, ні на GitHub. Приклад із кількома файлами злипається в один блок, а решітка коментаря посеред нього перетворюється на заголовок Markdown.

Друга половина болю – таблиці параметрів. У комірці «Тип» лежить Array<string>, у комірці «Опис» – список із двох пунктів, і універсальний конвертер розриває на цьому рядок. Далі приїжджають бічна навігація на сорок посилань, перемикач версій і банер про cookie. Довести таку нотатку руками довше, ніж прочитати саму сторінку.

Третій шар – сторінка живе недовго. Довідник переїжджає на наступну мажорну версію, і адреса, за якою ви писали код, віддає перенаправлення в розділ, де вашого прапорця вже немає. Внутрішня вікі за SSO зникає ще тихіше – простір закривають разом із проєктом. Закладка в обох випадках веде в порожнечу, а пошук по теці з нотатками – ні: розширення читає вже відмальовану сторінку вашої сесії і не робить жодного мережевого запиту.

Що змінюється в нотатці

• Блок виходить як ```js, а не голий – підсвічування в Obsidian, VS Code і на GitHub працює одразу після вставляння
• Мову беруть із розмітки сторінки: клас огорожі, батьківський елемент, сліди підсвічувача – розширення не вгадує її з самого коду
• На технічному корпусі мітка мови вціліла в 73 блоках зі 156 – проти 20 і 0 у двох порівнюваних рушіїв
• Таблиці параметрів серіалізує саме розширення: комірка зі списком або кодом більше не розриває рядок
• Бічна навігація, хлібні крихти й перемикач версій зрізаються, а не конвертуються
• Посилання-примітки стають виносками [^1] з визначеннями в кінці нотатки

Метод `map` створює новий масив із результатів виклику функції для кожного елемента:

```js
let names = ["Богдан", "Петро", "Марія"];
let lengths = names.map(item => item.length);
alert(lengths); // 6,5,5
```

## Перебір: forEach

Як налаштувати під довідник

Один раз хвилин на шість – далі все робить скорочення на клавіатурі. Початкові значення розраховані на читання статей; довідник хоче іншого імені файлу, без поля автора й без картинок.

1. Установіть розширення й закріпіть іконку на панелі. Клік правою по іконці → Параметри: налаштування відкриються окремою вкладкою.
2. Виберіть дію кліку по іконці – «записати у теку». Саме це перетворює збереження на одне натискання без вікна: вікно перегляду корисне, поки ви призвичаюєтеся, і заважає потім.
3. Вкажіть теку. Наведіть її на каталог, який уже під контролем версій, – наприклад docs/clips у репозиторії, з яким працюєте. Браузер запитає підтвердження один раз і запам’ятає дозвіл для цього профілю.
4. Поставте шаблон імені {domain}-{title}. Сторінка «Початок роботи» є в чотирьох фреймворків одразу, і без домену в імені четверта тихо стане Початок-роботи-4.
5. У розділі frontmatter лишіть source і extraction, а author вимкніть. Довідник рідко підписаний, і порожнє поле в кожному файлі – шум, який ви однаково зрізатимете.
6. Зображенням поставте «пропускати». Знімок чужого редактора не шукається пошуком по тексту, а посилання веде на CDN, який переїде.
7. Відкрийте chrome://extensions/shortcuts і перевірте, що Alt+Shift+M за вами. Якщо скорочення забрало інше розширення – тут його й повертають.

Готові налаштування розробнику

Це ті значення, які варто змінити з початкових. Третя колонка пояснює причину саме для довідника, а не для читання взагалі.

Перед запуском сервера виконайте міграцію:

```
./bin/migrate --env production
```

```sql
SELECT id, created_at FROM sessions WHERE expires_at < now();
```

Друга огорожа мала `class="language-sql"`. Перша не мала нічого –
і лишилася голою, а не позначеною навмання.

Три робочі сесії

Зафіксувати ту версію, під яку писали

Ви на гілці v4 у довіднику фреймворка, читаєте сторінку про прапорець конфігурації, який у v5 перейменували. Натискаєте Alt+Shift+M. Файл лягає як example-dev-configuration-reference.md у docs/clips, source вказує на адресу з /v4/, а в шапці стоїть дата, яку оголосила сама сторінка.

За вісім місяців прапорець поводиться інакше, і ніхто не пам’ятає, чому його виставили. Нотатка лежить у репозиторії, в тому ж діапазоні комітів, що й зміна, і каже, за якою редакцією довідника ухвалили рішення. Жива адреса тим часом віддає v6, де цього прапорця немає взагалі.

Гілка форуму, яка справді допомогла

Офіційний довідник описує щасливий шлях, а розв’язок вашого випадку – у гілці на форумі, четвертим коментарем углиб, де прийнята відповідь має 140 балів під помилковою на 30. Ви зберігаєте гілку. Правило за сайтом відправляє її в threads, а структура коментарів переїжджає вкладеними цитатами, і бал лишається біля кожного.

Саме бал і важить, коли ви це перечитуєте. Просте копіювання гілки в буфер губить порядок повністю – і ви заново читаєте п’ять думок, не маючи чим відрізнити ту, з якою погодилася спільнота.

Таблиця змінних – просто в опис pull request

У посібнику з розгортання таблиця на вісімнадцять змінних оточення, у трьох комірках – приклад коду. Ви виділяєте таблицю на сторінці, зберігаєте виділене й вставляєте Markdown в опис pull request. GitHub малює її таблицею, бо це таблиця GFM, а не знімок екрана.

На технічному корпусі з п’ятнадцяти таблиць цей серіалізатор зберіг дванадцять там, де кожен із порівнюваних рушіїв зберіг сім. Ламають універсальні конвертери саме такі комірки – зі списком або кодом усередині.

Проти звичних способів

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

Коли вийшло не те

Чому огорожа без мітки мови?

Бо сторінка не сказала, яка це мова. Clean Clipper читає мову з класу, що його лишив підсвічувач самого сайту, і не вгадує її з коду. Приклад, підсвічений вручну без класу, дає голу огорожу – і це чесний результат. Вгадане python над фрагментом для оболонки гірше за відсутність мітки: підсвічування тоді впевнено розфарбовує не те.

Чому половини посібника немає?

Майже завжди винні вкладки або акордеон. Розширення перетворює те, що браузер справді відмалював, а вміст вкладки, який вставляють лише після кліку, до кліку в DOM не існує. Розкрийте вкладку й розділ, тоді зберігайте – або збережіть по разу на кожен варіант. Там, де сайт малює всі вкладки одразу й ховає їх засобами CSS, приїжджають усі, одна за одною.

Чому воно каже, що статті немає?

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

Що означає extraction: "jsonld-articlebody" у моєму файлі?

Що сторінка віддала текст статті у структурованих даних, але так і не домалювала його в DOM, тож тіло взяли звідти. Це записано, а не приховано, бо два шляхи можуть розходитися: копія зі структурованих даних інколи є ранішим чернетковим варіантом, а інколи – єдиною повною. Побачивши це значення, варто зазирнути в оригінал, перш ніж спиратися на текст.

Чого воно не робить

Розширення не обходить сайт: зберігається та сторінка, на якій ви стоїте, а не весь довідник. Мову воно не вгадує – якщо сторінка ніде її не оголосила, огорожа лишиться голою. Діаграми й знімки екрана не завантажуються: зображення лишаються посиланнями на початковий сайт. Інтерактивна пісочниця збережеться тим, що видно в DOM у момент кліку, – станом редактора, а не самим застосунком.

Питання