CLAUDE.md

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

Project Overview

1700 kōan is a French website dedicated to classical Zen kōan literature. It’s built with Eleventy (11ty) static site generator and provides:

• A comprehensive database of classical kōans in French
• Biographical information for Zen masters
• Lineage trees showing relationships between masters
• A glossary of Buddhist terms
• Search functionality via Pagefind

The site generates both development and production versions with different search indexing and asset handling.

Development Commands

Setup

npm install

Install external dependencies:

• GraphViz (required for lineage tree generation)
• ImageMagick (for high-resolution graph printing)

Development Server

npm start                # Standard development server
npm run incremental      # Incremental builds for faster development

Build Commands

npm run build           # Full production build to 1700koan.fr/
npm run prebuild        # Pre-build with graph generation and date updates
npm run build-serve     # Production build with local server

Graph Generation

npm run gengraph        # Generate all lineage graphs
npm run gengraph_small  # Generate small subset graphs (masters defined in _scripts/graph/small_graph_main.ts)
npm run affiche         # Generate complete lineage for printing (300dpi)

Search Indexing

npm run index           # Build search index with Pagefind

Utilities

npm run name_extraction # Extract names from content files

Architecture

Content Structure

• Persons/: Master biographies with metadata (dates, lineage, etc.)
• Koans/: Individual kōan texts with person references
• Biographies/: Extended biographical materials
• Texts/: Buddhist texts and teachings
• Compilations/: Collections like Mumonkan, Hekiganroku
• Pages/: Static pages (about, glossary, sources)

Technical Structure

• _config/: Eleventy configuration modules
  • collections.js: Dynamic collection creation
  • filters/: Template filters for text processing
  • relate-collections.js: Cross-collection relationships
  • replacements.js: Text replacement system
  • markdown.js: Markdown processing configuration
  • pagefind.js: Search integration
• _data/: Global data files
  • masters.json: Master genealogy data
  • replacements_*.json: Auto-generated text replacement rules
• _scripts/: Build-time scripts
  • graph/: GraphViz lineage tree generation
  • update_pubdate.js: Publication date management
• _includes/: Eleventy templates and layouts
• style/: SCSS stylesheets with modular architecture

Key Features

Relational Collections: Uses custom plugin to create relationships between Persons, Koans, Texts, etc.

Text Replacement System: Automatically replaces person names with links and converts between romanization systems (romaji/pinyin).

Lineage Graphs: Generates SVG lineage trees using GraphViz from master-disciple relationships.

Multi-language Support: Handles Japanese, Chinese, Sanskrit terms with romanization.

Content Metadata: Rich frontmatter system with dates, sources, person references, and draft management.

Build Process

1. Pre-build: Generate graphs, update publication dates
2. Content Processing: Apply text replacements, create cross-references
3. Collection Building: Generate related content connections
4. Search Indexing: Build Pagefind search database (production only)
5. Asset Processing: SCSS compilation, file copying

Development Notes

• Content files use .11tydata.js for collection-specific metadata
• Draft posts are filtered out in production (controlled by pubdate and draft fields)
• Development builds output to 1700koan.fr-dev/, production to 1700koan.fr/
• GraphViz must be installed for lineage tree generation
• Search indexing only runs in production builds with INDEX=true