Skip to main content
Puerto Rican Genealogy Conectando Raíces, Celebrando Herencia

CLAUDE.md — Puerto Rican Genealogy Group Website

This file provides focused context for Claude Code when working inside the puertoricangenealogygroup/ directory.

Site Identity

Session Start Protocol

At the start of every session and at the top of every planning or processing block, state the current date and time.

Format: Session: YYYY-MM-DD HH:MM (local time)

Build & Serve

# Position in the correct directory
cd /Users/sylviavargas/Documents/GitHub/Claude/puertoricangenealogygroup
rm Gemfile.lock 

# First time or after dependency changes:
bundle install

# Local dev server:
bundle exec jekyll serve
# → http://localhost:4000

# If bundle install fails: delete Gemfile.lock and retry

Bilingual Update Rule (CRITICAL)

Every content change must be applied to BOTH languages. When you change an English page, also update its Spanish counterpart:

English path Spanish counterpart
page.md (root) es/page.md
_research-guides/guide-name.md _research-guides/es-guide-name.md
research-guides.md es/guias-investigacion.md

Frontmatter pairing: both files must share the same ref: value. The lang: field must be en or es.

Section-level parity required: Updating a Spanish counterpart file is not enough — every ## and ### section in the EN file must exist (translated) in the ES file. After editing any research guide, run the parity check from puertoricangenealogygroup/:

bash check-bilingual-parity.sh

This script compares heading counts between every EN/ES pair and flags gaps. Fix any reported gaps before marking the task done.

bash ../scripts/check-site.sh runs this parity check as row 1.2 along with ten other checks, so prefer that as the single entry point. See root CLAUDE.md under “Testing Website Changes”.

All external HTTP/HTTPS links in .md files must use this HTML format — never plain markdown [text](url):

<a href="URL" target="_blank" rel="noopener noreferrer"><em>Link Text</em></a>

To add a page to the site menu, edit _config.yml and add entries to both navigation.en and navigation.es:

navigation:
  en:
    - title: Page Title
      url: /page-url/
  es:
    - title: Título de Página
      url: /es/url-de-pagina/

Layouts & Collections

Layout Used for Path pattern
default Home page, bare pages any .md at root or es/
page Standard content pages with title header + breadcrumb layout: page in frontmatter
guide Research guide modules _research-guides/*.md (auto-applied)
resource Resource pages _resources/*.md (auto-applied)
municipality Municipality detail pages _municipalities/*.md (auto-applied)

Research guides output at /research-guides/:name/; resources at /resources/:name/. Municipality pages output at /tools/municipality-guide/:name/ (EN) or explicit permalink: in frontmatter (ES, e.g., /es/guia-municipios/san-german/).

CSS & Styling

Logo Usage

Frontmatter Template

---
layout: page
title: "Page Title"
description: "Brief description for SEO."
lang: en          # or es
ref: page-ref     # shared between EN and ES versions for language switcher
permalink: /url/  # required for non-collection pages
---

File Conventions

Copyright is managed centrally via _config.yml fields. Do not hardcode author name, trademark, or year range in templates.

_config.yml copyright fields:

author:
  name: "Sylvia Vargas"
  url: "https://looking4myroots.com"
copyright_year_start: "2024"
trademark: "Teaching Genealogists AI™"

Template variables:

Variable Value
Sylvia Vargas Sylvia Vargas
https://looking4myroots.com https://looking4myroots.com
2024 2024
Teaching Genealogists AI™ Teaching Genealogists AI™

Where copyright appears:

Municipality Data Integrity (_data/pr-municipalities.json)

mother_town must never be an empty array.

Every entry must have at least one value. The Mother-Town Relationships tree on the website is built entirely from this field; an empty array silently drops that municipality and all its descendants from the tree.

Value When to use
["Original Settlement"] Only for the three original Spanish settlements: San Juan (1521), San Germán (1573), Arecibo (1616).
["Town A"] Municipality split from one earlier town.
["Town A", "Town B"] Municipality split from two earlier towns.

To find the correct parent town: look at the founding year and cross-reference with neighboring municipalities that were founded earlier. If uncertain, check the Notas para su Historia for that municipality.

Before saving any new or updated entry, verify:

assert m["mother_town"] != [], f"{m['name']} has empty mother_town"

Municipality Images

Coat of arms and historical map images follow a strict naming convention. Full details in prgg-admin/ideas/municipality-pages/CONVENTIONS.md.

Folders:

Naming format: [municipality-id]-[year].[ext]

Examples: san-german-1574.svg, ponce-unknown.jpg

Before placing any image: verify the license on Wikimedia Commons manually (automated access returns 403). Update the escudo.license and escudo.attribution_url fields in _data/pr-municipalities.json.

Before Completing Any Website Change

Verify every internal link in new or modified files before finishing. For each internal href (relative path or absolute path starting with /):

  1. Resolve the target: check permalink: in the matching .md file or _research-guides//_resources/ collection file.
  2. Confirm the file exists in the repo. If not, find the correct permalink and fix the link.
  3. Spanish pages must link to Spanish permalinks (e.g., /es/guias-investigacion/... not /research-guides/...).

Common broken-link patterns to watch for:

External links do not need verification during editing (they change without notice), but must follow the <a href="..." target="_blank" rel="noopener noreferrer"><em>text</em></a> format.

Required Verification — Before Marking Any Task Done

This is mandatory. Do not report a task complete without running these steps.

  1. Start the Jekyll server (from puertoricangenealogygroup/):

    bundle exec jekyll serve
  2. Visit the affected page(s) at http://localhost:4000
  3. Confirm the change is correct and nothing is visually broken
  4. Visit the Spanish counterpart and confirm parity
  5. Resize to mobile width (~375px) if the change is CSS or layout

Full per-type checklists are in prgg-admin/FAQ.md under “Verification & Testing”.

After Every Website Change

Append an entry to ../prgg-admin/CHANGELOG.md:

## YYYY-MM-DD
- File(s) changed: ...
- What changed and why: ...

No exceptions.

What’s New — Required Update (Required)

Any new page, new feature, or significant enhancement must be added to both news files before the session ends:

What counts as a What’s New entry:

Entry format:

- date: YYYY-MM-DD
  category: features        # features | courses | guides
  featured: true            # true for ONE entry at a time — demote the previous featured to false
  title: "New: Short Title"
  body: "1-2 sentences describing what was added and why it matters to researchers."
  link: /internal/path/

Spanish entry rules:

No exceptions. If you add a municipality page, guide, tool, or enhancement and do not update these files, the session is incomplete.

Key File Paths

File Purpose
_config.yml Site config, navigation, collections, defaults
_includes/header.html Site header, nav, search
_includes/footer.html Site footer
_includes/head.html <head> tag, fonts, SEO
assets/css/style.css All CSS styles
assets/js/main.js Site-wide JS (search, nav, smooth scroll)
search.json Client-side search index generator
_data/ YAML/JSON data files (news, municipalities, funeral cards)
assets/images/ Site images and logos
assets/pdfs/ PDF course materials
copyright.md English copyright and terms of use page (/copyright/)
es/derechos-de-autor.md Spanish copyright and terms of use page (/es/derechos-de-autor/)
privacy-policy.md English privacy policy page (/privacy-policy/)
es/politica-de-privacidad.md Spanish privacy policy page (/es/politica-de-privacidad/)