Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
name: CI

on:
push:
branches: [main]
pull_request:

jobs:
check:
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v6

- uses: jdx/mise-action@v4

- run: bundle install

# -c keeps going after a failure so one run shows every problem.
- name: Check
env:
MISE_TASK_OUTPUT: interleave
run: mise run -c check
15 changes: 15 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1 +1,16 @@
# Jekyll build output and caches
_site
.jekyll-cache
.jekyll-metadata

# Bundler
.bundle
vendor/bundle

# Editor and agent tooling
.vscode
.ruby-lsp
.claude

# macOS
.DS_Store
5 changes: 5 additions & 0 deletions .markdownlint-cli2.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
ignores:
- "_site/**"
- "vendor/**"
- ".claude/**"
- "CLAUDE.md" # import shim (@AGENTS.md), not prose
3 changes: 3 additions & 0 deletions .markdownlint.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
MD013: false # line-length
MD025: false # single-title/single-h1: Jekyll pages put the title in front matter
MD033: false # no-inline-html: pages embed images, video and badges as HTML
39 changes: 34 additions & 5 deletions .mise.toml
Original file line number Diff line number Diff line change
@@ -1,14 +1,43 @@
[tools]
ruby = "3.2.2" # Cloudflare Build System version 2 using Ruby 3.2.2
ruby = "4.0.7"
node = "24.4.1"
"npm:cspell" = "9.1.5"
"npm:markdownlint-cli2" = "0.22.1"
"gem:html-proofer" = "5.2.1"

[tasks.install]
run = "bundle install"

[tasks.dev]
run = "bundle exec jekyll serve --livereload --open-url --port 4002"
run = "bundle exec jekyll serve --livereload --livereload-port 35702 --open-url --port 4002"

[tasks.build]
run = "bundle exec jekyll build --quiet"

[tasks.spell]
run = "cspell lint --no-progress ."

[tasks.markdownlint]
run = """
out=$(markdownlint-cli2 '**/*.md' 2>&1) && echo "Markdown lint passed" || { echo "$out"; exit 1; }
"""

# Internal links only. External sites rate-limit and flake; check them by hand
# with `htmlproofer _site` when it matters.
[tasks.links]
depends = ["build"]
run = "htmlproofer _site --disable-external --no-check-internal-hash"

[tasks.check]
depends = ["spell", "markdownlint", "links"]

# Run after a deploy lands. Cloudflare Pages builds on push to main.
[tasks.verify]
run = """
curl -fsS https://birdsnearme.com/ | grep -q "<title>Birds Near Me" && echo "birdsnearme.com is up"
test "$(curl -s -o /dev/null -w '%{http_code}' https://birdsnearme.com/no-such-page/)" = 404 && echo "404 page works"
"""

[tasks.deploy]
depends = ["check"]
run = "git push"

[settings]
experimental = true
3 changes: 2 additions & 1 deletion 404.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
---
title: 404 Not Found
permalink: /404.html
---

You are at a page that doesn't exist.
You are at a page that doesn't exist. [Go home?](/)
67 changes: 67 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# Agent Notes

<!-- cspell:ignore birdsnearme -- the domain and Cloudflare Pages project name -->

Background for AI agents working in this repo.

## What this is

The marketing site for Birds Near Me, a worldwide birding field guide for iPhone built on
eBird data, live at [birdsnearme.com](https://birdsnearme.com). A Jekyll site on Cloudflare
Pages. The app itself lives in a separate repo, `BirdsNearMe`.

**The repo and the site are both public.** Anything committed here is published.

Keep it minimal. Don't add gems, plugins, pages or build steps unless asked.

## Commands

```sh
mise run install # bundle install
mise run dev # serve on :4002 with livereload
mise run check # build + spell + markdownlint + internal links
mise run verify # curl the live site after a deploy
mise run deploy # check, then git push
```

**Read the counts, not just the exit code.** html-proofer prints `Ran on N files` and cspell
prints `Files checked: N`. A green run over zero files checked nothing.

## Deploys

Cloudflare Pages project `birdsnearme-website` builds every push. `main` goes to
production; other branches get a preview URL. The build runs `bundle exec jekyll build`
with `RUBY_VERSION` set in the Cloudflare project, so a Ruby bump means changing `Gemfile`,
`.mise.toml` and that variable together.

GitHub Actions runs `mise run -c check` on pushes and PRs. It doesn't block Cloudflare.

## Layout

- `_config.yml` holds the site name, description, icon, copyright start year and author.
The layout reads them; don't hard-code them in HTML.
- `_layouts/page.html` is the only layout. `_includes/head.html` has the meta and Open Graph
tags; a page can override the description with `description:` and the preview image with
`ogimage:` in front matter.
- `index.md`, `support.md`, `privacy.md`, `404.md`.
- `pico.min.css` is Pico 1.5, copied in rather than loaded from a CDN.

## Writing

- Claims must match the released app on the App Store, not the rewrite in the app repo.
In September 2026 that was version 1.5 (March 2019), which needs iOS 10 or later. Update
`index.md` and `support.md` when a new version ships.
- The app's data comes from eBird, Flickr, Wikipedia and xeno-canto. Keep the
acknowledgements and the privacy policy in step with that list.

## Suppressions

Suppress a check inline, with a reason, in the file that provoked it:
`<!-- cspell:ignore word -->` or `<!-- markdownlint-disable-next-line MD0xx -->`. Move a
word to `cspell.config.yaml` only once a second file needs it.

## Branches, issues and PRs

- Branch names are flat and short: `<issue>-<slug>`, no `claude/` prefix.
- Issue and PR bodies aren't hard-wrapped.
- Squash-merge only.
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
@AGENTS.md
2 changes: 1 addition & 1 deletion Gemfile
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
ruby "3.2.2"
ruby "4.0.7"

source "https://rubygems.org"

Expand Down
Loading
Loading