Перевірка посилань

На сайті посилання перевіряються за допомогою Lychee із збереженим у системі контролю версій кешем результатів зовнішніх посилань (див. Кеш посилань).

Перевірка посилань

Щоб перевірити посилання локально, виконайте:

npm run check:links

Типові команди

Скрипти check:links і check:links:internal виконуються на збірці BUILD_KIND; check:links:diff перевіряє файли з наявної збірки public/. Докладніше дивіться в Типи збірки: повна та скорочена.

Конфігурація

Lychee виконується на зібраному сайті (public/) з використанням згенерованого (та проігнорованого в git) файлу lychee.toml. Скрипт generate:config:links створює його з lychee.base.toml плюс блоку exclude_path, обчисленого з front matter сторінок, який має два джерела:

• link_check_exclude_path — список регулярних виразів шляхів відносно сайту для сторінок, які перевірка посилань має пропустити, наприклад, пагінацію блогу та старі дописи; див. content/en/blog/_index.md. Почніть шаблон з ^(../)?, щоб він охоплював усі локалі: необовʼязковий ../ відповідає дволітерному сегменту шляху локалі, такому як ja/.
• drifted_from_default — локалізовані сторінки з відмінностями, статус true (змінено відповідник EN) або file not found (відповідник EN видалено). Посилання з такої сторінки не перевіряються, оскільки вони можуть бути застарілими, але сторінка залишається дійсним цільовим посиланням: вхідні посилання з синхронізованих сторінок, включно з фрагментами, все ще перевіряються.

Збережені статуси відхилення актуальні лише настільки, наскільки свіжа остання нічна синхронізація статусів Housekeeping (як обʼєднана, тому вік може перевищувати день), тому генератор також пропускає сторінки з очікуваним відхиленням: локалізовані копії англійських сторінок, змінених (або видалених) після базового рівня статусу відхилення — коміту головної гілки, записаного в data/l10n-drift.yaml при загальній синхронізації статусів (npm run fix:i18n). Копія, яка сама змінилася після базового рівня, залишається перевіреною: хтось працює над нею. Генерація конфігурації завершується помилкою, якщо базовий рівень відсутній або не може бути знайдено; у CI завдання CHECK LINKS спочатку поглиблює поверхневий клон до базового коміту; локально отримайте відсутню історію (git fetch upstream main) або перевизначить базовий рівень: DRIFT_BASELINE=HEAD npm run check:links очищає накладання (пропуски за збереженим статусом все ще діють).

Локальна загальна синхронізація статусів (npm run fix:i18n) може перезаписати data/l10n-drift.yaml; залиште цей перезапис незафіксованим — локально записаного коміту може не існувати у вихідному репозиторії.

Link cache

Результати перевірки зовнішніх посилань кешуються у файлі .lycheecache, який знаходиться під контролем версій, тому перевірки завантажують лише ті URL, які є новими або термін дії кеш-записів яких закінчився. Lychee кешує лише успішні результати, тому невдалі спроби повторюються при кожному запуску.

Оскільки кеш регулярно оновлюється за допомогою кількох запланованих робочих процесів, а також PR-ів із змінами вмісту, паралельні оновлення обʼєднуються порядково за допомогою стратегії Git union (див. .gitattributes), а не позначаються як конфлікти. Такі обʼєднання можуть залишати дубльовані або застарілі записи; вони нешкідливі для перевірки, а наступний запуск перевірки посилань перепише кеш чистим. У PR зафіксуйте таке переписування.

Якщо ви додаєте або змінюєте зовнішні посилання, запустіть npm run check:links перед надсиланням PR, збірка сайту займає більшу частину часу, та зафіксуйте оновлений .lycheecache разом із змінами вмісту. Інакше перевірка CACHE updates committed? зазнає невдачі; для відновлення дивіться CACHE updates committed?.

Робочі процеси оновлення кешу та обслуговування

Наступні робочі процеси виконуються щоденно та запускають команду перевірки посилань:

Оновлення refcache спочатку очищає найстаріші записи кешу (кількість є вхідним параметром робочого процесу) і повторно запускає перевірку посилань, яка оновлює записи кешу для очищених URL, що все ще використовуються на сайті.

Повторна перевірка невдалих посилань

Деякі сайти показують браузерам дійсні сторінки, але відмовляють простим HTTP-клієнтам, як-от Lychee (захист від ботів, безумовні відповіді 404 від crates.io, перенаправлення на сторінку входу npmjs.com). Оскільки невдачі ніколи не кешуються, посилання на такі сайти інакше провалювали б перевірку посилань при кожному запуску, щойно термін дії їхніх кеш-записів закінчиться.

Інструмент double-check повторно перевіряє зафіксовані Lychee невдачі через пробу на рівні вебоглядача. URL, які проба успішно розвʼязує, записуються у .lycheecache з синтетичним статусом 206 («OK by analysis»). Робочий процес Refcache refresh запускає його після перевірки посилань; щоб запустити його локально на основі збереженого журналу:

npm run log:check:links
npm run fix:link-cache:double-check

Щодо параметрів виконайте npm run fix:link-cache:double-check -- --help. Щодо поведінки зонда та налаштування дивіться double-check README.

У CI

Робочий процес check-links.yml збирає сайт один раз (скорочено) та передає цей артефакт завданню CHECK LINKS, тому локальні запуски та CI перевіряють ту саму збірку. Це завдання завершується помилкою, якщо будь-яка перевірка посилань не вдається, і передає оновлений кеш завданню CACHE updates committed?, яке завершується помилкою, якщо після запуску зафіксований .lycheecache залишається застарілим.