remoteintech/remote-jobs

# CLAUDE.md

Repository context for AI agents (and humans) working on the codebase. For end-user contribution instructions, see [`CONTRIBUTING.md`](CONTRIBUTING.md).

## Project Overview

Remote In Tech is a community-maintained directory of remote-friendly tech companies. The site is built with [Eleventy](https://www.11ty.dev/) (v3) and deployed on Netlify.

**Live site:** https://remoteintech.company

## Directory Structure

```
src/
├── companies/          # Company profiles (Markdown with YAML frontmatter)
├── blog/               # Blog posts (Markdown)
├── pages/              # Static pages and dynamic templates (Nunjucks)
├── common/             # Shared templates (404, redirects, sitemap, feeds)
├── _layouts/           # Page layouts (base, page, post, company)
├── _includes/          # Partials, components, and WebC components
├── _config/            # Eleventy configuration (collections, filters, plugins)
├── _data/              # Global data files (navigation, meta, companyTags)
└── assets/             # Static assets (CSS, JS, fonts, images)

dist/                   # Build output (gitignored)
```

## Build Commands

```bash
npm run start           # Development server with hot reload
npm run build           # Production build (clean + eleventy + pagefind)
npm run build:11ty      # Eleventy build only (faster for testing)
npm run clean           # Remove dist and generated files
```

## Company Profiles

Companies are Markdown files in `src/companies/` with this frontmatter structure:

```yaml
---
title: "Company Name"
slug: company-slug                    # URL slug (required); must match the filename
website: https://example.com          # Main company website URL
careers_url: https://example.com/jobs # Optional: careers/jobs page URL
region: worldwide                     # worldwide, americas, europe, asia-pacific, americas-europe, other
remote_policy: fully-remote           # fully-remote, remote-first, remote-friendly, hybrid
company_size: startup                 # tiny, small, medium, large, enterprise
technologies:                         # Array of tech tags
  - javascript
  - python
  - devops
addedAt: 2024-03-15                   # Date first contributed (managed by maintainers)
updatedAt: 2025-06-20                 # Date of last real content change (managed by maintainers)
---
```

**URL fields:**

- `website` — Main company URL (used to verify the company, identify brand)
- `careers_url` — Optional careers/jobs page URL. When present, the "Apply Now" button links here; otherwise falls back to `website`

Valid technology tags are defined in `src/_data/companyHelpers.js` under `techLabels`. The validation script (`.github/scripts/validate-companies.js`) is the source of truth for required fields, allowed enum values, and required Markdown sections.

To add a company, see [`CONTRIBUTING.md`](CONTRIBUTING.md).

## Key Configuration Files

- `eleventy.config.js` — Main Eleventy config (imports from src/_config/)
- `src/_config/collections.js` — Company and blog collections
- `src/_data/companyHelpers.js` — Tech labels, region labels, featured companies
- `src/_data/companyTags.js` — Generates browse page tags with counts
- `src/_data/meta.js` — Site metadata (title, description, analytics)
- `src/common/_redirects.njk` — Netlify redirects (auto-generates company redirects)

## Coding Conventions

- **Templates:** Nunjucks (.njk) for layouts and pages
- **Content:** Markdown with YAML frontmatter for companies and blog posts
- **Styles:** CUBE CSS methodology with Tailwind as a design token processor (not traditional utility classes)
- **Components:** WebC components in `src/_includes/webc/`
- **Local CSS:** Use `{%- css "local" -%}` blocks for page-specific styles
- **Design Tokens:** Defined in `src/_data/designTokens/` (colors, spacing, typography)

## Collections

Available in templates:

- `collections.companies` — All companies (alphabetically sorted)
- `collections.featuredCompanies` — Randomly shuffled subset (8 of 12) from curated list
- `collections.recentCompanies` — Recently added (by addedAt date)
- `collections.companiesByRegion` — Grouped by region
- `collections.companiesByTech` — Grouped by technology
- `collections.allPosts` — Blog posts (reverse chronological)

## Search

Site search is powered by [Pagefind](https://pagefind.app/):

- **Nav search:** Dropdown search in the navigation bar (quick results)
- **Search page:** `/search/` — Full search results page with pagination
- Search index is built during `npm run build` via the pagefind post-process step

## Redirects

Legacy URL redirects are auto-generated in `src/common/_redirects.njk`:

- Old company URLs (`/company-slug`) redirect to new format (`/companies/company-slug/`)
- Blog subdomain redirects from old WordPress site

## Analytics

Fathom Analytics (privacy-focused) — only loads in production builds.

- Site ID configured in `src/_data/meta.js`
- 404 errors tracked via custom event with the attempted URL path

## Advertising

Carbon Ads (ethical, developer-focused) — only loads in production builds.

- Config: `src/_data/meta.js` (`carbonAds` export)
- Partial: `src/_includes/partials/carbon-ad.njk`
- CSS: `src/assets/css/global/blocks/carbon-ad.css`
- Layout: `base.njk` wraps `<main>` + ad `<aside>` in sidebar composition (production only)
- Cover format with automatic classic fallback

## SEO

### AI Bot Policy

`src/common/robots.njk` generates robots.txt with a dual policy:

- **Allowed:** AI search bots (ChatGPT-User, Claude-User, PerplexityBot, YouBot, Applebot-Extended)
- **Blocked:** AI training crawlers (GPTBot, CCBot, ClaudeBot, Google-Extended, FacebookBot, anthropic-ai, cohere-ai)

`AGENTS.md` is a symlink to `CLAUDE.md` for broader AI agent compatibility.

### Structured Data (JSON-LD)

Schema.org markup in `src/_includes/schemas/`:

- `WebSite.njk` — Site info with SearchAction for sitelinks search box
- `BreadcrumbList.njk` — Auto-generated breadcrumb trail from URL path
- `Organization.njk` — Company profile structured data
- `BlogPosting.njk` — Blog post structured data

Schemas are included via `src/_includes/head/schema.njk`. Page-specific schemas use the `schema` frontmatter field.

### Meta Descriptions

Company pages auto-generate meta descriptions from the "Company blurb" section via computed data in `src/companies/companies.11tydata.js`. Descriptions are truncated to ~155 characters at sentence boundaries.

### Company Dates

Company profiles have `addedAt` and `updatedAt` dates stored directly in frontmatter:

- **`addedAt`** — Date when the company was first contributed to the project (traced through git history, including the pre-migration `company-profiles/` path)
- **`updatedAt`** — Date of the last real content change (excludes bulk migrations and infrastructure commits). Some companies only have `addedAt` if no genuine content update occurred after the initial contribution

These dates were backfilled from a decade of git history using `git log --follow` to trace files through the October 2025 migration from `company-profiles/` to `src/companies/`. They are now static frontmatter values — no git commands run during build.

The homepage "Recently Added" section uses `addedAt` to show the most recently added companies. Company profile pages display "Last updated: [date]" in the footer.

### Social Cards

Twitter/X card meta tags are included in `src/_includes/head/meta-info.njk`:

- `twitter:card` — summary_large_image
- `twitter:title`, `twitter:description`, `twitter:image`

Open Graph tags are also present for Facebook/LinkedIn sharing.

## Versioning

The site uses semantic versioning in `package.json`. The version displays in the footer and links to `/changelog/`.

- **Major version bump**: Reserved for full site eras/redesigns (v1 = flat list, v2 = linked profiles, v3 = original live site, v4 = Eleventy rebuild)
- **Minor version bump** (e.g. 4.3.0 → 4.4.0): Visible changes — new companies, blog posts, feature additions/removals, data changes visitors can see
- **Patch version bump** (e.g. 4.4.0 → 4.4.1): Invisible changes — bug fixes, refactoring, documentation, CI/CD, performance improvements

## Deployment

- **Platform:** Netlify (auto-deploys from main branch)
- **Build command:** `npm run build`
- **Publish directory:** `dist`
- **Node version:** 22 (specified in package.json engines)

## Maintenance scripts

Ad-hoc maintainer tooling lives in `scripts/`. See `scripts/README.md` for the link-rot detection pipeline (`check-links.sh` + `fix-links.mjs`) used to find dead URLs, parked domains, and stale careers links across all company profiles.

## GitHub Actions

- **CI** (`.github/workflows/ci.yml`): Runs on push/PR to main. Builds the site with Node 22.
- **Validate Company Profiles** (`.github/workflows/validate-companies.yml`): Runs on PRs that touch company files. Validates frontmatter, enum values, slug/filename match, URL format, and required sections. Posts a PR comment with results and blocks merge on errors.
- **CodeQL** (`.github/workflows/codeql-analysis.yml`): Security scanning on push/PR and weekly schedule.

## Branch Protection

The `main` branch has protection rules:

- Requires pull request reviews (1 approval)
- Requires `build` status check to pass
- Only repository owner can push directly
- Force pushes and deletions disabled
- Admins can bypass when needed