Кому це · Evgeny K.

Перенести документацію в Markdown без прибирання

Перенесення документації зазвичай означає конвертувати HTML, а потім довше вичищати те, що конвертер залишив. Саме навколо цього вичищання й побудовано Clean Web Clipper, і саме його перевірено: на 512 протестованих сторінках у видобутих статтях не лишилося жодного тега HTML.

Звідки ці числа: сторінка заміру з версіями рушіїв і датами

Прибирання після конвертації

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

Потім пошкодженими приїжджають саме ті частини, які були потрібні найбільше. Огорожі коду гублять мітку мови, тож нічого не підсвічується, і читач не відрізнить команду оболонки від тіла JSON. Таблиці зі списком у комірці розвалюються. Врізки стають осиротілими абзацами, де ніщо не позначає попередження. Це вже не робота для пошуку-заміни – це повторне читання кожної сторінки.

Чого ніхто не планує, так це аудиту згодом. Через шість тижнів хтось питає, чи був абзац на новому сайті в старій документації, чи його дописали під час перенесення, – і якщо сконвертовані файли не зберегли адреси, звідки прийшли, відповісти можна, лише знайшовши оригінал. А на сайті документації, який відтоді вимкнули, це означає не знайти нічого. Рядок source у кожному імпортованому файлі коштує один рядок і закриває питання, а рядок date показує, яку редакцію імпортовано.

Що переноситься чисто

• Заголовки, списки, таблиці, огорожі коду й виноски лягають у стандартний Markdown
• Огорожі зберігають мітку мови: на технічному корпусі – 73 зі 156, проти 20 і 0 у порівнюваних рушіїв
• Жодного вцілілого тега HTML у видобутих статтях на 512 протестованих сторінках
• Бічна навігація, перемикачі версій і колонки «На цій сторінці» зрізаються, а не конвертуються
• Врізки й попередження стають цитатами, бо стандартного синтаксису для них у Markdown немає
• Шаблон імені файлу й підтека тримають імпортований набір у порядку, поки він росте
• Кожен файл несе адресу, звідки прийшов, тож на рецензії імпортований абзац можна простежити до сторінки-джерела
• Виноски збираються до того, як очищувач зріже ідентифікатори елементів, від яких вони залежать, – саме від цього порядку залежить, чи вціліють посилання на примітки взагалі

## Автентифікація

Кожен запит підписується токеном із заголовка `Authorization`.

```http
POST /api/v1/auth/token
Content-Type: application/json
```

> Токен живе 60 хвилин. Після цього потрібен окремий запит на оновлення.

| Поле | Тип | Обов’язкове |
| --- | --- | --- |
| client_id | string | так |
| client_secret | string | так |

Як налаштувати під перенесення

Два налаштування, одна тека й одне робоче правило щодо комітів. Правило щодо комітів і робить можливою рецензію потім.

1. Створіть у репозиторії документації каталог import/, окремо від місця, де житимуть готові сторінки. Поки перенесення триває, сирі конвертації й відредаговані сторінки не повинні лежати в одній теці.
2. Клік правою по іконці розширення → Параметри. Наведіть теку збереження на import/ і виберіть дію кліку по іконці – «записати у теку». Тридцять сторінок – це тридцять натискань клавіш, а не ще й тридцять вікон.
3. Поставте шаблон імені {domain}-{title}. Імпорт із двох-трьох сайтів-джерел постійно натрапляє на однакові заголовки, і тільки домен не дає «Огляду» перетворитися на Огляд-3.
4. У розділі frontmatter увімкніть title, source і extraction. source відповість на питання аудиту через шість тижнів, а extraction покаже, які сторінки взято зі структурованих даних, а не з відмальованого.
5. Зображення лишіть посиланнями, а не пропускайте. Ці адреси ви однаково не збережете, але посилання – це опис: воно фіксує, що на сторінці була діаграма, і саме це знадобиться, коли плануватимете роботу з графікою.
6. Перш ніж зберігати сторінку з вкладками чи акордеонами, розкрийте їх. Розширення конвертує те, що відмалював браузер, а вкладки, чий вміст вставляють лише після кліку, до кліку в DOM немає.
7. Закомітьте сирий імпорт одним комітом, а переструктуруйте в наступних. Тоді кожна подальша різниця показуватиме ваші редакторські зміни, а не суміш ваших змін із конвертацією.

