From dd50c9b1d335365901467d5868ca7f026ed8209a Mon Sep 17 00:00:00 2001 From: Paul Buetow Date: Thu, 16 Apr 2026 09:01:58 +0300 Subject: docs: add comprehensive README with posting instructions Amp-Thread-ID: https://ampcode.com/threads/T-019d94cc-99a9-74af-8f3d-9521cd73324f Co-authored-by: Amp --- README.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 112 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a158f0f..303455a 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,113 @@ -# snonux Microblog engine +# snonux — Static microblog generator -WIP - Come back later. +snonux is the static microblog engine behind [snonux.foo](https://snonux.foo). It processes source files from an input directory into a self-contained static site with paginated HTML pages, an Atom feed, and themed WebGL backgrounds. + +## Quick start + +```sh +go build -o snonux ./cmd/snonux +./snonux --input ./inbox --output ./dist +``` + +## Creating posts + +Drop files into the input directory (`./inbox` by default). Each file becomes one post. Supported formats: + +### Plain text (.txt) + +``` +inbox/ + thoughts.txt +``` + +The text content is rendered as-is into a post. + +### Markdown (.md) + +``` +inbox/ + update.md +``` + +Standard Markdown is converted to HTML (GitHub Flavored Markdown supported). Raw HTML blocks are passed through. + +### Markdown with embedded images + +Reference a local image from your Markdown file using standard `![alt](filename)` syntax. Place the image file in the same input directory: + +``` +inbox/ + update.md + screenshot.png +``` + +Where `update.md` contains: + +```markdown +Check out this screenshot! + +![screenshot](screenshot.png) + +Pretty neat, right? +``` + +The image file is automatically copied into the post's asset directory, and the `` src is rewritten to the correct path. The image file is consumed together with the Markdown file and removed from the input directory after processing. + +**Note:** The image filename in the Markdown must match the actual file in the inbox. Remote URLs (`http://`, `https://`) are left as-is and not downloaded. + +### Images (.png, .jpg, .gif) + +``` +inbox/ + photo.jpg +``` + +A standalone image file becomes its own post. Images wider than 1024px are downscaled and re-encoded as JPEG at 80% quality. + +### Audio (.mp3) + +``` +inbox/ + voice-note.mp3 +``` + +An audio file becomes a post with an embedded HTML5 audio player. + +### After processing + +All source files are removed from the input directory once they have been successfully processed into the output directory. + +## Command-line flags + +``` +--input DIR Input directory for new source files (default: ./inbox) +--output DIR Output directory for generated site (default: ./dist) +--base-url URL Base URL for Atom feed links (default: https://snonux.foo) +--theme NAME Visual theme, or "random" (default: random) +--sync Rsync output to pi0/pi1 after generation +--list-themes Print available theme names and exit +--version Print version and exit +``` + +## Themes + +Each run can use a different visual theme. Use `--list-themes` to see all available themes, or `--theme random` (the default) to pick one at random. + +## Output structure + +``` +dist/ + index.html # Page 1 (newest posts) + page2.html # Page 2, etc. + atom.xml # Atom feed (last 42 entries) + favicon.ico + posts/ + 2026-04-16-120000/ + post.json # Post metadata and rendered HTML + screenshot.png # Asset (if any) + ... +``` + +## License + +See [LICENSE](LICENSE). -- cgit v1.2.3