# AGENTS.md

# Project overview

Bibek's Blog is a static blog generated with Eleventy (11ty). Markdown content in posts/ is rendered into _site/; browser JavaScript, CSS, search data, and static verification files are copied into the output. The site is configured for Cloudflare Pages/Vercel-style deployment.

# Architecture

• .eleventy.js is the main build configuration. It registers RSS, navigation, blog-tools, and syntax-highlighting plugins; Markdown options; date/tag/SEO filters; collections; HTML minification; passthrough copies; and the post-build PWA/Tailwind hook.
• posts/ contains dated Markdown articles. posts/posts.json supplies collection metadata.
• _11ty/ contains Eleventy collections and tag utilities. _custom/ contains shortcodes such as post-summary extraction.
• _data/ contains global data and build-time helpers, including metadata, projects, popular content, SEO monitoring, and statistics utilities.
• js/main.js handles shared browser behavior; js/code-blocks.js handles code-block UX; js/search.js implements the BlogSearch class and client-side search; js/search-index.json is generated search data.
• api/ contains Eleventy/serverless-style endpoints for search diagnostics/results and SEO monitoring. api/seo-monitor-json.11ty.js emits a generated SEO-monitor JSON resource.
• css/ and style/tailwind.css contain styles. Tailwind output is generated into _site/css/main.css.
• pwa-config.js generates the service worker after an Eleventy build. vercel.json defines redirects, rewrites, and security/cache headers.

# Common commands

npm install
npm run serve              # Eleventy dev server (ELEVENTY_ENV=dev)
npm run develop            # clean + Tailwind and Eleventy watchers
npm run build              # production Eleventy build and search-index copy
npm run build:validate     # production build plus feed validation
npm run generate-search-index
npm run lint               # ESLint for scripts/

The build writes generated content to _site/ and updates js/search-index.json; do not hand-edit generated files. npm run clean removes _site/.

# Content changes

• Add posts as Markdown files under posts/ with front matter including at least title, date, description, and tags.
• Keep tag behavior compatible with _11ty/tagUtilities.js and _11ty/retrieveTags.js; system tags are filtered/normalized there.
• Update layouts/includes and data files when changing site-wide presentation or metadata.

# Change and verification guidance

• Prefer small, focused changes and preserve existing Eleventy conventions.
• For build/config/content changes, run npm run build:validate when dependencies are installed.
• For browser-side changes, run a production build and manually verify the relevant page/search flow.
• Avoid committing _site/ or other generated output unless the repository explicitly requires it.
• Treat environment variables such as ELEVENTY_ENV and GA_API_ENDPOINT as deployment/build configuration; do not hard-code secrets.

# Repository knowledge graph

The codebase is indexed with codebase-memory-mcp. Prefer its graph tools for code discovery (search_graph, trace_path, get_code_snippet, query_graph, and search_code) before falling back to grep/file search. The local index artifact is .codebase-memory/graph.db.zst.