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

This is the documentation repository for the Karafka ecosystem - a Ruby and Rails efficient Kafka processing framework. It consists of Markdown files that are automatically processed and deployed as documentation.

• npm run lint - Lint all Markdown files using mkdocs-material-linter package
• npm run lint:fix - Auto-fix linting issues where possible
• ./bin/mklint - Complete documentation validation including structure, cross-references, and MkDocs build in strict mode

• ./bin/refresh_remote_content - Downloads changelogs and commercial license from all Karafka component repositories
• ./bin/refresh_librdkafka_errors - Generates librdkafka error documentation using rdkafka gem
• ./bin/refresh_librdkafka_releases - Generates librdkafka releases documentation from GitHub
• ./bin/refresh_librdkafka_statistics - Generates librdkafka statistics documentation
• ./bin/refresh_librdkafka_configuration - Generates librdkafka configuration documentation
• ./bin/align_structure - Flattens nested documentation structure for MkDocs compatibility
• ./bin/sync_gh - Synchronizes content with GitHub Karafka main repo

Several files are automatically generated and should NEVER be manually edited:

• Changelog/*.md - Component changelogs
• Librdkafka/Changelog.md - librdkafka release notes
• Librdkafka/Errors.md - librdkafka error reference
• Librdkafka/Statistics.md - librdkafka statistics documentation
• Librdkafka/Configuration.md - librdkafka configuration documentation
• Development/Karafka-Integration-Tests-Catalog.md - Integration tests catalog

These files include header comments indicating auto-generation status.

• Documentation is organized as standalone Markdown files
• Cross-references and anchor links are validated during CI
• MkDocs is used for final documentation generation and deployment
• Custom markdownlint rules enforce Karafka-specific formatting requirements

• Content refresh happens twice daily (6:00 AM and 6:00 PM UTC)
• Pull requests are automatically created when content updates are available
• CI pipeline validates Markdown formatting, structure, and builds documentation in strict mode

• All shell code blocks should use bundle exec prefix as enforced by custom linting rules
• Admonition blocks must have valid types and non-empty titles
• The mklint script is the authoritative validation tool - always run it before submitting changes
• Manual edits should focus on non-auto-generated documentation files only
• Auto-generated files have header comments like [//]: # (This file is auto-generated by bin/refresh_remote_content)
• Files excluded from linting are configured in .markdownlint-cli2.jsonc

Do what has been asked; nothing more, nothing less. NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.