Publishing a trail means putting your files on the internet so that anyone with a smartphone and a web address can open it. The method we recommend — GitHub Pages — is completely free, handles any amount of visitors, and gives your trail a permanent web address that won't disappear. This chapter walks through every step. Allow about 30 minutes the first time.
Before you start
Read this chapter through once before doing anything — it's quicker to understand the whole process first than to follow steps blindly and get confused halfway through. Then come back to the top and work through it step by step.
You'll need the following things ready before you begin:
- Your trail files — the complete folder containing your trail app, GeoJSON file, config file, images, and audio (if any). See the file structure section below.
- A computer — a laptop or desktop running Windows, Mac, or Linux. A tablet or phone is not suitable for the upload steps.
- A web browser — Chrome or Edge work best for the file upload step. Firefox also works. Safari on Mac is fine.
- An email address — to create your GitHub account. Using a shared group email (such as your society's info@ address) is recommended so others can take over the account if needed.
What is GitHub Pages?
GitHub is a website used by software developers to store and share code. It is owned by Microsoft and used by millions of organisations worldwide, including the BBC, the NHS, and most major technology companies. It is not going anywhere.
GitHub Pages is a feature of GitHub that turns a folder of files into a live website — for free, with no monthly fees, no adverts, and no limit on how many people visit. The Heritage Trail app is a set of files (HTML, JavaScript, images, audio) that work perfectly as a GitHub Pages site.
Your trail will get a permanent web address in the format:
For example, a group called Olney Heritage Society publishing a trail called the Cowper Walk might have the address olneyheritage.github.io/cowper-walk/. That address is permanent — it won't change unless you delete the repository.
Getting your files ready
Before uploading, make sure your trail folder is complete and correctly structured. GitHub is not forgiving of missing files or incorrect paths — if a file is in the wrong place, images won't load and audio won't play.
Your trail folder should look like this:
The yellow files are required — the trail will not work without them. The blue files are optional — only include them if your trail uses images or audio at each stop.
Splash.jpg and splash.jpg are treated as different files. If your config.js or GeoJSON refers to images/splash.jpg but the file is named Splash.jpg, the image won't appear. Use lowercase throughout — it avoids all of these problems.
Step 1 · Create a GitHub account
If you already have a GitHub account, skip to Step 2.
Open github.com in your browser and click the Sign up button.
You'll need an email address, a username, and a password. The username becomes part of your trail URL, so choose something that represents your group: olneyheritage, stonyhistory, mkcanalsociety. No spaces are allowed — use hyphens if needed.
GitHub sends a verification email. Click the link in it to confirm your account before continuing.
When asked to choose a plan, select Free. You don't need any paid features. Everything in this guide works on the free plan.
Step 2 · Create a repository
A repository is GitHub's name for a folder. Each trail gets its own repository. The repository name becomes part of your trail's URL, so choose something short and descriptive.
When logged in to GitHub, look for a + icon near the top-right of the page. Click it and choose New repository from the menu.
This name appears in your trail URL. Keep it short, lowercase, and use hyphens instead of spaces: village-trail, cowper-walk, canal-history. Avoid anything too generic — if you plan multiple trails, you'll want names that distinguish them.
Make sure the repository is set to Public. This is required for the free GitHub Pages hosting. It means the files in your repository are visible to anyone who looks — which is fine, since the trail itself is intended to be public.
Leave all other settings as they are — do not tick "Add a README file" or anything else. Click the green Create repository button.
Step 3 · Upload your files
Now you'll upload your trail files. GitHub lets you do this directly in the browser — no software to install.
On the empty repository page, you'll see some introductory text. Look for the link that says uploading an existing file and click it. This opens the upload page.
Open File Explorer (Windows) or Finder (Mac) and navigate to your trail folder. You want to see the contents of the folder — the files and subfolders inside it — not the folder itself.
Select all files and folders inside your trail folder (Ctrl+A on Windows, Cmd+A on Mac), then drag them into the large upload area on the GitHub page. Wait for all items to appear in the list below the upload box — this can take a minute if you have many photos.
If dragging doesn't work, click the choose your files link instead and select them manually. Note that some browsers handle folder uploads differently — Chrome and Edge work most reliably.
Scroll down past the file list. You'll see a section called Commit changes. You can leave the message box as it is — GitHub fills in a default. Click the green Commit changes button.
GitHub saves all your files. This may take a minute or two if you have many images or audio files.
images/ or audio/ subfolders, try a different approach: upload the main files first, then use the Add file → Upload files button within the repository to upload the subfolder contents separately. You can create the folder structure by typing the folder name followed by a forward slash at the start of the filename — for example, typing images/ before a filename tells GitHub to put it in an images subfolder.
Step 4 · Turn on GitHub Pages
This single step is what turns your repository from a folder of files into a live website.
Near the top of your repository page, click the Settings tab. It has a cog icon and is near the right-hand end of the tab row.
In the left-hand settings menu, scroll down until you see Pages under the "Code and automation" section. Click it.
Under the Source heading, click the dropdown and select Deploy from a branch.
Two further dropdowns appear. Set the first to main and the second to / (root). Then click Save.
GitHub now builds your site. This takes between one and three minutes. You can move on to the next step while it works — the URL will be ready by the time you need it.
Step 5 · Find your trail URL
Once GitHub has built your site, your trail is live. The address follows this pattern:
So if your GitHub username is olneyheritage and your repository is called cowper-walk, your trail address is https://olneyheritage.github.io/cowper-walk/
Go back to Settings → Pages. Once the site is built, a blue banner appears saying "Your site is live at…" with a Visit site button. Click it to confirm it works.
Open the URL on a smartphone — not a desktop browser. GPS and geolocation only work on phones, and auto-play audio behaviour differs between desktop and mobile. Walk to the start of your trail and confirm that the splash screen loads, the map shows the correct location, and the first stop triggers when you approach it.
Write down or copy the full URL. You'll need it for the QR poster, your society's website, and any printed materials. The URL is permanent — it won't change as long as the repository exists.
Step 6 · Make a QR code poster
Now that you have a URL, you can generate a QR code poster — the physical sign that directs visitors to the trail. The Heritage Trail QR poster maker creates a print-ready poster with your trail name, a description, and a large QR code that visitors scan to open the trail on their phone.
Enter the full GitHub Pages URL in the trail address field. The QR code generates automatically. Check that it scans correctly by pointing your phone's camera at the screen.
Add your trail name, the name of your group, and a one or two sentence description. Choose a poster style that suits your trail's character.
Click Download poster (PNG) to save a print-ready file. Print on A4 paper at 100% scale. For outdoor use, laminate the poster after printing — a standard A4 laminating pouch costs around £1 and makes the poster weatherproof. Put it up at your trail's starting point.
Using your own hosting
If your society already has a website with a web hosting package, you can host the trail on that server instead of using GitHub Pages. This gives you more control over the URL and keeps everything under your existing hosting account. You'll need to be comfortable using an FTP or SFTP program — or have a volunteer who is.
What you'll need
- Web hosting that serves static files — almost any shared hosting package does this. If your society website is on WordPress, Wix, or a similar platform, check with your host whether you can also host static files in a separate folder.
- HTTPS enabled on the server — this is essential. The trail's GPS features will not work on phones unless the site is served over a secure HTTPS connection. Most modern hosting packages include a free SSL certificate (Let's Encrypt). If you're unsure, ask your web host.
- FTP or SFTP access — your hosting provider will have given you FTP credentials (a hostname, username, and password) when you signed up. SFTP is the secure version and is preferred where available.
- FileZilla — a free FTP/SFTP client for Windows and Mac. Download it from filezilla-project.org. Always download from the official site.
Getting the trail app files
Download the Heritage Trail starter pack — a ZIP file containing the trail app (index.html, sw.js, manifest.json) along with a placeholder config.js and an empty trail folder structure. The download link is on the toolkit homepage.
Unzip the starter pack on your computer. You'll see a folder containing the app files. Add your own files into the correct places:
Replace the placeholder config.js with your own from the config editor. Add your trail.geojson from the map editor. Put your images in the images/ folder and your audio files (if any) in the audio/ folder.
Uploading with FileZilla
In FileZilla, go to File → Site Manager and click New site. Enter your hosting provider's FTP hostname (something like ftp.yourdomain.org.uk), your FTP username, and your FTP password. Set the protocol to SFTP if your host supports it, otherwise use FTP. Click Connect.
The right-hand panel in FileZilla shows your server's files. Navigate to the folder that is publicly accessible on the web — this is usually called public_html, www, or htdocs. If you're not sure which folder to use, ask your web host.
Right-click in the right-hand panel and choose Create directory. Name it the same as your trail — for example cowper-walk. Lowercase, no spaces. This folder name becomes part of your trail's URL: yourdomain.org.uk/cowper-walk/
In the left-hand panel (your computer), navigate to your trail folder. Select everything inside it — all files and the images/ and audio/ subfolders. Drag them into the new folder on the right-hand panel (your server). FileZilla uploads everything, including the subfolders.
With many photos or audio files this may take a few minutes. The status bar at the bottom shows progress.
Open a browser and go to your trail's URL — for example https://yourdomain.org.uk/cowper-walk/. The trail splash screen should load. If you see a blank page or an error, check that index.html is in the folder (not inside a subfolder of it) and that HTTPS is working.
Updating on your own server
To update the trail, edit the relevant file on your computer, then reconnect in FileZilla and drag the new version into the same folder on the server. FileZilla will ask whether to overwrite the existing file — click Overwrite. Updates appear immediately, with no rebuild delay.
Updating your trail
Once the trail is live, you can update it at any time — to correct a mistake, add a new stop, change a photograph, or update a description. The process is simple: change the relevant file on your computer, then upload the new version to GitHub.
Edit your trail.geojson in the map editor, update config.js in the config editor, or replace an image file. Save the updated file to your computer.
Go to your repository on GitHub. If it's a single file (like trail.geojson), click on the filename, then click the pencil edit icon, then look for the option to upload a replacement. Alternatively, drag the new file onto the repository's main page and commit it — GitHub will replace the old file automatically if it has the same name.
GitHub rebuilds the site automatically. The live trail updates on its own — you don't need to do anything else. Check the live trail on your phone after a minute or two to confirm the update has appeared.
Troubleshooting
Here are the most common problems groups encounter when publishing for the first time, and what to do about them.
| Problem | What to check |
|---|---|
| The site shows a 404 error | Wait five minutes — GitHub Pages can take a few minutes to go live the very first time. Also check that index.html is in the root of the repository, not inside a subfolder. If you see a list of files rather than the trail app, the index.html is in the wrong place. |
| Photos aren't loading | Check that the filenames in your GeoJSON exactly match the filenames you uploaded — including uppercase and lowercase letters. Also check that the path in the GeoJSON starts with images/ and matches the folder name exactly. |
| The map shows the wrong location | Check the centerLat and centerLng values in your config.js. In the UK, latitude is a number around 51–53 and longitude is a number between roughly -5 and +2. They may have been accidentally swapped. Use the config editor to regenerate the file. |
| GPS doesn't trigger stops | GPS only works on phones, not desktop computers. Test outside on an actual phone. If stops still don't trigger, check the defaultRadius in config.js — it may be set too small. Try increasing it to 20 or 30 metres. |
| Audio doesn't play automatically | Many phone browsers block auto-play until the visitor has tapped somewhere on the page first. A play button appears instead. This is a browser security feature, not a fault in the trail. Most visitors understand what a play button is. |
| Changes aren't appearing after an update | GitHub Pages can take one to two minutes to rebuild after a commit. Wait a moment, then do a hard refresh on your phone (pull the page down firmly to force a reload). If changes still don't appear after five minutes, check that you committed the changes — look in the repository to confirm the file was updated. |
| The trail works on wifi but not mobile data | This usually means one or more files are large — typically a high-resolution image. Check that all images are under 200KB. Use Squoosh to compress any that are over this size. |
Publishing checklist
Work through this before telling anyone the trail is live.
- All required files present — index.html, config.js, trail.geojson, manifest.json, sw.js
- All filenames lowercase — no spaces, no special characters
- Images under 200KB each — compressed using Squoosh if needed
- GitHub account created — using a group email address, credentials stored safely
- Repository created and set to Public
- All files uploaded and committed
- GitHub Pages turned on — source set to main branch, root folder
- Trail URL confirmed — site loads in browser
- Tested on a phone outdoors — map correct, stops trigger, images load, audio plays
- Tested on mobile data — not just wifi
- QR poster downloaded and printed
- Poster put up at the trail starting point
- Trail URL shared with your society and on your website