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
2 changes: 0 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,6 @@ jobs:

- uses: jdx/mise-action@v4

- run: bundle install

# -c keeps going after a failure so one run shows every problem.
- name: Check
env:
Expand Down
13 changes: 4 additions & 9 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,15 +1,10 @@
# Jekyll build output and caches
_site
.jekyll-cache
.jekyll-metadata

# Bundler
.bundle
vendor/bundle
# Hugo build output and its cache
public
resources
.hugo_build.lock

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

# macOS
Expand Down
4 changes: 2 additions & 2 deletions .markdownlint-cli2.yaml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
ignores:
- "_site/**"
- "vendor/**"
- "public/**"
- "resources/**"
- ".claude/**"
- "CLAUDE.md" # import shim (@AGENTS.md), not prose
2 changes: 1 addition & 1 deletion .markdownlint.yaml
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
MD013: false # line-length
MD025: false # single-title/single-h1: Jekyll pages put the title in front matter
MD025: false # single-title/single-h1: pages put the title in front matter
MD033: false # no-inline-html: pages embed images, video and badges as HTML
22 changes: 10 additions & 12 deletions .mise.toml
Original file line number Diff line number Diff line change
@@ -1,20 +1,17 @@
[tools]
# Cloudflare Pages build image v3 preinstalls 3.4.4; any other version
# compiles from source on every build. See AGENTS.md before changing.
ruby = "3.4.4"
# Cloudflare Pages reads HUGO_VERSION from the project's settings: change both
# together. See AGENTS.md.
hugo = "0.167.0"
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"
lychee = "0.24.2"

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

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

[tasks.spell]
run = "cspell lint --no-progress ."
Expand All @@ -24,11 +21,12 @@ 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.
# Internal links and images only. External sites rate-limit and flake; check
# them by hand with `lychee public` when it matters. Links leave off .html, as
# Cloudflare serves /privacy.html at /privacy.
[tasks.links]
depends = ["build"]
run = "htmlproofer _site --disable-external --no-check-internal-hash"
run = "lychee --offline --no-progress --fallback-extensions html --root-dir \"$PWD/public\" 'public/**/*.html'"

[tasks.check]
depends = ["spell", "markdownlint", "links"]
Expand Down
44 changes: 24 additions & 20 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,39 +7,35 @@ 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
eBird data, live at [birdsnearme.com](https://birdsnearme.com). A Hugo 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.
Keep it minimal. Don't add a theme, Hugo modules, pages or build steps unless asked. Every
template is in `layouts/`.

## Commands

```sh
mise run install # bundle install
mise run dev # serve on :4002 with livereload
mise run dev # hugo server on :4002 with live reload
mise run check # build + spell + markdownlint + internal links
mise run deploy # guard, check, push, wait for Pages, verify
mise run verify # curl the live site
mise run deploy-status # is main live?
```

**Read the counts, not just the exit code.** html-proofer prints `Ran on N files` and cspell
**Read the counts, not just the exit code.** lychee prints `N OK` 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.

Ruby stays on 3.4.4 because build image v3 preinstalls it. Any other version compiles
from source and adds about 3 minutes to every build. `Gemfile` and `Gemfile.lock` are
identical across the five Jekyll sites (gshaw.ca, LandNav, AEDSim, Birds Near Me,
weisearts.com): change them in one, then copy both files to the others.
<!-- cspell:ignore weisearts gshaw -- the sibling sites' domains -->
production; other branches get a preview URL. The build runs
`hugo --cleanDestinationDir --panicOnWarning` into `public/`, with `HUGO_VERSION` set in the
Cloudflare project for production and preview, so a Hugo bump means changing `.mise.toml`
and that variable together. `--panicOnWarning` makes a deprecation fail the build rather
than scroll past.

**Deploy with `mise run deploy`**, never a bare `git push` to `main`.
`scripts/deploy-guard.sh` refuses unless the branch is `main`, the tree is clean and
Expand All @@ -52,13 +48,21 @@ GitHub Actions runs `mise run -c check` on pushes and PRs. It doesn't block Clou

## Layout

- `_config.yml` holds the site name, description, icon, copyright start year and author.
- `hugo.toml` 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.
- `layouts/baseof.html` is the page shell. `layouts/_partials/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.
- `content/`: `_index.md` (the home page), `support.md`, `privacy.md`, `404.md`.
`uglyURLs` keeps pages at `/privacy.html`, as before; Cloudflare serves them at
`/privacy`, the canonical URL.
- `static/` is published as it is: icons, the QR code, screenshots, and `pico.min.css`,
Pico 1.5 copied in rather than loaded from a CDN.
- `public/` is build output; it's gitignored.

Hugo doesn't run template code inside Markdown files: a loop over data goes in a
shortcode in `layouts/_shortcodes/`. A link with spaces needs angle brackets:
`[text](<mailto:x?subject=A B>)`, and a blank line inside a raw HTML block ends it.

## Writing

Expand Down
10 changes: 0 additions & 10 deletions Gemfile

This file was deleted.

172 changes: 0 additions & 172 deletions Gemfile.lock

This file was deleted.

7 changes: 3 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,8 @@
## Develop

```sh
mise install # Ruby, Node, cspell, markdownlint, html-proofer
mise run install # bundle install
mise run dev # http://localhost:4002 with livereload
mise install # Hugo, Node, cspell, markdownlint, lychee
mise run dev # http://localhost:4002 with live reload
mise run check # build, spell check, markdown lint, internal links
```

Expand All @@ -18,5 +17,5 @@ Deploy with `mise run deploy`. It refuses unless you're on a clean `main` with n
- Domain Registrar: [Cloudflare Registrar](https://www.cloudflare.com/products/registrar/)
- DNS: [Cloudflare DNS](https://www.cloudflare.com/dns/)
- Hosting: [Cloudflare Pages](https://pages.cloudflare.com)
- Build System: [Jekyll](https://jekyllrb.com)
- Build System: [Hugo](https://gohugo.io)
- CSS: [Pico.css](https://picocss.com)
Loading
Loading