# Repository: remoteintech/remote-jobs
# Stars: 40245

## CLAUDE.md

# CLAUDE.md

## Shorthand

- **"Punch it"** = commit, push, and open a PR to upstream, all in one go.

## 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)
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                 # startup, small, medium, large, enterprise
technologies:                         # Array of tech tags
  - javascript
  - python
  - devops
addedAt: 2024-03-15                   # Date first contributed (from git history)
updatedAt: 2025-06-20                 # Date of last real content change (from git history)
---
```

**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`.

## 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

Access these 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.

## Deployment

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

## 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

When bumping the version:
1. Update `version` in `package.json`
2. Add a new entry at the top of `src/_data/changelog.json`

Changelog entries should be summaries. Call out each company addition by name with the `Company:` prefix (e.g. `Company: BigData Boutique`), but summarise edits, deletions, and fixes. Change types: `added`, `changed`, `fixed`, `removed`. Descriptions support HTML links — use them to link to company profiles, blog posts, and relevant pages (e.g. `Company: <a href="/companies/bigdata-boutique/">BigData Boutique</a>`).

## Contributing a Company

1. Create `src/companies/{slug}.md` with required frontmatter
2. Add company description in Markdown body
3. Run `npm run build` to verify it builds correctly
4. Submit PR to `remoteintech/remote-jobs`

## Processing Contributor PRs

PRs that touch company files are automatically validated by the **Validate Company Profiles** Action (`.github/workflows/validate-companies.yml`). The bot posts a comment with specific feedback and blocks merging until issues are fixed.

**Workflow:**

1. **Check the automated validation comment** on the PR for any issues
2. **If the contributor needs more guidance** beyond what the bot provided, leave a helpful comment explaining what to fix
3. **For old-format PRs** (files in `company-profiles/` or changes to `README.md`), the bot will explain the new format with a template — ask the contributor to update their PR
4. **Only re-create a PR yourself as a last resort** if the contributor is unresponsive after reasonable follow-up

**Reject PRs that:**
- Promote harmful services (hacking tools, spam, etc.)
- Have minimal or no meaningful content
- Are duplicates of existing companies

## 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

## Link Checker

A script to check all outbound URLs in company profiles for broken links and redirects.

### Files (gitignored)

- `check-links.sh` - Link checker script
- `extracted-urls.txt` - List of all URLs extracted from company files
- `link-check-results.csv` - Results with status codes and explanations
- `link-report.html` - Interactive HTML report for viewing results

### Commands

```bash
# Full check - all URLs (~8 min for ~2,200 URLs)
./check-links.sh

# Quick check - only re-check URLs that weren't OK last time
./check-links.sh --quick

# Refresh - re-extract URLs from company files, then full check
./check-links.sh --refresh
```

### Viewing Results

Open `link-report.html` directly in a browser and load `link-check-results.csv` via the file picker (or drag and drop).

### CSV Columns

| Column | Description |
|--------|-------------|
| `source_file` | Company profile containing the link |
| `original_url` | URL as it appears in the file |
| `resolved_url` | Final URL after redirects |
| `status_code` | HTTP status (200, 404, ERROR, etc.) |
| `explanation` | What happened (OK, Redirects, Not found, etc.) |
| `no_change_needed` | Yes / No / Review |

### Workflow

1. Run `./check-links.sh` for initial full scan
2. Fix broken links in company profiles
3. Run `./check-links.sh --quick` to verify fixes
4. Repeat until satisfied


## README.md

# Remote In Tech

**[remoteintech.company](https://remoteintech.company)** — A community-maintained directory of remote-friendly tech companies.

> This repository is the source code for the site. To browse the directory, visit **[remoteintech.company](https://remoteintech.company)**.

## Contributing a Company

We welcome contributions! To add a company to the directory:

1. Create a file at `src/companies/{company-slug}.md`
2. Use the frontmatter template below
3. Add a company description in the Markdown body
4. Run `npm run build` to verify it builds
5. Submit a PR to this repo

### Company Profile Template

```yaml
---
title: "Company Name"
slug: company-slug
website: https://example.com
careers_url: https://example.com/careers
region: worldwide                     # worldwide, americas, europe, asia-pacific, americas-europe, other
remote_policy: fully-remote           # fully-remote, remote-first, remote-friendly, hybrid
company_size: small                   # startup, small, medium, large, enterprise
technologies:
  - javascript
  - python
---

## Company blurb

A short description of the company and what they do.
```

PRs are automatically validated — the bot will comment with any issues to fix.

## Development

```bash
npm install         # Install dependencies
npm run start       # Dev server with hot reload
npm run build       # Production build
```

Requires Node.js 22+.

## Credits

Built with [Eleventy Excellent](https://github.com/madrilene/eleventy-excellent) by [Lene Saile](https://github.com/madrilene).

## License

ISC