CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Meltwater Engineering Blog (underthehood.meltwater.com) - a Jekyll static site hosted on GitHub Pages. Posts are written in Markdown, built by Jekyll, and deployed automatically when pushed to main.

Build and Serve

Docker (recommended):

./run-preview.sh

Serves at http://localhost:4000 with drafts, future posts, and live reload.

Local Ruby:

bundle install
jekyll serve --drafts --future

Requires Ruby 3.2.0 (see .tool-versions).

Blog Post Conventions

File naming: _posts/YYYY-MM-DD-url-slug.md

Images: stored in images/own/YYYY-MM-DD-slug/ and referenced with absolute paths (/images/own/...). Use the <figure> pattern:

<figure style="margin: 2em 0;">
<img src="/images/own/YYYY-MM-DD-slug/image.png" alt="Description" />
</figure>

Front matter:

---
layout: post
title: "Post Title"
comments: true
categories: [tag1, tag2]
author: <a href="https://linkedin.com/in/handle">Author Name</a>
image: "/images/own/YYYY-MM-DD-slug/preview.png"
excerpt: "Short preview text"
---

Excerpt separator: Use <!-- more --> to mark where the index page preview cuts off.

External links: Should use target="_blank".

Architecture

  • _posts/ - Published blog posts (Markdown)
  • _drafts/ - Unpublished drafts
  • _layouts/ - Jekyll templates (post.html is the main blog post layout)
  • _includes/ - Reusable Liquid partials (header, navigation, sidebar)
  • css/ - SCSS stylesheets (screen.scss is the main entry point)
  • docs/ - Writer documentation (MkDocs, published via Backstage TechDocs)

CI

  • Link checking: GitHub Actions runs Lychee on all Markdown files for broken links (on push/PR to main)
  • Deployment: Pushing to main triggers GitHub Pages build and deploy

Content Style

  • Never use em dashes in content
  • Don’t use SVG for preview images (the image front matter field)
  • Image filenames from docx conversion use pandoc’s imageN.ext naming