Skip to content

AGENTS.md

Latest commit

 

History

History
44 lines (28 loc) · 2.18 KB

AGENTS.md

File metadata and controls

44 lines (28 loc) · 2.18 KB

Repository Guidelines

Project Structure & Module Organization

This directory contains editorial source files and assets consumed by the Astro app.

  • src/data/blog/: blog posts, examples, and release notes.
  • src/data/citations/: shared and per-path BibLaTeX files.
  • src/pages/about.md: the About page content.
  • src/assets/images/ and public/: images and static files used by content.
  • .markdownlint/ and .markdownlint-cli2.yaml: markdown rules for this workspace.

Keep article text, references, and related assets together when possible.

Build, Test, and Development Commands

Content validation is executed from code/, because the app owns the tooling:

  • bun run sync:content: create linked content paths inside code/ from this directory's source files.
  • bun run cites:check: verify references, bibliography IDs, and URL alignment.
  • bun run check:articles: run article-focused validation.
  • bun run lint:md: apply markdownlint rules after syncing config.
  • bun run cites:transform_inline: convert inline links to reference-link form.

If an agent cannot find the corresponding content files from within code/, run bun run sync:content in code/ first so the linked paths are recreated.

Writing Style & Naming Conventions

Use kebab-case filenames such as how-to-update-dependencies.md. Keep frontmatter consistent with existing posts and update bibliography data when adding or changing cited links.

Markdown rules are strict:

  • use reference links, not inline links;
  • do not put links inside headings;
  • end prose paragraphs with punctuation;
  • keep reference IDs alphanumeric with underscores only.

Testing Guidelines

After editing any file in src/data/blog/, src/data/citations/, or src/pages/about.md, run bun run cites:check and bun run check:articles from code/. Run bun run lint:md when changing markdown structure or large sections of prose.

Commit & Pull Request Guidelines

Use Conventional Commit messages, for example docs: add bibliography entries for about page. PRs should summarize content changes, link related issues, and mention the validation commands run. Include screenshots only when an edit changes rendered layout or media.