Static Blog + Telegram Cross-Post

A minimal static blog that automatically cross-posts to Telegram using GitHub Pages and GitHub Actions.

✨ Features

• 📝 Static Blog: Fast, lightweight blog built with vanilla HTML/CSS/JS
• 🤖 Telegram Integration: Automatic cross-posting to Telegram channels with images
• 🔄 GitHub Actions: Automated builds and deployments
• 📱 Responsive Design: Mobile-friendly layout
• 🔍 SEO Ready: Includes sitemap, RSS feed, and meta tags
• 🎨 Dark Theme: Modern dark theme with smooth animations

📺 Live Example

See this project in action: Telegram Channel Example

🚀 Quick Start

1. Setup Repository

git clone https://github.com/your-username/pages-telegram-blog.git
cd pages-telegram-blog

2. Configure GitHub Pages

1. Go to Settings → Pages in your GitHub repository
2. Set source to Deploy from a branch
3. Select branch: main and folder: / (root)

3. Setup Telegram Bot

1. Create a bot with @BotFather on Telegram
2. Get your bot token
3. Add your bot to your channel as an admin
4. Get your channel ID (numeric, e.g., -1001234567890)

4. Configure Secrets

In your GitHub repository, go to Settings → Secrets and variables → Actions and add:

• TELEGRAM_BOT_TOKEN: Your bot token from BotFather
• TELEGRAM_CHAT_ID: Your channel's numeric ID

5. Create Your First Post

mkdir posts/my-first-post

Create posts/my-first-post/meta.json:

{
  "title": "My First Post",
  "description": "This is my first blog post!",
  "date": "2025-01-01",
  "tags": ["blog", "first-post"],
  "image": "cover.png",
  "telegram_message": "Check out my first blog post! 🎉"
}

Create posts/my-first-post/index.html with your blog content and add a cover.png image.

📁 Project Structure

.
├── 📄 index.html
├── 📂 posts/
│   └── 📂 post-slug/
│       ├── 📄 index.html
│       ├── 📄 meta.json
│       └── 🖼️ cover.png
├── 📂 assets/
│   ├── 📂 css/
│   │   └── 📄 site.css
│   └── 📂 img/
│       └── 🖼️ og-default.png
├── 📂 scripts/
│   ├── 🐍 build_index.py
│   ├── 🐍 changed_posts.py
│   └── 🐍 telegram_post.py
├── 📂 .github/workflows/
│   ├── 🔧 build.yml
│   └── 🔧 post-to-telegram.yml
├── 📄 feed.xml
├── 📄 sitemap.xml
└── 📄 robots.txt

🛠️ Development

Prerequisites

• Python 3.11+
• Git

Local Setup

git clone https://github.com/your-username/pages-telegram-blog.git
cd pages-telegram-blog
pip install -e ".[dev]"
pre-commit install

Code Quality

This project uses pre-commit hooks to maintain code quality:

• Ruff: Code formatting and linting
• MyPy: Static type checking
• Prettier: HTML/CSS/JS formatting
• Markdownlint: Markdown linting
• Bandit: Security scanning

Hooks run automatically on commit, or manually:

pre-commit run --all-files

Building Locally

python scripts/build_index.py

python scripts/telegram_post.py my-post-slug

Adding Posts

1. Create a new directory: posts/your-post-slug/
2. Add required files:
   • index.html: Your blog post content
   • meta.json: Post metadata
   • cover.png: Post cover image
3. Commit and push to trigger auto-build and Telegram posting

Post Metadata Schema

{
  "title": "Required: Post title",
  "description": "Optional: Post description for SEO",
  "date": "Required: YYYY-MM-DD format",
  "tags": ["Optional", "Array", "Of", "Tags"],
  "image": "Optional: image filename (defaults to cover.png)",
  "telegram_message": "Optional: Custom Telegram caption"
}

🔧 Customization

Styling

Edit assets/css/site.css to customize the appearance. The current theme uses CSS custom properties for easy color scheme modifications.

Site Configuration

Update the constants in scripts/build_index.py:

• SITE_DESC: Site description for SEO
• Page titles and metadata

Telegram Messages

Customize Telegram post format in scripts/telegram_post.py or use the telegram_message field in post metadata.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔒 Security

Please see SECURITY.md for security considerations and reporting vulnerabilities.

🆘 Support

• 📖 Check the documentation
• 🐛 Report bugs
• 💡 Request features
• 💬 Ask questions

---

Made with ❤️ for the blogging community