Development environment

This repository has two local toolchains:

  • Python and trail-data tooling, managed by uv
  • The GitHub Pages site, built with Ruby and Jekyll

Prerequisites

Install:

  • uv
  • Python 3.9 or newer
  • Ruby
  • Ruby development headers and native build tools

On Debian or Ubuntu:

sudo apt-get update
sudo apt-get install -y ruby-dev build-essential

Python setup

Create the locked environment:

uv sync

Run all tests:

uv run pytest

Dependencies are declared in pyproject.toml and locked in uv.lock. Do not install them globally.

Ruby and Jekyll setup

The required Bundler version is recorded at the end of Gemfile.lock.

This machine may have an unrelated Go executable named bundle. Confirm before using it:

bundle --version

It must identify itself as Bundler. If it does not, install and invoke Ruby Bundler explicitly. A repository-local installation can be used from vendor/bundle; the verified executable in this checkout is:

vendor/bundle/ruby/3.2.0/bin/bundle install
vendor/bundle/ruby/3.2.0/bin/bundle exec jekyll build

The Ruby minor-version directory may differ on another machine.

Development API keys

Copy the ignored override:

cp _config_dev.yml.template _config_dev.yml

Add development-only values:

google_api:
  maps_key: "YOUR_DEV_MAPS_API_KEY"
  weather_key: "YOUR_DEV_WEATHER_API_KEY"

Confirm it stays ignored:

git check-ignore _config_dev.yml

Browser-visible production keys must have both website-referrer and API restrictions in Google Cloud.

Build and serve

Production-equivalent build:

<ruby-bundle> exec jekyll build

Development server with local API overrides:

<ruby-bundle> exec jekyll serve \
  --config _config.yml,_config_dev.yml \
  --host 127.0.0.1 --port 4000

Open http://127.0.0.1:4000/trails/.

Complete verification

Run the tests and build:

uv run pytest
jq empty trails/bay_area_trails.json
jq empty _data/trails/bay_area_trails.json
git diff --check
<ruby-bundle> exec jekyll build

Then confirm:

  • _site/trails/index.html exists;
  • _site/trails/bay_area_trails.json parses with jq;
  • opening one trail marker closes the previous popup;
  • trail links use https://www.alltrails.com/trail/us/california/<slug>;
  • the Lower Meadow trail points to:
https://www.alltrails.com/trail/us/california/lower-meadow-trail-to-farm-bypass-loop

Do not commit _config_dev.yml, .venv/, _site/, .bundle/, or vendor/bundle/.