FormaTeX

\usepackage{github-actions}

جمّع LaTeX في GitHub Actions

أتمتة تجميع LaTeX في خط CI/CD الخاص بك. يجمّع كل دفع (push) مستنداتك، ويكشف الأخطاء قبل الدمج، وينشر ملفات PDF كمخرجات قابلة للتنزيل، دون الحاجة إلى تثبيت TeX Live محليًا.

\section{لماذا CI/CD لـ LaTeX}

أصدر مستنداتك بثقة

تعامل مع مصدر LaTeX كما تتعامل مع البرمجيات. تكشف عمليات البناء الآلية الحزم المعطوبة والملفات المفقودة وأخطاء التجميع قبل أن تصل إلى قرّائك.

لا تصدر ملفات PDF معطوبة أبدًا

اكشف أخطاء التجميع قبل الدمج. تفشل فحوصات طلب السحب (pull request) إذا تعذّر تجميع المستند.

توزيع آلي

تُرفق ملفات PDF كمخرجات بكل تشغيل لسير العمل. شارك رابطًا مباشرًا لأحدث مستند مجمَّع.

لا حاجة إلى TeX Live محليًا

يساهم أعضاء الفريق في مصدر LaTeX دون تثبيت TeX Live. تتولى واجهة API التجميع في السحابة.

\section{Prerequisites}

قبل أن تبدأ

  • حساب FormaTeX: تكفي الخطة المجانية (15 عملية تجميع/شهر)
  • مفتاح FormaTeX API من لوحة التحكم
  • مستودع GitHub يحتوي على ملفات .tex

\section{دليل خطوة بخطوة}

الإعداد في أربع خطوات

1

احصل على مفتاح API

سجّل في FormaTeX وانسخ مفتاح API من لوحة التحكم. تتضمن الخطة المجانية 15 عملية تجميع مجانية شهريًا، وهي كافية للبدء.

2

أضف السر إلى GitHub

خزّن مفتاح API كسر في المستودع حتى لا يظهر أبدًا في ملف YAML الخاص بسير العمل. انتقل إلى Repository → Settings → Secrets and variables → Actions → New secret وسمِّه FORMATEX_API_KEY.

# Add your FormaTeX API key as a GitHub Actions secret
# Go to: Repository → Settings → Secrets and variables → Actions → New secret
# Name: FORMATEX_API_KEY
# Value: your API key from formatex.io/dashboard/api-keys

# Test locally before committing:
export FORMATEX_API_KEY="your-key-here"
curl -X POST https://api.formatex.io/api/v1/compile \
  -H "X-API-Key: $FORMATEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"latex": "\\documentclass{article}\\begin{document}Hello\\end{document}", "engine": "pdflatex"}'
3

أنشئ ملف سير العمل

أنشئ الملف .github/workflows/latex.yml في مستودعك. يجمّع سير العمل البسيط هذا الملف main.tex ويرفع ملف PDF الناتج كمخرج (artifact).

# .github/workflows/latex.yml
name: Compile LaTeX

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  compile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Compile LaTeX to PDF
        env:
          FORMATEX_API_KEY: ${{ secrets.FORMATEX_API_KEY }}
        run: |
          jq -n --rawfile latex main.tex '{engine: "xelatex", latex: $latex}' \
            | curl --fail-with-body -sS -X POST https://api.formatex.io/api/v1/compile \
                -H "X-API-Key: $FORMATEX_API_KEY" \
                -H "Content-Type: application/json" \
                -d @- -o output.pdf

      - name: Upload PDF artifact
        uses: actions/upload-artifact@v4
        with:
          name: compiled-pdf
          path: output.pdf
4

ادفع التغييرات وراقب البناء

نفّذ commit وادفع ملف سير العمل. سيبدأ GitHub Actions تلقائيًا عند دفعك التالي إلى main. افتح تبويب Actions في مستودعك لمشاهدة تشغيل سير العمل. وعند اكتماله، يظهر ملف PDF المجمَّع ضمن Artifacts.

\section{إعداد سير العمل الكامل}

بناء مصفوفي مع معالجة الأخطاء

توسّع إلى مستندات متعددة باستراتيجية المصفوفة (matrix). يجمّع سير العمل هذا الأطروحة والعرض التقديمي والملحق بالتوازي، ويلتقط أخطاء HTTP بشكل صريح، ويحتفظ بملفات PDF لمدة 30 يومًا.

# .github/workflows/latex-full.yml
name: LaTeX Build Pipeline

on:
  push:
    paths: ['**.tex', '**.bib']

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        document: [thesis, presentation, appendix]

    steps:
      - uses: actions/checkout@v4

      - name: Compile ${{ matrix.document }}
        env:
          FORMATEX_API_KEY: ${{ secrets.FORMATEX_API_KEY }}
          DOC: ${{ matrix.document }}
        run: |
          jq -n --rawfile latex "$DOC.tex" '{engine: "xelatex", latex: $latex}' \
            | curl --fail-with-body -sS -X POST https://api.formatex.io/api/v1/compile \
                -H "X-API-Key: $FORMATEX_API_KEY" \
                -H "Content-Type: application/json" \
                -d @- -o "$DOC.pdf"

      - name: Upload PDFs
        uses: actions/upload-artifact@v4
        with:
          name: pdfs-${{ matrix.document }}
          path: ${{ matrix.document }}.pdf
          retention-days: 30

\section{اختيار المُجمِّع}

اختر مُجمِّع LaTeX

مرّر الحقل الاختياري engine في جسم JSON للتحكم في المُجمِّع الذي يستخدمه FormaTeX. القيمة الافتراضية هي pdflatex عند عدم تحديده.

pdflatexxelatexlualatex

\section{Troubleshooting}

المشكلات الشائعة وحلولها

مفتاح API غير معيَّن

تأكد من إضافة FORMATEX_API_KEY كسر (secret) في المستودع وليس كمتغير. الأسرار مشفّرة أما المتغيرات فلا. انتقل إلى Settings → Secrets and variables → Actions → Secrets (وليس Variables).

ملفات .tex الكبيرة

للملفات التي تتجاوز 10 MB، استخدم نقطة نهاية التجميع غير المتزامن (/api/v1/compile/async). تُعيد نقطة النهاية غير المتزامنة معرّف مهمة يمكنك الاستعلام عنه للحصول على النتيجة.

حزم مفقودة

تتضمن بيئة FormaTeX المعزولة TeX Live 2023 كاملًا، وأغلب حزم CTAN متاحة مباشرةً. إذا كانت إحدى الحزم مفقودة، تواصل مع الدعم وسنضيفها.

\section{تكاملات ذات صلة}

استخدم FormaTeX من أي بيئة

FormaTeX هو واجهة HTTP API بسيطة. أمثلة جاهزة للنسخ واللصق لكل لغة ومنصة رئيسية.

هل أنت مستعد لأتمتة عمليات بناء LaTeX؟

الخطة المجانية: 15 عملية تجميع مجانية شهريًا. لا حاجة إلى بطاقة ائتمان.