Кому это · Обновлено 16 сентября 2026 · Автор: Евгений К.

Документация API в Markdown с подсветкой кода

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

Откуда эти цифры: страница замера с версиями движков и датами

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

Документация – это в первую очередь код, и именно эта часть у большинства клипперов приезжает битой. Забор выходит голым, без метки: в 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 Web 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.

Чего Clean Web Clipper не делает с документацией?

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

Как страница разбирается по шагам, описано на странице об устройстве извлечения.

Что он распознаёт и какие страницы снимает?

Какие языки он распознаёт? Те, что объявляет сама страница. Clean Web Clipper не угадывает язык по коду – он читает класс, оставленный подсветчиком сайта. Поэтому метка ровно настолько верна, насколько верна исходная страница, и отсутствует там, где страница её не дала.

Что со ссылками, горячей клавишей и сайтом целиком?

Что происходит с относительными ссылками внутри документации? Относительные ссылки достраиваются до абсолютных ещё до конвертации. Ссылка вида ../hooks/use-state превращается в полный адрес на исходный сайт, поэтому из заметки она открывается. Переписывать её под структуру вашего репозитория расширение не пытается – это ручная работа.