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

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

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

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

npm run check:links

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

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

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

Невиробничі збірки сайту містять чернетки та сторінки з датою в майбутньому, а виробничі збірки їх виключають. Тому посилання на таку сторінку працює в deploy preview і проходить check:links, але повертає 404 на виробничому сайті. Скрипт check:links:production-internal виявляє це: він виконує офлайн-перевірку на скороченій виробничій збірці та повідомляє про кожну сторінку, яка посилається на ціль, яку збірка не створила. Щоб побачити погляд контрибʼютора на невдачу, дивіться CHECK LINKS (production, internal).

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

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

Перевірка посилань читає згенерований (проігнорований git) файл lychee.toml, який скрипт generate:config:links створює з lychee.base.toml плюс винятки, обчислені з двох полів front matter:

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

Збережені статуси відхилення відстають від змін в англійському вмісті, доки наступну синхронізацію статусів Housekeeping не обʼєднано, тому генератор також обробляє сторінки з очікуваним відхиленням як такі, що мають відмінності:

• Сторінка з очікуваним відхиленням: локалізована копія, англійська сторінка якої змінилася або була видалена після базового рівня статусу відхилення, якщо сама копія відтоді не змінювалася (хтось працює над нею).
• Базовий рівень статусу відхилення: коміт main, записаний у data/l10n-drift.yaml загальними синхронізаціями статусів (npm run fix:i18n). Локальна синхронізація може перезаписати цей файл; залиште перезапис незафіксованим, оскільки записаний коміт може не існувати у вихідному репозиторії.

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

• Отримайте відсутню історію: git fetch upstream main.
• Перевизначте базовий рівень: DRIFT_BASELINE=HEAD npm run check:links порівнює з поточним комітом, тож лише незафіксовані зміни англійського вмісту зараховуються як такі, що очікують відхилення (збережені статуси все ще діють).

Link cache

Результати перевірки зовнішніх посилань кешуються у link-cache.jsonc, зафіксований кеш, який підтримує пакунок link-cache; власний файл кешу Lychee, .lycheecache, виводиться з нього за кожним запуском і ігнорується git. Щодо формату файлу, включаючи те, як вручну додати запис, див. Власний кеш; щодо того, які URL перевірка завантажує, а які віддає з кешу, див. Операційна модель. Ручні правки — лише для навмисного засіювання; для URL, який просто блокує перевірку посилань, додайте ?link-check=no до нього (див. Обробка дійсних зовнішніх посилань).

Кеш регулярно оновлюється кількома запланованими робочими процесами, а також PR із змінами вмісту, тому одноразові оновлення можуть конфліктувати під час 3-way merge Git, включаючи різні URL: обидві сторони вставляють у той самий відсортований проміжок, або одна сторона обрізає запис, який інша оновила або вставила поруч (такий фрагмент може тоді розділити запис). Коли зміни кешу гілки — це рутинні результати перевірки, бери файл main повністю і повторно запусти перевірку, яка повторно додасть все, що потрібно гілці; інакше слідуй правилам конфліктів у Власний кеш, потім повторно запусти перевірку для нормалізації файлу.

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

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

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

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

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

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

Інструмент double-check повторно перевіряє зафіксовані Lychee невдачі через пробу на рівні вебоглядача. URL, які проба успішно розвʼязує, записуються у link-cache.jsonc з синтетичним статусом 206 («OK by analysis»); URL, які вона не може розвʼязати, зберігають невдачу, записану перевіркою, для опрацювання в PR оновлення. Робочий процес 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 збирає сайт (скорочено) у своєму завданні BUILD та передає цей артефакт завданню CHECK LINKS, тому локальні запуски та CI перевіряють ту саму збірку. Це завдання завершується помилкою, якщо будь-яка перевірка посилань не вдається, і передає оновлений кеш завданню CACHE updates committed?, яке завершується помилкою, якщо після запуску зафіксований link-cache.jsonc залишається застарілим.

Завдання CHECK LINKS (production, internal) виконується поряд із BUILD, зі своєю власною збіркою: воно запускає check:links:production-internal.