خدمة Markdown to PDF عربية بـ Puppeteer في 100 سطر

المستوى المطلوب: متوسط. يفترض المقال إنك تعرف Node.js على مستوى أساسي، تتعامل مع async/await، وعندك فكرة عن Docker. لو لسه مبتدئ في الكلام ده، ابدأ بـ Hono Quickstart الأول وارجع.

لو بتدير منصة عربية وكل أول شهر بييجي عميل يطلب تقرير PDF من dashboard، الحلول الجاهزة بتاعدك بتكلفك $0.05 لكل صفحة وبتفشل في الـ RTL في نص الحالات. الـ 100 سطر اللي قدامك بيولّدوا تقرير 5 صفحات بنص عربي صحيح في 1.2 ثانية، وبيشتغلوا على VPS بـ $9.4 شهريًا.

بناء خدمة Markdown to PDF عربية بـ Puppeteer و Hono

المشكلة باختصار

أغلب مكتبات تحويل Markdown لـ PDF (PDFKit، jsPDF، html-pdf-node القديم) بنيت على bidi engine ضعيف أو معدوم. النتيجة: عنوان "تقرير المبيعات" بيطلع في الـ PDF "تاعيبملا ريرقت" — الحروف بتتعكس، علامات الترقيم بتقع في الناحية الغلط، وأي لاتيني داخل عربي بيكسر السطر. عميلك بيشوف المخرج، بيقفل التذكرة، وبيدور على منافس.

الحل المنطقي: بدل ما تحاول تكتب bidi engine من الصفر، استخدم محرك متصفح كامل (Chromium headless) عشان يضمنلك CSS، font shaping، و Unicode bidirectional algorithm صحيحين. وبعدين خد المخرج كـ PDF عبر API الـ print built-in.

صفحات PDF مطبوعة على مكتب بجانب لابتوب يعرض كود TypeScript لخدمة توليد التقارير

تخيّل المطبعة الورقية القديمة (مثال للمبتدئ)

تخيّل عندك مطبعة قديمة من اللي بنشوفها في أفلام الأبيض والأسود. الماكينة دي فيها صناديق صغيرة، وكل صندوق فيه قوالب حروف معدنية. لما تيجي تطبع جملة، أنت اللي بتختار القوالب وتركبها بإيدك، حرف ورا حرف، من اليمين للشمال للعربي.

لو ركّبت قوالب لاتينية وحاولت "تطبعها بالعكس" عشان تطلع عربي، مش هتظبط. الكسرات مش هتلتصق بالحروف، الهمزات هتقع تحت كلمة تانية، والأرقام داخل الكلام هتسيب فجوات. ده بالظبط اللي بيحصل لما PDFKit يحاول يرسم نص عربي: هو شايفه حروف منفصلة بدون قواعد ربط.

لما تستخدم Chromium headless، زي ما تكون شغّلت ماكينة طباعة ديجيتال حديثة فيها processor كامل بيفهم اللغة. إنت بتدّيله الجملة كنص HTML، وهو بيقرر ترتيب الحروف، أماكن الكسرات، وحجم كل حرف بناءً على اللي قبله واللي بعده.

التعريف العلمي الدقيق

الـ Headless Chrome هو نسخة من Chromium بتشتغل بدون واجهة رسومية — مفيش render إلى شاشة، الناتج بيتكتب على off-screen buffer. مكتبة Puppeteer بتتحكم فيه عبر Chrome DevTools Protocol، نفس البروتوكول اللي بيستخدمه DevTools اللي بتفتحه F12.

المهم في موضوعنا: نفس الـ font rendering، CSS engine، و bidirectional algorithm (UAX #9) بتاع Chrome العادي اللي بيشتغل على ٣ مليار جهاز يوميًا. الـ page.pdf() method بتمر على Chromium's print pipeline، وبتطلع PDF فيه embedded fonts و selectable text — مش صورة. ده يعني عميلك يقدر ينسخ الكلام، يعمل Ctrl+F، ويترجم بـ Google Translate.

الكود الكامل في 100 سطر TypeScript

المعمارية بسيطة: Hono framework يستقبل POST بـ Markdown، يحوّله HTML بـ marked، يحقن CSS RTL وخط Cairo، يفتح page في Chromium مشغّل من قبل، ويرجّع PDF binary.

شاشة محرر كود تعرض ملف TypeScript لـ Hono و Puppeteer مع endpoint توليد PDF

// main.ts import { Hono } from 'hono'; import puppeteer, { Browser } from 'puppeteer'; import { marked } from 'marked'; const app = new Hono(); let browser: Browser | null = null; async function getBrowser() { if (!browser) { browser = await puppeteer.launch({ headless: true, args: ['--no-sandbox', '--disable-dev-shm-usage'], }); } return browser; } const wrap = (body: string, title: string) => `<!DOCTYPE html> <html dir="rtl" lang="ar"> <head> <meta charset="UTF-8"> <title>${title}</title> <link href="https://fonts.googleapis.com/css2?family=Cairo:wght@400;700&display=swap" rel="stylesheet"> <style> body { font-family: 'Cairo', sans-serif; line-height: 1.8; padding: 2cm; color: #111; } h1, h2, h3 { color: #0f172a; margin-top: 1.4em; } code { background: #f4f4f5; padding: 2px 6px; border-radius: 4px; font-size: 0.92em; } pre { background: #0f172a; color: #e2e8f0; padding: 14px; border-radius: 8px; direction: ltr; overflow-x: auto; } table { border-collapse: collapse; width: 100%; margin: 1em 0; } td, th { border: 1px solid #e5e7eb; padding: 10px; text-align: right; } blockquote { border-right: 4px solid #2563eb; padding: 8px 14px; background: #eff6ff; } </style> </head> <body>${body}</body> </html>`; marked.setOptions({ gfm: true, breaks: true }); app.post('/api/pdf', async (c) => { const { markdown, title = 'تقرير' } = await c.req.json(); if (!markdown || typeof markdown !== 'string') { return c.json({ error: 'markdown مطلوب' }, 400); } const html = wrap(await marked.parse(markdown), title); const b = await getBrowser(); const page = await b.newPage(); try { await page.setContent(html, { waitUntil: 'networkidle0', timeout: 15000 }); const pdf = await page.pdf({ format: 'A4', printBackground: true, margin: { top: '1.2cm', bottom: '1.2cm', left: '1cm', right: '1cm' }, preferCSSPageSize: false, }); return new Response(pdf, { headers: { 'Content-Type': 'application/pdf', 'Content-Disposition': `attachment; filename="${title}.pdf"`, }, }); } finally { await page.close(); } }); export default { port: 3000, fetch: app.fetch };

خدمة Markdown to PDF عربية بـ Puppeteer — تقارير RTL في 100 سطر

بناء خدمة Markdown to PDF عربية بـ Puppeteer و Hono

المشكلة باختصار

تخيّل المطبعة الورقية القديمة (مثال للمبتدئ)

التعريف العلمي الدقيق

الكود الكامل في 100 سطر TypeScript

هل استفدت من المقال؟

أرقام مقاسة من إنتاج فعلي

الـ trade-offs اللي لازم تعرفها قبل ما تنزّل ده production

الفخ الأمني الأكبر — لا تتجاهل هذا الجزء

متى لا تستخدم هذه الطريقة أصلاً

الخطوة التالية

مصادر