Phil Skentelbery
372064b116
Implement Phase 3 of v1.3.0 tags feature per microformats-tags-design.md: Routes (starpunk/routes/public.py): - Add /tag/<tag> archive route with normalization and 404 handling - Pre-load tags in index route for all notes - Pre-load tags in note route for individual notes Admin (starpunk/routes/admin.py): - Parse comma-separated tag input in create route - Parse tag input in update route - Pre-load tags when displaying edit form - Empty tag field removes all tags Templates: - Add tag input field to templates/admin/edit.html - Add tag input field to templates/admin/new.html - Use Jinja2 map filter to display existing tags Implementation details: - Tag URL parameter normalized to lowercase before lookup - Tags pre-loaded using object.__setattr__ pattern (like media) - parse_tag_input() handles trim, dedupe, normalization - All existing tests pass (micropub categories, admin routes) Per architect design: - No pagination on tag archives (acceptable for v1.3.0) - No autocomplete in admin (out of scope) - Follows existing media loading patterns Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
206 lines
5.7 KiB
Markdown
206 lines
5.7 KiB
Markdown
# StarPunk
|
|
|
|
A minimal, self-hosted IndieWeb CMS for publishing notes with RSS syndication.
|
|
|
|
**Current Version**: 1.2.0
|
|
|
|
## Versioning
|
|
|
|
StarPunk follows [Semantic Versioning 2.0.0](https://semver.org/):
|
|
- Version format: `MAJOR.MINOR.PATCH`
|
|
- Current: `1.2.0` (stable release)
|
|
- Check version: `python -c "from starpunk import __version__; print(__version__)"`
|
|
- See changes: [CHANGELOG.md](CHANGELOG.md)
|
|
- Versioning strategy: [docs/standards/versioning-strategy.md](docs/standards/versioning-strategy.md)
|
|
|
|
## Philosophy
|
|
|
|
"Every line of code must justify its existence. When in doubt, leave it out."
|
|
|
|
StarPunk is designed for a single user who wants to:
|
|
- Publish short notes to their personal website
|
|
- Own their content (notes stored as portable markdown files)
|
|
- Syndicate via RSS
|
|
- Support IndieWeb standards (Micropub, IndieAuth)
|
|
- Run on minimal resources
|
|
|
|
## Features
|
|
|
|
- **File-based storage**: Notes are markdown files, owned by you
|
|
- **IndieAuth authentication**: Use your own website as identity
|
|
- **Micropub support**: Full W3C Micropub specification compliance
|
|
- **Media attachments**: Upload and display images with your notes
|
|
- **Microformats2**: Full h-entry, h-card, and h-feed markup for IndieWeb compatibility
|
|
- **Author discovery**: Automatic profile discovery from your IndieWeb identity
|
|
- **RSS, ATOM, JSON Feed**: Multiple syndication formats with Media RSS support
|
|
- **Custom slugs**: Control your note permalinks
|
|
- **No database lock-in**: SQLite for metadata, files for content
|
|
- **Self-hostable**: Run on your own server
|
|
- **Minimal dependencies**: Core dependencies, no build tools
|
|
|
|
## Requirements
|
|
|
|
- Python 3.11 or higher
|
|
- 500MB disk space
|
|
- Linux, macOS, or Windows with WSL2
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Clone repository
|
|
git clone https://github.com/YOUR_USERNAME/starpunk.git
|
|
cd starpunk
|
|
|
|
# Install uv (package manager)
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
|
|
# Create virtual environment
|
|
uv venv .venv --python 3.11
|
|
|
|
# Install dependencies
|
|
uv pip install -r requirements.txt
|
|
|
|
# Configure
|
|
cp .env.example .env
|
|
# Edit .env and set ADMIN_ME and SESSION_SECRET
|
|
|
|
# Initialize database
|
|
mkdir -p data/notes
|
|
.venv/bin/python -c "from starpunk.database import init_db; init_db()"
|
|
# Note: Database also auto-initializes on first run if not present
|
|
|
|
# Run development server
|
|
.venv/bin/flask --app app.py run --debug
|
|
|
|
# Visit http://localhost:5000
|
|
```
|
|
|
|
## Configuration
|
|
|
|
All configuration is in the `.env` file. Required settings:
|
|
|
|
- `ADMIN_ME` - Your IndieWeb identity URL (e.g., https://yoursite.com)
|
|
- `SESSION_SECRET` - Random secret key (generate with `python3 -c "import secrets; print(secrets.token_hex(32))"`)
|
|
- `SITE_URL` - Public URL of your site
|
|
|
|
See `.env.example` for all options.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
starpunk/
|
|
├── app.py # Application entry point
|
|
├── starpunk/ # Application code
|
|
├── data/ # Your notes and database (gitignored)
|
|
│ ├── notes/ # Markdown files
|
|
│ └── starpunk.db # SQLite database
|
|
├── static/ # CSS and JavaScript
|
|
├── templates/ # HTML templates
|
|
└── tests/ # Test suite
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Publishing Notes
|
|
|
|
**Via Web Interface**:
|
|
1. Navigate to `/admin`
|
|
2. Login with your IndieWeb identity
|
|
3. Create notes in markdown
|
|
|
|
**Via Micropub Client**:
|
|
1. Configure client with your site URL
|
|
2. Authenticate via IndieAuth
|
|
3. Publish from any Micropub-compatible app
|
|
|
|
### Backing Up Your Data
|
|
|
|
Your notes are stored as plain markdown files in `data/notes/`. Back up this directory:
|
|
|
|
```bash
|
|
# Simple backup
|
|
tar -czf backup.tar.gz data/
|
|
|
|
# Or use rsync
|
|
rsync -av data/ /backup/starpunk/
|
|
```
|
|
|
|
## Development
|
|
|
|
See [docs/standards/development-setup.md](docs/standards/development-setup.md) for detailed setup.
|
|
|
|
```bash
|
|
# Install dev dependencies
|
|
uv pip install -r requirements-dev.txt
|
|
|
|
# Run tests
|
|
.venv/bin/pytest
|
|
|
|
# Format code
|
|
.venv/bin/black starpunk/ tests/
|
|
|
|
# Lint
|
|
.venv/bin/flake8 starpunk/ tests/
|
|
```
|
|
|
|
## Architecture
|
|
|
|
StarPunk uses a hybrid storage approach:
|
|
- **Notes content**: Markdown files (portable, human-readable)
|
|
- **Metadata**: SQLite database (fast queries)
|
|
|
|
This gives you both portability AND performance.
|
|
|
|
See [docs/architecture/](docs/architecture/) for complete documentation.
|
|
|
|
## IndieWeb Compliance
|
|
|
|
StarPunk implements:
|
|
- [Micropub](https://micropub.spec.indieweb.org/) - Publishing API
|
|
- [IndieAuth](https://www.w3.org/TR/indieauth/) - Authentication
|
|
- [Microformats2](http://microformats.org/) - h-entry, h-card, h-feed markup
|
|
- [RSS 2.0](https://www.rssboard.org/rss-specification) with Media RSS extensions
|
|
- [ATOM 1.0](https://validator.w3.org/feed/docs/atom.html) - Syndication format
|
|
- [JSON Feed 1.1](https://jsonfeed.org/version/1.1) - Modern feed format
|
|
|
|
## Deployment
|
|
|
|
### Production Setup
|
|
|
|
```bash
|
|
# Install gunicorn
|
|
uv pip install gunicorn
|
|
|
|
# Run with gunicorn
|
|
.venv/bin/gunicorn -w 4 -b 127.0.0.1:8000 app:app
|
|
|
|
# Configure nginx/Caddy for HTTPS
|
|
# Set up systemd for process management
|
|
# Enable regular backups of data/ directory
|
|
```
|
|
|
|
See [docs/standards/deployment-standards.md](docs/standards/deployment-standards.md) for details.
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file
|
|
|
|
## Credits
|
|
|
|
Built with:
|
|
- [Flask](https://flask.palletsprojects.com/) - Web framework
|
|
- [python-markdown](https://python-markdown.github.io/) - Markdown processing
|
|
- [feedgen](https://feedgen.kiesow.be/) - RSS generation
|
|
- [httpx](https://www.python-httpx.org/) - HTTP client
|
|
- [IndieLogin](https://indielogin.com/) - Authentication service
|
|
|
|
## Contributing
|
|
|
|
This is a personal project optimized for single-user use. If you want additional features, consider forking!
|
|
|
|
## Support
|
|
|
|
- Documentation: [docs/](docs/)
|
|
- Issues: GitHub Issues
|
|
- IndieWeb: [indieweb.org](https://indieweb.org/)
|