Налаштування для імпорту

Ці значення підібрано для набору файлів, який людина переглядатиме сторінку за сторінкою, а потім редагуватиме, – а не для теки, яку прочитають раз і забудуть.

## Встановлення

> **Увага:** оновлення одразу через дві мажорні версії не підтримується.

npm

```bash
npm install example-cli --save-dev
```

pnpm

```bash
pnpm add -D example-cli
```

Обидві вкладки були відмальовані в DOM, тож приїхали обидві, одна за одною.
Вкладка, яку малюють лише після кліку, не приїхала б.

Три перенесення

Тридцять сторінок документації постачальника

Довідник API партнера має жити у вашій документації. Ви зберігаєте тридцять сторінок в import/, по одному натисканню на кожну. Огорожі приїжджають із мітками: на технічному корпусі мітка мови вціліла в 73 огорожах зі 156 проти 20 і 0 у порівнюваних рушіїв, а ліва навігація, перемикач версій і віджет відгуків не приїжджають нікуди.

Редагувати доводиться прозу й структуру. Не доводиться – двісті рядків бічного меню на сторінку, які пряма конвертація HTML поклала б на початок кожного файлу. Саме через них перенесення й розтягуються на тижні.

Посібник, збудований із врізок

Посібник-джерело щедро користується врізками – попередженнями, примітками й порадами. У Markdown немає стандартного синтаксису ні для однієї з них, тож усі три стають цитатами: вміст виживає, різниця між типами – ні.

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

Порятунок перед вимкненням сайту

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

Зображення варто спланувати окремо. Вони лишаються посиланнями на сайт, який ось-ось перестане існувати, тож діаграми важливих сторінок доведеться зберегти вручну до дедлайну; посилання в імпортованих файлах і є переліком для цього.

Проти інших способів конвертації

Зазвичай перенесення поєднує два з цих способів. Чесне порівняння – не про те, чи буде ручна робота, а про те, де саме вона з’явиться.

Що доведеться виправити після імпорту

Чому всі врізки тепер виглядають однаково?

Попередження, примітки й поради стають цитатами, бо в Markdown немає стандартного синтаксису врізок, на який їх можна перенести. Текст цілий, а виділення на початку рядка зазвичай виживає, тож попередження, що починалося з жирного «Увага:», і далі так каже. Розставляння типів – прохід, який треба закласти; його обсяг покаже один grep по цитатах.

Чому сторінка прийшла без заголовка вгорі?

Порожні заголовки прибираються, а на багатьох сайтах документації видима назва сторінки взагалі не заголовок, а елемент навігації поза тілом статті. Назва однаково потрапляє у файл через поле frontmatter title, яке береться з метаданих самої сторінки. Підняти її до H1 – механічний крок, який можна прогнати скриптом по всьому імпорту.

Чому посилання на зображення досі ведуть на старий сайт?

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

Чому сторінка з jsonld-articlebody читається не так, як на сайті?

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

Чим воно не є

Це не інструмент перенесення: немає обходу сайту, переписування посилань, карти перенаправлень і завантаження графіки. Зображення лишаються посиланнями на початковий сайт, тож імпортований набір не самодостатній. Усе, чого Markdown не вміє виразити, – вкладки з кодом, включення, типи врізок, власні компоненти – сплющується до найближчого простого відповідника: вміст виживає, оформлення ні. І конвертується те, що сторінка відмалювала, тож текст у нерозкритому акордеоні в DOM відсутній і не зберігається.

Питання