https://github.com/sun-praise/hugo-admin
A lightweight web-based admin interface for managing Hugo static sites. Provides an intuitive GUI for browsing, searching, editing posts, and controlling the Hugo development server.
https://github.com/sun-praise/hugo-admin
alpinejs blog-admin cms content-management flask hugo hugo-admin markdown-editor python sqlite static-site-generator tailwindcss websocket
Last synced: about 2 hours ago
JSON representation
A lightweight web-based admin interface for managing Hugo static sites. Provides an intuitive GUI for browsing, searching, editing posts, and controlling the Hugo development server.
- Host: GitHub
- URL: https://github.com/sun-praise/hugo-admin
- Owner: sun-praise
- License: apache-2.0
- Created: 2025-11-11T09:05:39.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-06-22T16:49:19.000Z (4 days ago)
- Last Synced: 2026-06-22T18:24:14.814Z (4 days ago)
- Topics: alpinejs, blog-admin, cms, content-management, flask, hugo, hugo-admin, markdown-editor, python, sqlite, static-site-generator, tailwindcss, websocket
- Language: Python
- Homepage:
- Size: 1.38 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Hugo Admin
[](https://github.com/Svtter/hugo-admin/actions)
[](https://github.com/Svtter/hugo-admin/blob/main/LICENSE)
[](https://www.python.org/downloads/)
[](https://gohugo.io/)
[](https://github.com/psf/black)
[δΈζ](README.zh-CN.md) | English
## Screenshot
## Features
- **π Dashboard**: Overview of blog statistics and quick actions
- **π Post Management**: Browse, search, and filter posts by category and tags
- **βοΈ Markdown Editor**: Online editing with auto-save and keyboard shortcuts
- **π Hugo Server Control**: Start/stop Hugo dev server with real-time logs
- **π Advanced Search**: Full-text search with category and tag filtering
- **β‘ Real-time Updates**: WebSocket-based live log streaming
- **πΎ Cache System**: SQLite-based caching for fast post retrieval
- **π Password Login**: Single-admin authentication gates every API and the realtime channel
## Tech Stack
- **Backend**: Flask + Flask-SocketIO
- **Frontend**: Tailwind CSS + Alpine.js
- **Real-time Communication**: WebSocket (Socket.IO)
- **Process Management**: psutil
- **Database**: SQLite (for caching)
## Installation
### Docker (Recommended)
Pull the image from GHCR and run with Docker Compose:
```bash
# Clone the repository
git clone https://github.com/Svtter/hugo-admin.git
cd hugo-admin
# Start the service
docker compose up -d
```
Open your browser and navigate to `http://127.0.0.1:5050`.
See [docker-compose.yml](docker-compose.yml) for volume mounts and environment variables. Adjust the volume paths to match your Hugo site layout.
### Manual Setup
#### Requirements
- Python 3.9+
- Hugo (installed and in PATH)
#### Steps
1. Clone the repository:
```bash
git clone https://github.com/Svtter/hugo-admin.git
cd hugo-admin
```
2. Install dependencies:
```bash
pip install .
```
3. Configure the application:
```bash
cp config.py config_local.py
# Edit config_local.py to set your Hugo root directory
```
4. Run the application:
```bash
python app.py
```
5. Open your browser and navigate to `http://127.0.0.1:5050`
## Configuration
Edit `config.py` or create `config_local.py` to customize:
```python
# Hugo root directory (parent of content/)
HUGO_ROOT = '/path/to/your/hugo/site'
# Content directory
CONTENT_DIR = HUGO_ROOT + '/content'
# Hugo server settings
HUGO_SERVER_PORT = 1313
HUGO_SERVER_HOST = '127.0.0.1'
```
## Usage
### Dashboard
- View blog statistics (post count, tags, categories)
- Check Hugo server status
- Quick access to common operations
- Recent posts overview
### Post Management
- Browse all posts with pagination
- Search posts by title, content, tags, or categories
- Filter by specific category or tag
- Click any post to edit
### Editor
- Edit Markdown files with syntax highlighting
- Auto-save on changes
- Keyboard shortcut: `Ctrl+S` / `Cmd+S` to save
- Real-time save status indicator
### Server Control
- Start Hugo server (with or without drafts)
- Stop running server
- View server status (PID, uptime, CPU, memory)
- Real-time log streaming
## Development
### Running Tests
```bash
# Install dev dependencies
pip install -r requirements-dev.txt
# Run all tests
pytest
# Run with coverage
pytest --cov=. --cov-report=html
```
### Project Structure
```
hugo-admin/
βββ app.py # Flask application
βββ config.py # Configuration
βββ pyproject.toml # Dependencies and project metadata
βββ Dockerfile # Docker image build
βββ docker-compose.yml # Docker Compose configuration
βββ pytest.ini # Pytest configuration
βββ services/ # Business logic
βββ routes/ # Flask Blueprints (API routes)
βββ frontend/ # React + Vite SPA
βββ tests/ # Test suite
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## Security
- **Login required**: every `/api/*` endpoint and the SocketIO realtime channel are gated behind a password-authenticated session; unauthenticated requests get `401`.
- On first start a default `admin`/`admin` account is created β set `ADMIN_USERNAME`/`ADMIN_PASSWORD` (or change the password in-app) before exposing the service.
- Passwords are stored only as salted hashes (`werkzeug.security`); credentials live in `data/auth.json` and are never committed. A corrupt/unreadable credential file fails closed (startup aborts) rather than silently resetting the admin.
- File operations are restricted to the `content` directory, with path-traversal protection.
- Set a strong `SECRET_KEY` in production and keep the service on a trusted network or behind a reverse proxy.
## Roadmap
- [x] Basic framework
- [x] Hugo server control
- [x] Post browsing and search
- [x] Markdown editor
- [x] Markdown preview
- [x] SQLite caching system
- [x] Test suite with CI/CD
- [x] Image upload and management
- [x] Docker support
- [x] Git operations interface
- [x] Password-based admin login
- [ ] Batch operations
- [ ] Multi-user support
## License
Apache License 2.0 - see [LICENSE](LICENSE) file for details
## Acknowledgments
Built with β€οΈ for the Hugo community.