CLAUDE.md

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

Project Overview

This is a Turkish law firm website (Akkuş Avukatlık) built with Eleventy (11ty) static site generator, based on the high-performance blog template from Google. The site is optimized for performance, accessibility, and SEO with extensive Tailwind CSS customization.

Development Commands

Primary Development

• npm run dev - Start development with watch mode (SCSS, Tailwind, 11ty)
• npm run build - Production build (SCSS → Tailwind → SVG → JS → 11ty)

Individual Tasks

• npm run dev:11ty - Start Eleventy dev server only
• npm run dev:tailwindcss - Watch Tailwind CSS compilation
• npm run dev:scss - Watch SCSS compilation
• npm run build:tailwindcss - Build production Tailwind CSS (minified)
• npm run build:scss - Compile SCSS to CSS
• npm run build:svg - Generate SVG sprite from icons/
• npm run build:js - Bundle and minify JavaScript with Rollup

Testing

• npm test - Run Mocha tests
• npm run test-watch - Run tests in watch mode

Content Management

• npm run admin - Start Netlify CMS proxy server for local content editing

Architecture & Key Patterns

Directory Structure

├── _11ty/           # Eleventy plugins and custom functionality
├── _data/           # Global data files (metadata.json, settings.js)
├── _includes/       # Nunjucks templates and layouts
├── _site/           # Generated static site (build output)
├── admin/           # Netlify CMS configuration
├── css/             # Compiled CSS output
├── img/             # Images (optimized with srcset generation)
├── js/              # JavaScript source files
├── pages/           # Markdown pages for legal service descriptions
├── posts/           # Blog posts (articles about legal topics)
├── services/        # Legal service category pages
├── taxonomy/        # Tag/category pages for organizing content
├── tailwindcss/     # Tailwind source files and SCSS components
└── test/            # Test files

Content Types

1. Services (services/) - Legal practice areas (e.g., criminal law, family law)
2. Pages (pages/) - General content pages and lawyer profiles
3. Posts (posts/) - Blog articles about legal topics
4. Taxonomy (taxonomy/) - Category and tag pages
5. Reviews (reviews/) - Client testimonials

Performance Optimizations

• Images: Automatic srcset generation, WebP/AVIF conversion, lazy loading
• CSS: Tailwind CSS with PurgeCSS for unused style removal
• JS: Rollup bundling with Terser minification
• HTML: Minification and compression optimization
• CSP: Content Security Policy with hash-based script validation

Custom 11ty Plugins (_11ty/)

• img-dim.js - Image dimension inference
• json-ld.js - Structured data generation
• optimize-html.js - HTML minification
• apply-csp.js - Content Security Policy application
• srcset.js - Responsive image generation
• video-gif.js - GIF to MP4 conversion

Styling System

• Base: Tailwind CSS v3.1+ with custom configuration
• Components: SCSS components in tailwindcss/scss/components/
• Utilities: Custom utilities in tailwindcss/scss/utilities/
• Typography: Quicksand font family, Turkish content optimization

Data Management

• _data/metadata.json - Site metadata, contact info, social media
• _data/menu.json - Navigation structure
• _data/settings.js - Environment-specific settings
• Each content type has .11tydata.js files for shared front matter

Turkish Language Features

• Content is primarily in Turkish
• Turkish-specific URL slugs and permalinks
• Local business schema markup for İzmir, Turkey
• Turkish legal terminology and practice areas

SEO & Schema Markup

• Comprehensive JSON-LD structured data
• Open Graph and Twitter Card meta tags
• XML sitemaps for different content types
• Local business schema for law firm

Development Notes

• Uses Nunjucks for templating with Liquid for Markdown
• Content Security Policy requires hash updates when adding inline scripts
• Images should be placed in img/ for automatic optimization
• All content uses front matter for metadata
• Turkish characters are properly handled in URLs and content

Testing

• Basic tests verify homepage navigation and post listings
• Tests check for required HTML structure elements
• Run npm test after major changes to verify build integrity

Custom Markdown Containers

The site uses custom markdown-it containers for rich content formatting:

Container Name	Use Case	Syntax
summaryToc	Table of contents - collapsible navigation for long legal documents	::: summaryToc İçindekiler
kanun	Legal provisions - displaying law articles, regulations, and statutes	::: kanun 2547 Sayılı Yükseköğretim Kanunu
youtube	Video embeds - legal education videos, case study explanations	::: youtube dQw4w9WgXcQ
summary	FAQ sections - collapsed questions about legal procedures	::: summary Dava açmak için süre sınırı var mı?
summaryOpen	Important FAQ - expanded questions that should be visible by default	::: summaryOpen Uzman avukat desteği neden önemli?

Container Examples:

::: summaryToc İçindekiler
- Dava Süreci
- Gerekli Belgeler  
- Mahkeme Kararları
:::

::: kanun 2547 Sayılı Yükseköğretim Kanunu
Üniversitelerin akademik kadro ilanları...
:::

::: summary Dava açmak için süre sınırı var mı?
60 gün içinde dava açılmalıdır...
:::

::: summaryOpen Uzman avukat desteği neden önemli?
Akademik hukuk karmaşık bir alandır...
:::

All containers render as accessible <details>/<summary> HTML elements with appropriate CSS classes for styling.

Deployment

• Optimized for Netlify deployment
• Uses netlify.toml for build configuration
• Automatic image optimization and caching headers
• Environment variable support for metadata overrides