Кому это

Документация с кодом, сохранившим язык

Clean Clipper читает язык на самой странице – из класса забора, из родительского элемента, из разметки, которую оставил подсветчик сайта, – и вписывает его в забор. На техническом корпусе из девяти страниц метка пережила клип в 73 заборах из 156, против 20 и 0 у двух сравниваемых движков. Остальная страница приходит обычным Markdown, без бокового меню.

Что ломается при копировании

Документация – это в первую очередь код, и именно эта часть у большинства клипперов приезжает битой. Забор выходит голым, без метки: в Obsidian он серый монолит, в репозитории проходит ревью без подсветки. Значит, надо открыть каждую заметку и дописать js, python или bash над каждым забором. На документации в тридцать страниц это вечер, потраченный на восстановление того, что на исходной странице уже было.

С остальным клипом не лучше. Переключатель версий, боковое меню и колонка «На этой странице» оказываются посреди текста, а таблица параметров схлопывается в одну строку, потому что в одной ячейке лежал пример кода. Через три месяца вы ищете в заметках нужную опцию API и сначала натыкаетесь на три копии меню. Заметка есть, а перечитать её нельзя.

У самих заборов кнопка «копировать» обычно есть, но отдаёт она ровно код и ничего кроме. Оговорка над примером, таблица параметров под ним и та единственная строчка про третий аргумент, ради которой вы страницу и открыли, остаются на сайте. Через месяц в заметке лежит вызов функции без единого слова объяснения, и собирать его обратно приходится тем же поиском, каким вы нашли страницу в первый раз.

Что меняется в заметке

