AGENTS.md

Project Overview

This repository is the Jekyll source for thebackcountrymom.com, a static blog based on the Norlin theme. Content is mostly Markdown posts and pages, with Liquid templates, Sass partials, YAML data files, JavaScript helpers, and image assets.

Common Commands

• make start: install bundle dependencies and run the site locally with bundle exec jekyll serve.
• make post: prompt for a post title, create a new post via jekyll-compose, install dependencies, and start the local server.
• make ship: deploy workflow. It pulls, regenerates tag pages, stages everything, commits, and pushes. Only run this when explicitly asked.
• bundle exec jekyll build: build the site without serving it. Use this as the default verification command for content/template/style changes when dependencies are available.
• python tag_generator.py: regenerate tag pages in tag/ from post and draft front matter. This deletes and recreates existing tag/*.md files.

The local site serves at http://127.0.0.1:4000/ by default.

Authenticated git and GitHub CLI (gh) access are available in this environment. Use them when needed for normal repository, pull request, and deployment workflows.

Repository Structure

• _posts/: blog posts in Jekyll date-title Markdown format.
• _pages/: standalone pages included by _config.yml.
• _layouts/: page, post, default, tag, and links layouts.
• _includes/: reusable Liquid partials, including head, header, footer, search, pagination, and widgets.
• _sass/: Sass settings, tools, modules, and layouts. The main include is _includes/main.scss.
• _data/: YAML-backed structured content used by posts and templates.
• images/: site images and post assets. Keep paths stable because posts reference them directly.
• tag/: generated tag pages. Prefer regenerating with python tag_generator.py instead of hand-editing generated tag files.
• js/: site JavaScript and vendored browser libraries.

Content Conventions

Posts should use front matter consistent with existing files:

---
layout: post
title:
description:
date:
image: '/images/posts/...'
tags:
permalink: /example-slug/
---

• Use layout: post for blog posts.
• Keep post image paths rooted from /images/....
• Tags are commonly written as a space-separated list, for example tags: backpacking kids gear.
• Keep permalinks trailing-slash style, for example /utah-winter-yurts/.
• Use _data/*.yml for large structured product lists or repeated content rather than embedding all data directly in templates.
• Some posts intentionally contain inline HTML and Liquid loops. Preserve those patterns unless the task asks for a refactor.

Style And Implementation Notes

• Match the existing Jekyll/Liquid, Sass, and Markdown style. Keep changes scoped.
• Avoid broad theme refactors for content updates.
• Use existing Sass partial organization:
  • _sass/0-settings/ for variables, helpers, and mixins.
  • _sass/1-tools/ for resets, grid, animation, syntax, and shared tooling.
  • _sass/3-modules/ for reusable UI modules.
  • _sass/4-layouts/ for page-specific layout styles.
• Do not edit vendored files under js/vendors/ unless specifically requested.
• Do not commit or rely on .DS_Store files.
• Be careful with _config.yml: changes require restarting the Jekyll server.

Verification

• For most code, template, Sass, and content changes, run bundle exec jekyll build if local Ruby dependencies are installed.
• For local visual checks, run make start or bundle exec jekyll serve and inspect http://127.0.0.1:4000/.
• If tags were changed or new tags were added, run python tag_generator.py and review the generated tag/ changes.

Deployment Guardrails

• This is a solo-developer site. Do not open pull requests for routine work in this repo.
• When the user asks to publish or push, push directly to main.
• Do not automatically push after making changes. Only push when the user explicitly asks.
• Do not run make ship or ship.sh unless the user explicitly asks to publish/deploy.
• ship.sh performs git pull, regenerates tags, stages all files, commits, and pushes. Check git status before using it.
• After any push to this repo, monitor the GitHub Pages deployment with gh until it succeeds or fails.
• If a deployment fails, investigate the failing check or workflow logs, explain the cause, and help implement a fix.
• Preserve unrelated user changes in the working tree. Do not revert files unless the user asks.