لو موقعك فيه 300 مقال وبتربط لمصادر خارجية في كل واحد منهم، غالبًا عندك دلوقتي ما بين 40 و 70 رابط بيرجّع HTTP 404 أو DNS error — وانت مش عارف. المقال ده بيوريك إزاي تأتمت الفحص كل أسبوع، تاخد تقرير مرتّب، وتفضّل ماسك موقعك قبل ما Google يخصم منه ترتيب.
الموقف باختصار: ليه الروابط الخارجية بتموت
لمّا بتكتب مقال تقني وبتحط رابط لـ توثيق أو مقال مرجعي، إنت بتعمل وعد للقارئ: "الرابط ده شغّال". المشكلة إن الوعد ده بيتكسر بشكل طبيعي بمرور الوقت. الشركات بتعيد هيكلة مواقعها، الدومينات بتنتهي، الصفحات بتتنقل من /blog/x إلى /docs/x. دراسة Ahrefs من 2023 على 2 مليون صفحة لقيت إن 66.5% من الروابط القديمة بتموت خلال 9 سنين. المعدل السنوي تقريبًا 7-8% لو ما فحصتش يدويًا.
خلينا نقرّب المفهوم بمثال بسيط قبل ما نتعمّق. تخيّل إنك عندك مكتبة فيها 500 كتاب، وكل كتاب بيحيل للقارئ على فهرس موجود في كتاب تاني. كل سنة، حوالي 35 كتاب بيتلغي. لو مفيش حد بيتفقّد الفهارس، بعد 3 سنين القارئ بيفتح كتاب، يطلب مرجع، ويلاقي الصفحة فاضية. ده بالظبط اللي بيحصل في موقعك لما ما تفحصش الروابط.
ليه Lychee وليس غيره
الأداة اللي هنستخدمها اسمها Lychee. مكتوبة بـ Rust، مفتوحة المصدر، وبتفحص الروابط بشكل متوازي. فيه بدايل زي linkchecker (Python) أو html-proofer (Ruby)، لكن الفرق رقمي وواضح:
- Lychee: بيفحص 10,000 رابط في حوالي 55 ثانية على GitHub Actions runner.
- linkchecker: نفس العدد بياخد 12-15 دقيقة.
- html-proofer: نفس العدد بياخد 8-10 دقيقة.
الافتراض هنا إن عندك اتصال إنترنت طبيعي من GitHub، ومفيش rate limiting صارم على الدومينات اللي بتربطها.
تعريف دقيق للمفهوم
Lychee بيشتغل كـ HTTP client متوازي (بـ tokio async runtime)، بيرسل طلبات HEAD بدل GET عشان يوفّر bandwidth. لو الرابط رجّع 405 أو 403 على HEAD، بيعمل fallback تلقائي لـ GET. بيدعم استخراج الروابط من Markdown, HTML, reStructuredText، وحتى Org-mode. فيه نظام cache مدمج بيخلّيه ما يفحصش نفس الرابط مرتين في نفس الـ run.
الإعداد الكامل — خطوة بخطوة
الـ workflow ده بيشتغل كل أحد الساعة 2 صباحًا UTC (5 صباحًا بتوقيت القاهرة)، يفحص كل ملفات الموقع، ويفتح Issue تلقائي لو لقى روابط مكسورة. حط الملف ده في .github/workflows/link-check.yml:
name: Link Checker
on:
schedule:
- cron: '0 2 * * 0'
workflow_dispatch:
jobs:
linkChecker:
runs-on: ubuntu-latest
permissions:
issues: write
steps:
- uses: actions/checkout@v4
- name: Restore lychee cache
uses: actions/cache@v4
with:
path: .lycheecache
key: cache-lychee-${{ github.sha }}
restore-keys: cache-lychee-
- name: Run Lychee
id: lychee
uses: lycheeverse/lychee-action@v2
with:
args: >-
--cache
--max-cache-age 7d
--no-progress
--exclude-mail
--exclude-path './node_modules'
--exclude-path './.git'
--timeout 20
--max-retries 2
'./**/*.md'
'./**/*.mdx'
'./**/*.html'
fail: false
output: ./lychee-report.md
- name: Create Issue from report
if: steps.lychee.outputs.exit_code != 0
uses: peter-evans/create-issue-from-file@v5
with:
title: 'تقرير الروابط المكسورة — ${{ github.run_id }}'
content-filepath: ./lychee-report.md
labels: broken-links, maintenance
الـ workflow ده بيستفيد من 3 آليات مهمة. أولًا، actions/cache بيحفظ نتائج الفحص السابقة، فلو رابط رجّع 200 الأسبوع اللي فات، ما بيعيدش فحصه إلا بعد 7 أيام. ده بيخفّض زمن التشغيل بنسبة 40-60% بعد أول run. ثانيًا، --timeout 20 بيمنع تعليق الـ workflow على موقع بطيء لا نهائيًا. ثالثًا، create-issue-from-file بيحوّل التقرير المنسّق Markdown لـ Issue فعلي في الـ repo.
ضبط التوهّمات (False Positives)
أول مرة هتشغّل الـ workflow غالبًا هيدّيك 20-40 رابط "مكسور" في حين إنهم شغّالين فعلًا. ده بيحصل لثلاث أسباب رئيسية.
الأول: دومينات بتحطّ Cloudflare Bot Protection على HEAD requests. الحل إنك تضيف --accept-type text/html أو تستبعدهم صراحة. الثاني: LinkedIn و Twitter بيرجعوا 999 أو 403 لأي crawler. استبعدهم. الثالث: بعض المواقع بتعمل redirect لـ login page لو الـ User-Agent ما عجبهاش.
حط ملف lychee.toml في جذر المشروع:
max_redirects = 10
timeout = 20
max_retries = 2
user_agent = "Mozilla/5.0 (compatible; Lychee/0.15)"
accept = [200, 203, 206, 301, 302, 429]
exclude = [
"^https://linkedin\\.com",
"^https://www\\.linkedin\\.com",
"^https://twitter\\.com",
"^https://x\\.com",
"^https://localhost",
"^mailto:",
"^tel:"
]
exclude_file = ".lycheeignore"
بعدها تقدر تضيف في .lycheeignore أي رابط فردي ما عايز تفحصه.
مثال بسيط للمبتدئين على TOML
لو مشوفتش ملف TOML قبل كده: فكّر فيه كأنه وصفة طبخ. كل سطر فيه "مكوّن = كمية". timeout = 20 معناها "استنّى 20 ثانية بالكتير". exclude معناها "الأكلات اللي مش هنحطها". بعدها، Lychee بيقرأ الوصفة ويطبخ الفحص طبقًا للتعليمات. دلوقتي التعريف العلمي: TOML اختصار لـ "Tom's Obvious Minimal Language"، فورمات إعدادات بسيط ومقروء بشري يُستخدم في أدوات زي Cargo و Poetry و Lychee.
الـ Trade-offs — المكسب والتكلفة
الحل ده مش مجاني بالكامل. بتكسب: فحص أسبوعي لكل الروابط، تنبيه تلقائي، بدون ما تدفع لأي SaaS (فيه خدمات زي Dead Link Checker بتطلب منك 20-50 دولار شهريًا لنفس الشغل). بتخسر: دقائق قليلة من GitHub Actions minutes كل أسبوع. على حساب مجاني بتاخد 2000 دقيقة شهريًا، فحص 500 مقال بياخد حوالي دقيقة واحدة، يعني 4 دقائق شهريًا — أقل من 0.2% من الحصة.
الـ trade-off الكبير الحقيقي: الـ workflow ده بيفحص الروابط من سيرفرات GitHub في US East. لو فيه موقع بيحجب هذه المنطقة، هيتعامل معاه كأنه مكسور. الحل: ضيف المواقع دي في exclude، أو شغّل self-hosted runner من منطقة جغرافية مختلفة.
متى لا تستخدم هذه الطريقة
لو موقعك أقل من 30 مقال، ما تحتاجش أتمتة — افتح npx broken-link-checker يدويًا كل شهر. لو موقعك SPA كامل بـ React وبتولّد المحتوى من API runtime، Lychee مش هيلقى الروابط في الـ HTML الثابت. في الحالة دي استخدم linkinator اللي بيشغّل headless browser (أبطأ لكن بيشوف JS-rendered content). لو عندك Intranet مغلق خلف VPN، GitHub Actions مش هيقدر يوصل، لازم تنقل الـ workflow لـ self-hosted runner داخل الشبكة.
المصادر
- Lychee Official Repository — GitHub
- lychee-action — GitHub Action الرسمي
- Ahrefs Link Rot Study 2023
- GitHub Actions — حدود الاستخدام والفوترة
- create-issue-from-file — GitHub Action
- TOML Specification
الخطوة التالية
افتح repo موقعك دلوقتي، أضف ملف .github/workflows/link-check.yml بالمحتوى اللي فوق، وشغّل workflow_dispatch يدويًا مرة واحدة. هتاخد تقرير كامل في 2-3 دقايق. ركز على الروابط اللي رجّعت 404 أو 410، ابدأ تصلّحها أو استبدلها. الروابط اللي رجّعت 429 سيبها للأسبوع الجاي — غالبًا rate limit مؤقت.