• Забор выходит как ```js, а не голый – подсветка в Obsidian, VS Code и на GitHub работает сразу после вставки
• Язык читается со страницы – класс забора, родительский элемент, разметка подсветчика – и никогда не угадывается по коду
• Таблица параметров с кодом в ячейке сохраняет строки, а не схлопывается
• Ссылки-примечания становятся сносками [^1], определения собираются в конце файла
• Боковое меню, переключатель версий и колонка «На этой странице» срезаются, а не конвертируются
• Код в строке остаётся кодом в строке – в том числе внутри заголовков и ячеек
• Относительные ссылки достраиваются до абсолютных: ../hooks/use-state из заметки открывается, а не ведёт в никуда
• Написания языка приводятся к одному виду – javascript становится js, yml – yaml, а plaintext не пишется вовсе

## Шаг 1: разбейте интерфейс на компоненты

JSON API возвращает данные примерно такого вида:

```js
[
  { category: "Фрукты", price: "$1", stocked: true, name: "Яблоко" },
  { category: "Овощи", price: "$2", stocked: true, name: "Шпинат" }
]
```

| Хук | Что возвращает |
| --- | --- |
| `useState` | пару: значение и функцию-сеттер |
| `useEffect` | ничего; принимает функцию и список зависимостей |

Как склипать страницу документации

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

1. Закрепите иконку: нажмите кусочек пазла справа от адресной строки и щёлкните булавку у Clean Clipper. Иначе расширение придётся каждый раз искать в выпадающем списке, а из окна настроек до него два клика.
2. Откройте в настройках раздел «Клик по иконке» и выберите «Скопировать Markdown». После этого Alt+Shift+M кладёт страницу в буфер вообще без окна – ровно за то время, пока вы переключаетесь в редактор.
3. В разделе «Куда сохранять» впишите шаблон имени файла {domain}-{title} и подпапку docs. У справочников заголовки повторяются – «Установка», «Введение», «Быстрый старт» есть у каждого второго продукта, – и без домена в имени файлы через неделю не различить.
4. На странице документации раскройте ту вкладку примера, которая вам нужна: npm или yarn, JavaScript или TypeScript. Расширение читает DOM после отрисовки, поэтому в клип попадает открытая вкладка, а не все три сразу.
5. Нажмите иконку. Переключатель наверху окна говорит, взята вся страница или ваше выделение; если перед нажатием вы что-то выделили, окно откроется сразу на выделении.
6. Переключитесь на вид «Markdown» и посмотрите на первую строку каждого забора. Где страница объявила язык, стоит js или python. Голый забор означает, что класса на странице не было, – и это не сбой, а отказ угадывать.
7. Нажмите «Копировать» и вставьте Markdown в README, в описание пул-реквеста или в заметку проекта. Подсветка включается сразу: проходить по файлу и дописывать метки над заборами не придётся.

Настройки под работу с документацией

Набор, с которого стоит начать, если вы клипаете справочники и руководства, а не статьи. Ничего необратимого здесь нет: любую строчку можно поменять позже, а кнопка «Сбросить всё» возвращает исходное.

---
title: "useEffect – Справочник React"
source: "https://ru.react.dev/reference/react/useEffect"
extraction: "dom"
---

## Параметры

| Параметр | Тип | Описание |
| --- | --- | --- |
| `setup` | функция | Возвращает функцию очистки или ничего |
| `dependencies` | массив или ничего | Список реактивных значений; сравниваются через `Object.is` |

> Осторожно: без второго аргумента эффект выполняется после каждого рендера.

```
useEffect(setup, dependencies?)
```

Три сценария целиком

Разбор незнакомой библиотеки перед подключением

Вам предложили взять библиотеку, и к завтрашнему обсуждению нужны не впечатления, а аргументы. Вы проходите четыре страницы – обзор, установку, справочник по конфигурации и раздел про миграцию – и на каждой жмёте Alt+Shift+M, не открывая окно и не отрываясь от чтения.

В папке docs лежат четыре файла с именами вроде example.dev-Конфигурация.md. Таблица опций в них цела, заборы с метками, бокового меню нет. Один поиск по папке отвечает, поддерживает ли библиотека то, ради чего её и берут, – и в обсуждение уходит цитата с адресом источника, а не «я где-то читал».

Ответ коллеге в рабочем чате

В чате спрашивают, как правильно закрыть соединение в пуле. Вы знаете нужный раздел справочника, открываете его, выделяете абзац вместе с примером и жмёте Alt+Shift+M. Отрезать от выделения расширение ничего не станет: то, что человек выбрал сам, срезке навигации не подвергается.

В буфере – три абзаца и забор с меткой python. В чате это вставляется подсвеченным блоком, а не серой простынёй, и коллеге не приходится гадать, где кончается ваш комментарий и начинается цитата из документации. Адрес источника при вставке выделения не добавляется автоматически – если он нужен, берите его из окна клипа, где он лежит в свойствах.

Перенос чужого справочника в свой репозиторий

Внутренний сервис документирован на вики, которая закрывается, и двенадцать страниц надо перевезти в репозиторий. Вы один раз настраиваете папку на диске и шаблон имени, а дальше проходите оглавление сверху вниз, по странице за раз: краулера здесь нет, двенадцать страниц – это двенадцать нажатий.

На выходе двенадцать файлов .md с одинаковыми именами по схеме, с сохранёнными уровнями заголовков и таблицами параметров. Пустые заголовки, которые оставляют после себя навигационные блоки, удалены – оглавление в репозитории не обрастает разделами-призраками. Внутренние ссылки остались абсолютными и ведут на старую вики: их переписывание под структуру репозитория остаётся ручной работой.

Чем это заменяет привычные способы

Задачу «утащить кусок документации к себе» решают пятью способами, и у каждого своя цена. В последней строке цена нашего способа тоже названа, а не пропущена.

Когда вывод не такой

Почему у забора не проставился язык?

Потому что страница его не объявила. Расширение смотрит атрибуты data-lang, data-language, lang и data-code-language на самом code, на pre и на двух родителях выше, а потом классы вида language-*, lang-*, hljs-* и те, что оставляют подсветчики GitHub. Если ни одного из них нет, метки не будет: угадать язык по трём строчкам кода можно, но ошибка здесь обходится дороже пропуска.

Почему в клип попал пример не из той вкладки?

Потому что в клип попадает то, что отрисовано. Вкладки с примерами почти всегда переключаются скриптом, и в разметке страницы в каждый момент лежит одна из них. Раскройте нужную вкладку до нажатия – а если нужны обе, склипайте страницу дважды, переключив вкладку между клипами.

Почему на странице справочника написано, что статьи нет?

Так расширение отвечает, когда на странице не находится тела статьи или когда пятая часть текста и больше приходится на подписи ссылок. Обзорные страницы справочников – списки методов, указатели, страницы «Все компоненты» – как раз такие: они целиком состоят из ссылок.

Отдать вместо них простыню из трёхсот ссылок было бы хуже, чем сказать прямо. Выход простой: клипайте страницу самого метода, а не указатель. Выделение работает и здесь – на выделенный фрагмент этот отказ не распространяется вовсе.

Почему подсветка не включилась, хотя метка стоит?

Посмотрите, какая именно метка стоит. Расширение приводит написания к одному виду и знает около шестидесяти языков; javascript превращается в js, yml – в yaml. Незнакомое значение отбрасывается, а plaintext и none не пишутся вовсе – это и есть голый забор. Если метка на месте, но подсветки нет, дело в подсветчике вашего редактора: не всякая сборка знает, скажем, graphql или dockerfile.

Чего он не делает

Он не угадывает язык у забора, который страница не пометила: там, где сайт отдаёт код без класса, забор остаётся голым – и это сознательно, придуманная метка обходится дороже, чем её отсутствие. Он не обходит сайт документации целиком: одна страница за раз, та, что перед вами, без краулера и без пакетной обработки. Он не скачивает ни схемы, ни скриншоты – картинки остаются ссылками на исходный сайт. И на страницах, которые защищает браузер, вроде chrome:// и магазина расширений, он не запускается вовсе.

Вопросы