A modern cycling blog built with Kirby CMS, featuring interactive maps, GPX track visualization, and photo galleries with GPS integration.
- Adventure Posts: Create detailed cycling adventure posts with ride statistics
- GPX Track Integration: Automatically extract ride statistics from GPX files
- Interactive Maps: Display routes on interactive Leaflet maps
- Photo Mapping: Photos with GPS EXIF data are automatically placed on the map
- Flexible Content: Use blocks to arrange text and images differently for each post
- Responsive Design: Built with Tailwind CSS for all screen sizes
- Git Version Control: Manage your site code with Git/GitHub
- FTP Deployment: One-command deployment to any PHP hosting via
deploy.sh(lftp)
cycling-adventures/
├── assets/
│ ├── css/ # Compiled CSS (generated, not in git)
│ ├── scss/ # Source SCSS files
│ └── js/ # JavaScript files
│ ├── adventure-map.js # Map initialization
│ └── vendor/ # Third-party libraries (Leaflet.js)
├── content/ # Your adventure content (not in git by default)
│ ├── home/ # Homepage
│ └── adventures/ # Adventure posts
├── kirby/ # Kirby CMS core files
├── site/
│ ├── blueprints/ # Content structure definitions
│ ├── config/ # Site configuration
│ ├── plugins/ # Custom plugins (GPX/EXIF helpers)
│ ├── snippets/ # Reusable template parts
│ └── templates/ # Page templates
├── package.json # Node.js dependencies and build scripts
├── deploy.sh # FTP deployment script (see Deployment section)
├── deploy.conf.example # Template for deploy.sh credentials
├── deploy.conf # Your real FTP credentials (gitignored, not in git)
└── README.md # This file
- PHP 8.0+ (for local development and server)
- Node.js 16+ and npm (for building CSS)
- Git (for version control)
- lftp (for deployment via
deploy.sh) — install withbrew install lftp
git clone <your-repo-url> cycling-adventures
cd cycling-adventuresnpm installThis will install:
- Tailwind CSS
- Sass compiler
- PostCSS with Autoprefixer
Build the CSS files from SCSS source:
npm run buildFor development with auto-rebuild on changes:
npm run devThe Kirby Panel is where you'll create and manage your adventures.
- Start a local PHP server:
php -S localhost:8000 kirby/router.php-
Open http://localhost:8000/panel in your browser
-
Create your admin account:
- Email: your@email.com
- Password: (choose a strong password)
- Language: English
Edit site/config/config.php:
- Change
'debug' => trueto'debug' => falsefor production - Update
'url'to your production URL
-
Navigate to "Adventures"
-
Click "+ Add" to create a new adventure
-
Fill in the fields:
- Title: Name of your ride
- Date: When the ride took place
- Description: Brief summary (shown on homepage)
- GPX File: Upload your .gpx track file
- Photos: Upload photos from the ride
- Ride Statistics: Auto-filled from GPX, or enter manually
- Content Layout: Use blocks to tell your story
-
Click "Save" and then "Change status" → "Published"
- Export GPX files from Strava, Komoot, Garmin Connect, etc.
- The system will automatically extract:
- Total distance
- Elevation gain
- Duration
- Average speed
- Track points for map visualization
- Photos with GPS EXIF data will be placed on the map automatically
- Photos without GPS will be matched to track points by timestamp
- For best results, ensure your camera/phone has GPS enabled
- Recommended formats: JPG with EXIF data
- Start PHP server:
php -S localhost:8000 kirby/router.php- In another terminal, watch for CSS changes:
npm run dev- Open http://localhost:8000 in your browser
- Edit templates, styles, or content
- Refresh browser to see changes
Before deploying, always build production CSS:
npm run buildThis creates minified CSS in assets/css/style.css.
Deployment is handled by deploy.sh, which builds the CSS, patches a copy of
site/config/config.php for production, and syncs only new/changed files to
your server over FTP with lftp mirror --only-newer. Your local
site/config/config.php is never modified — it stays on debug: true and
your local URL.
- Install
lftp:
brew install lftp- Create your deploy config from the example:
cp deploy.conf.example deploy.conf- Edit
deploy.confand fill in your details:
FTP_HOST=ftp.yourhost.com
FTP_USER=your-ftp-username
FTP_PASS=your-ftp-password
FTP_PORT=21
REMOTE_PATH=/httpdocs # path on the server where index.php lives
PRODUCTION_URL=https://www.yourdomain.comdeploy.conf is gitignored — it holds real credentials and must never be committed.
./deploy.shThis will:
- Run
npm run buildto produce production CSS - Generate a temporary copy of
site/config/config.phpwithdebug => false,urlset toPRODUCTION_URL, and the licenseactiveflag turned on - Mirror
assets/(excludingassets/scss/),kirby/, andsite/(excludingcache/,sessions/,accounts/,config.php) to the server, uploading only files that are new or changed - Upload
index.php,.htaccess, and the patched productionconfig.php
Only the files the site actually needs to run are touched on the server —
node_modules/, .git/, README.md, composer.json, and other local-only
files are never synced.
First deployment only: content/ isn't uploaded by deploy.sh. Upload it
once manually via FTP, then manage content through the Panel on the server
from then on.
- Visit http://yourdomain.com/panel
- Log in with your admin credentials
- If this is first deployment, create your account
- Start creating adventures!
-
deploy.confis set up (one-time) - Run
./deploy.sh - First deployment only: upload
content/manually via FTP - Check file permissions (see below)
- Test the site in a browser
- Test the Panel at /panel
On your server, these directories need write permissions (usually 755 or 775):
chmod 755 content/
chmod 755 media/
chmod 755 site/accounts/
chmod 755 site/cache/
chmod 755 site/sessions/Edit tailwind.config.js to customize colors:
colors: {
'ride-primary': '#2563eb', // Links and track color
'ride-secondary': '#16a34a', // Elevation/success color
'ride-accent': '#ea580c', // Highlights
}Edit assets/scss/style.scss for custom styles.
After changes, rebuild:
npm run buildTemplates are in site/templates/:
home.php- Homepage with adventure listadventure.php- Single adventure pageadventures.php- Adventures parent page
Snippets (reusable parts) in site/snippets/:
header.php- HTML head and site headerfooter.php- Site footeradventure-card.php- Adventure card for list view
Content structure is defined in site/blueprints/pages/:
home.yml- Homepage fieldsadventures.yml- Adventures parentadventure.yml- Individual adventure fields
Edit these to add/remove fields in the Panel.
Edit assets/js/adventure-map.js to customize:
- Map tile provider (currently OpenStreetMap)
- Marker icons and colors
- Track line styling
- Popup content
- Make sure you ran
npm install - Run
npm run build - Check that
assets/css/style.cssexists
- Check
.htaccesswas uploaded (Apache) - Verify
site/config/config.phphas correct URL - Check PHP version (needs 8.0+)
- Verify photos have GPS EXIF data
- Check that GPX file has timestamps
- Photos will only appear if within 5 minutes of track time
- Verify GPX file is valid XML
- Check file uploaded correctly in Panel
- Ensure PHP has XML support enabled
Set correct permissions on server:
chmod -R 755 content/ media/ site/accounts/ site/cache/ site/sessions/# Development
npm run dev # Watch and rebuild CSS on changes
php -S localhost:8000 kirby/router.php # Start local PHP server
# Build
npm run build # Build production CSS
# Deploy
./deploy.sh # Build, patch config, and sync changed files to production via FTP
# Git
git status # Check what changed
git add . # Stage all changes
git commit -m "msg" # Commit changes
git push # Push to GitHub
git pull # Pull latest from GitHub- Kirby CMS - File-based CMS
- Tailwind CSS - Utility-first CSS framework
- Leaflet.js - Interactive maps
- Sass - CSS preprocessor
- PHP 8+ - Server-side language
- Git/GitHub - Version control
This project is open source and available under the MIT License.
For Kirby CMS questions: https://getkirby.com/docs For issues with this project: Check GitHub Issues
Built with Kirby CMS. Maps powered by Leaflet.js and OpenStreetMap.
Happy cycling! 🚴♂️