برای اضافه کردن یک یادداشت کوتاه به وبلاگ Jekyll، معمولاً باید فایل Markdown بسازید، مشخصات نوشته را در ابتدای آن قرار دهید و تغییرات را به مخزن بفرستید. پروژهٔ tg-blog-updater این مسیر را از داخل تلگرام در دسترس قرار می‌دهد: عنوان، برچسب‌ها و متن را در یک پیام می‌فرستید و ربات فایل نوشته را در مخزن گیت‌هاب ایجاد می‌کند.
خروجی ربات یک commit شامل نوشتهٔ جدید است. ساخت و انتشار وبلاگ همچنان بر عهدهٔ فرایندی است که برای مخزن خود تنظیم کرده‌اید؛ برای مثال، اگر انتشار سایت با هر commit آغاز شود، نوشتهٔ ارسالی هم از همان مسیر منتشر خواهد شد.
از پیام تا فایل وبلاگ
ربات با کتابخانهٔ python-telegram-bot پیام‌ها را به روش polling دریافت می‌کند. پیام متنی باید از چتی با شناسهٔ مجاز رسیده باشد و ساختار مورد انتظار را داشته باشد. سپس عنوان، برچسب‌ها و بدنه استخراج می‌شوند و فایل از طریق PyGithub و GitHub Contents API ساخته می‌شود.
- مسیر پیش‌فرض نوشته‌ها
_postsاست و نام فایل از تاریخ روز و slug عنوان ساخته می‌شود. - عنوان فارسی در slug حفظ می‌شود؛ برای مثال «سلام دنیا» به
سلام-دنیاتبدیل می‌شود. - تاریخ نوشته و نام فایل بر اساس منطقهٔ زمانی تنظیم‌شده محاسبه می‌شوند؛ مقدار پیش‌فرض
Asia/Tehranاست. - ابتدای فایل شامل مشخصات
title،dateوtagsاست و پس از آن متن Markdown قرار می‌گیرد. - اگر برای همان روز و همان slug فایلی وجود داشته باشد، ربات آن را بازنویسی نمی‌کند و درخواست تغییر عنوان می‌دهد.
جزئیات ساخت نام فایل و محتوای نوشته در ماژول پردازش نوشته‌ها قرار دارد.
پیش‌نیازها و تنظیمات
برای شروع به یک مخزن حاوی وبلاگ Jekyll، توکن ربات از BotFather و توکن گیت‌هاب با امکان نوشتن در مخزن مقصد نیاز دارید. برای توکن fine-grained، دسترسی Contents: Read and write روی همان مخزن کافی است.
شناسهٔ عددی چت مجاز را هم مشخص کنید. اگر از گروه استفاده می‌کنید، طبق راهنمای پروژه باید privacy mode ربات را غیرفعال کنید یا آن را مدیر گروه قرار دهید تا پیام‌ها را دریافت کند. برای کانال نیز ربات باید مدیر باشد. یک چت قابل‌دسترسی برای ربات را به دریافت خطاها اختصاص دهید؛ چت خصوصی با ربات برای این کار مناسب است.
با نصب بودن Git، فایل نمونهٔ تنظیمات را دریافت کنید:
git clone https://github.com/hatamiarash7/tg-blog-updater.git
cd tg-blog-updater
cp .env.example .envفایل .env را با مقادیر خودتان تکمیل کنید:
| متغیر | کاربرد |
|---|---|
TELEGRAM_TOKEN |
توکن ربات تلگرام؛ الزامی |
CHAT_ID |
شناسهٔ عددی چتی که اجازهٔ ایجاد نوشته دارد؛ الزامی |
DEBUG_CHAT_ID |
شناسهٔ عددی چت دریافت گزارش خطا؛ الزامی |
GITHUB_TOKEN |
توکن دارای دسترسی نوشتن محتوای مخزن؛ الزامی |
GITHUB_REPO_NAME |
نام مخزن مقصد با قالب username/repo؛ الزامی |
POST_PATH |
پوشهٔ نوشته‌ها؛ پیش‌فرض _posts |
TIMEZONE |
نام منطقهٔ زمانی IANA؛ پیش‌فرض Asia/Tehran |
TELEGRAM_BASE_URL |
نشانی پایهٔ Bot API؛ پیش‌فرض https://api.telegram.org/bot |
قالب username/repo یک نمونه است و باید با نام مالک و مخزن وبلاگ جایگزین شود. توکن‌ها را فقط در تنظیمات محیط اجرا نگه دارید و داخل نوشته‌ها یا مخزن منتشر نکنید.
اجرا با Docker
پس از تکمیل .env، با نصب بودن Docker می‌توانید از دستور مستندشدهٔ پروژه استفاده کنید:
docker run -d --name tg-blog-updater --init --env-file .env \
--restart unless-stopped \
hatamiarash7/tg-blog-updater:latestدر این روش Docker مقادیر فایل را به متغیرهای محیطی تبدیل می‌کند. خود برنامه فایل .env را بارگذاری نمی‌کند؛ بنابراین در اجرای مستقیم Python، متغیرها باید از قبل در محیط فرایند تعریف شده باشند. فایل Compose مخزن نیز تنظیمات را با env_file می‌خواند و برای ساخت محلی ایمیج در دسترس است. جزئیات روش‌های اجرا در راهنمای مخزن آمده است.
ربات برای دریافت پیام از polling استفاده می‌کند؛ در این روش نیازی به تعریف نشانی وب‌هوک یا باز کردن پورت ورودی برای ربات ندارید. محیط اجرا باید به API تلگرام و گیت‌هاب دسترسی داشته باشد.
ارسال اولین نوشته
دستور /start قالب پیام را نشان می‌دهد. عنوان و برچسب‌ها هرکدام باید در یک خط باشند و با خطوط === از بخش بعدی جدا شوند. بدنه می‌تواند چندخطی باشد. نمونهٔ زیر را به‌صورت یک پیام متنی در چت مجاز ارسال کنید:
سلام دنیا
===
jekyll, telegram, یادداشت
===
این اولین نوشته‌ای است که از تلگرام به وبلاگ می‌فرستم.
## یک نکتهٔ کوتاه
متن نوشته می‌تواند شامل **Markdown** و چند بند جداگانه باشد.برای جدا کردن برچسب‌ها از کامای انگلیسی , استفاده کنید. عنوان، فهرست برچسب‌ها و بدنه نباید خالی باشند. بدنه به‌عنوان متن Markdown ذخیره می‌شود؛ قالب‌بندی بصری تلگرام به Markdown تبدیل نمی‌شود، پس نشانه‌هایی مانند ** و ## را در خود متن بنویسید.
برای نمونه، اگر این پیام در روز سوم اکتبر ۲۰۲۶ به وقت منطقهٔ تنظیم‌شده پردازش شود، مسیر فایل _posts/2026-10-03-سلام-دنیا.md خواهد بود. تاریخ واقعی هنگام پردازش پیام تعیین می‌شود. پس از ایجاد موفق commit، ربات پیام تأیید می‌فرستد؛ این تأیید مربوط به ثبت فایل در گیت‌هاب است و پایان انتشار سایت را تضمین نمی‌کند.
نکات استفاده
- دسترسی در سطح چت است: بررسی مجوز بر اساس
CHAT_IDانجام می‌شود، نه شناسهٔ شخص فرستنده. در گروه مجاز، هر عضوی که پیامش به ربات برسد می‌تواند با قالب درست نوشته ایجاد کند؛ گروه را متناسب با دسترسی نویسندگان انتخاب کنید. - مقصد، شاخهٔ پیش‌فرض مخزن است: در فراخوانی ایجاد فایل، شاخهٔ دیگری تعیین نمی‌شود و تنظیم محیطی برای انتخاب آن وجود ندارد. دسترسی توکن و قواعد شاخه باید اجازهٔ ایجاد commit بدهند.
- عملیات اصلی ایجاد نوشته است: گردش کار ویرایش یا حذف نوشته و بارگذاری پیوست در این پیاده‌سازی وجود ندارد. برای تصویر می‌توانید لینک Markdown بنویسید، اما خود تصویر باید از قبل میزبانی شده باشد.
- قالب Jekyll باید آماده باشد: ربات فقط
title،dateوtagsرا به مشخصات ابتدای فایل اضافه می‌کند. اگر قالب وبلاگ بهlayoutیا فیلدهای دیگر نیاز دارد، آن‌ها را از طریق پیش‌فرض‌های Jekyll یا تغییر کد تولید نوشته تأمین کنید. - گزارش خطا می‌تواند شامل محتوا باشد: بخشی از اطلاعات پیام دریافتی و traceback به
DEBUG_CHAT_IDفرستاده می‌شود. این چت را خصوصی و محدود به افراد مرتبط نگه دارید.
این رفتارها در کد ربات قابل بررسی‌اند. پروژه با مجوز MIT منتشر شده و برای افزودن یادداشت‌های کوتاه از تلگرام به وبلاگی با مسیر انتشار آماده، ابزار کوچکی فراهم می‌کند.