Skip to content

docs: improve readme for seo and discoverability #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bupd merged 2 commits into from
Jan 2, 2026
Merged

docs: improve readme for seo and discoverability #6

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7d01f5e
docs: improve readme for seo and discoverability
bupd Jan 2, 2026
b2f1a45
Merge branch 'main' into docs
bupd Jan 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 107 additions & 63 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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`