From 7d01f5e8c4a2a997d6a08f8d9356872ba137ebcc Mon Sep 17 00:00:00 2001 From: bupd Date: Fri, 2 Jan 2026 23:28:36 +0530 Subject: [PATCH] docs: improve readme for seo and discoverability Signed-off-by: bupd --- README.md | 170 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 107 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index ffbd262..176c84f 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,51 @@ # shitpost -Simple crossposting bridge that accepts text, photos, videos, and documents via a [Telegram bot](https://t.me/shitpost_engine_bot), runs the [crosspost](https://github.com/humanwhocodes/crosspost) CLI to publish them across social platforms. +Telegram-powered social media crossposting tool. Post once to Telegram, publish everywhere. -## Quick summary -- Listens for posts using Telegram Bot. -- Calls the `crosspost` CLI to publish (text-only or with image + alt text). -- Built as a lightweight abstraction over [humanwhocodes/crosspost](https://github.com/humanwhocodes/crosspost) (see that repo for crosspost-specific configuration). +Accept text, photos, videos, and documents via a [Telegram bot](https://t.me/shitpost_engine_bot), then publish them across all your social platforms simultaneously. +A lightweight, self-hosted alternative to Postiz, Buffer, and Hootsuite for developers who want full control over their social media automation. ## Motivation + - I am fed up with posting and managing different platforms. - I have multiple thoughts popping up in my head which I would like to convey to people - But I lack the patience to go through multiple different apps just to say something... - And to update the content based on the app is more hated. - -## Requirements -- Podman/Docker & Compose (recommended) or Go 1.25+ to build/run locally. -- A Telegram bot token (create via @BotFather). +## Features + +- Post to multiple social networks simultaneously from Telegram +- Supports text, images, videos, and documents +- Alt-text support for accessible image posts +- Self-hosted and privacy-focused +- Multi-arch Docker images (amd64, arm64) +- Lightweight Go binary with minimal dependencies + +## Supported Platforms + +| Platform | Text | Images | Videos | +|----------|------|--------|--------| +| Twitter/X | Yes | Yes | Yes | +| Bluesky | Yes | Yes | Yes | +| Mastodon | Yes | Yes | Yes | +| LinkedIn | Yes | Yes | No | +| Discord | Yes | Yes | Yes | +| Telegram | Yes | Yes | Yes | +| Slack | Yes | Yes | No | +| Dev.to | Yes | No | No | +| Nostr | Yes | No | No | + +## Why shitpost? + +| Feature | shitpost | Postiz | Buffer | +|---------|----------|--------|--------| +| Self-hosted | Yes | Yes | No | +| Free | Yes | Freemium | Freemium | +| Telegram interface | Yes | No | No | +| No web UI required | Yes | No | No | +| Privacy-focused | Yes | Partial | No | +| Open source | Yes | Yes | No | ## Docker Images @@ -88,86 +116,102 @@ For production, use a versioned tag (e.g., `v1.0.0`) to avoid unexpected updates 5. Send messages or media to your bot in Telegram. The bot will post using crosspost and reply with logs. +## Requirements -## Environment variables +- Docker/Podman (recommended) or Go 1.25+ +- Telegram bot token (create via [@BotFather](https://t.me/BotFather)) +- API keys for target platforms (Twitter, Bluesky, Mastodon, etc.) -- BOT_TOKEN (required) — Telegram bot token from BotFather. +## Environment Variables -crosspost itself may require additional environment variables (API keys, tokens for target platforms). For details about those envs and how to obtain them, consult: -https://github.com/humanwhocodes/crosspost +| Variable | Required | Description | +|----------|----------|-------------| +| `BOT_TOKEN` | Yes | Telegram bot token from BotFather | +| `TWITTER_API_CONSUMER_KEY` | No | Twitter API consumer key | +| `TWITTER_API_CONSUMER_SECRET` | No | Twitter API consumer secret | +| `TWITTER_ACCESS_TOKEN_KEY` | No | Twitter access token | +| `TWITTER_ACCESS_TOKEN_SECRET` | No | Twitter access token secret | +| `BLUESKY_HOST` | No | Bluesky host (e.g., bsky.social) | +| `BLUESKY_IDENTIFIER` | No | Bluesky handle or email | +| `BLUESKY_PASSWORD` | No | Bluesky app password | +| `MASTODON_HOST` | No | Mastodon instance URL | +| `MASTODON_ACCESS_TOKEN` | No | Mastodon access token | -Use .env (or docker-compose env_file) to supply values. +crosspost itself may require additional environment variables (API keys, tokens for target platforms). For details about those envs and how to obtain them, consult the [crosspost documentation](https://github.com/humanwhocodes/crosspost). +## Usage -## Telegram usage / caption rules +### Text Posts +Send any text message to your bot. It will be posted to all configured platforms. -- Text messages: posted as text via crosspost. -- Images/videos/documents: downloaded and posted via crosspost. -- Alt-text parsing: if the last line of the caption starts with `alt:` (case-insensitive), that line is removed from the caption and used as the image alt text. - Example: - ``` - Here’s the pic - alt: A smiling cat on a red blanket - ``` +### Media Posts +Send images, videos, or documents with an optional caption. +### Alt Text +Add alt text for accessibility by ending your caption with `alt:`: +``` +Check out this sunset! +alt: Orange and purple sunset over mountains +``` -## Running locally (without Docker) +## Running Locally (without Docker) -1. Ensure Go 1.25+ is installed. -2. Install dependencies: - ``` - go mod download - ``` -3. Build: - ``` - CGO_ENABLED=0 GOOS=linux go build -o bot main.go - ``` -4. Export BOT_TOKEN and run: +1. Install Go 1.25+ and crosspost CLI: + ```sh + npm install -g @humanwhocodes/crosspost ``` - export BOT_TOKEN=123456:ABC-DEF... + +2. Build and run: + ```sh + go build -o bot main.go + export BOT_TOKEN=your_token_here ./bot ``` -Note: When running locally, make sure the `crosspost` CLI is available in your PATH (install it with npm: npm install -g @humanwhocodes/crosspost) or adjust PATH accordingly. - - -## Persistence & volumes -- Media downloaded from Telegram are stored at ./downloads in the repo root (mounted to /app/downloads in the container). Keep this folder secure or change the mapping if needed. +## Architecture +``` +Telegram → shitpost bot → crosspost CLI → Social platforms +``` -## Security & privacy notes -- The bot downloads user media to local storage — protect the host and mounted volumes. -- crosspost stdout/stderr are returned to the chat; ensure crosspost does not leak secrets or sensitive tokens in logs. -- Consider implementing user allowlists if the bot will be public-facing (not implemented by default). +Built as a lightweight wrapper around [humanwhocodes/crosspost](https://github.com/humanwhocodes/crosspost). +## Security +- Self-hosted: your data stays on your server +- No third-party analytics or tracking +- Media files stored locally (configure volume mounts) +- Consider implementing allowlists for public-facing bots ## Troubleshooting -- Bot fails on startup: - - Ensure BOT_TOKEN is set and valid. - - Check container logs: docker compose logs -f +### Bot fails on startup +- Verify `BOT_TOKEN` is set correctly +- Check logs: `docker compose logs -f` -- crosspost not found: - - Dockerfile installs crosspost globally; if running locally, install it with: - npm install -g @humanwhocodes/crosspost - - Or ensure crosspost binary is on PATH. +### Posts not appearing +- Verify platform API keys are configured +- Check crosspost output in bot logs -- Files not saved: - - Ensure ./downloads exists and is writeable by the container/user. - - The compose file maps ./downloads to /app/downloads; permissions on host may need adjusting. +### Media not uploading +- Ensure `./downloads` directory exists and is writable +- Check disk space +## Contributing -## Development notes & roadmap (short) -- Add allowlist/denylist for users or groups. -- Add config options to control whether the posted file is returned. -- Add graceful shutdown handling. -- Add tests. -- Improve logging and error reporting. +Contributions welcome! Please open an issue or PR. ## License -See LICENSE in the repository. -References -- crosspost: https://github.com/humanwhocodes/crosspost +See [LICENSE](LICENSE) in the repository. + +## Related Projects + +- [crosspost](https://github.com/humanwhocodes/crosspost) - CLI tool powering the cross-posting +- [Postiz](https://github.com/gitroomhq/postiz-app) - Full-featured social media scheduler +- [Buffer](https://buffer.com) - Commercial social media management + +## GitHub Topics +Add these topics to your repository for better discoverability: +`crosspost`, `social-media`, `telegram-bot`, `twitter`, `bluesky`, `mastodon`, `automation`, `self-hosted`, `golang`, `docker`