| # Agent Instructions |
|
|
| This file provides context for AI coding agents (Claude Code, GitHub Copilot, Cursor, Windsurf, etc.) working on this project. |
|
|
| ## Project overview |
|
|
| This is a **research article template** built with Astro + MDX. It produces interactive, web-native scientific papers with D3.js data visualizations, dark mode support, and PDF export. |
|
|
| ### Key paths |
|
|
| | What | Where | |
| |------|-------| |
| | Astro app | `app/` | |
| | MDX content | `app/src/content/` (article.mdx, chapters/) | |
| | Components | `app/src/components/` | |
| | HTML embeds (D3 charts) | `app/src/content/embeds/` | |
| | Data files (CSV/JSON) | `app/src/content/assets/data/` | |
| | Styles & CSS variables | `app/src/styles/` | |
| | Scripts (export, import) | `app/scripts/` | |
|
|
| ### Tech stack |
|
|
| - **Astro 4** with MDX |
| - **D3.js v7** for data visualization (loaded via CDN in embeds) |
| - **Svelte** for interactive components (e.g., Trackio) |
| - **CSS custom properties** for theming (light/dark mode) |
|
|
| ## Agent skills |
|
|
| Detailed guides for common tasks live in `.ai/skills/`. Read the relevant skill file before starting work: |
|
|
| | Skill | File | When to use | |
| |-------|------|-------------| |
| | Create HTML embed | [`.ai/skills/create-html-embed/SKILL.md`](.ai/skills/create-html-embed/SKILL.md) | Creating D3 charts, visualizations, interactive embeds | |
| | Article frontmatter | [`.ai/skills/article-frontmatter/SKILL.md`](.ai/skills/article-frontmatter/SKILL.md) | Configuring title, authors, template variant, DOI, PDF | |
| | Deploy to HF Spaces | [`.ai/skills/deploy-to-hf-spaces/SKILL.md`](.ai/skills/deploy-to-hf-spaces/SKILL.md) | Deploying, pushing, or updating a Hugging Face Space | |
|
|
| > **Cursor users**: these skills are auto-detected via a symlink at `.cursor/skills/`. |
|
|
| ## Creating HTML embed charts |
|
|
| When asked to create a chart, visualization, or D3 embed, read the skill files: |
|
|
| 1. **Workflow & quick reference**: `.ai/skills/create-html-embed/SKILL.md` |
| 2. **Full conventions & directives**: `.ai/skills/create-html-embed/directives.md` |
|
|
| ### TL;DR |
|
|
| - Embeds are self-contained `.html` files in `app/src/content/embeds/` |
| - Structure: single root `<div>` + scoped `<style>` + IIFE `<script>` |
| - Colors from `window.ColorPalettes`, theming via CSS variables |
| - Dark mode aware, responsive (ResizeObserver), mount-guarded (`data-mounted`) |
| - Integrated in MDX via `<HtmlEmbed src="d3-name.html" title="..." />` |
|
|
| ## Article frontmatter |
|
|
| When asked to configure article metadata (title, authors, template variant, etc.), read `.ai/skills/article-frontmatter/SKILL.md`. |
|
|
| Key points: |
| - `template: "article"` (default) = full layout; `template: "paper"` = lighter single-column |
| - Titles support `\n` for line breaks; long titles are auto-sized |
| - Authors use 1-based affiliation indices |
|
|
| ## Deploy to Hugging Face Spaces |
|
|
| When asked to deploy or update a Space, read `.ai/skills/deploy-to-hf-spaces/SKILL.md`. |
|
|
| Quick reference: |
| - SDK is Docker (`app_port: 8080`), build uses the included `Dockerfile` |
| - Push with `git push space main` (add remote first if needed) |
| - Cache issues: push an empty commit to force rebuild |
| - **Never remove the `research-article-template` tag from `README.md`** - it powers the [Research Article Gallery](https://huggingface.co/spaces/tfrere/research-article-gallery) |
|
|
| ## Coding conventions |
|
|
| - **Commits**: follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, etc.) |
| - **Styles**: scoped CSS, use existing CSS variables from `app/src/styles/_variables.css` |
| - **Components**: Astro components (`.astro`), Svelte for interactivity (`.svelte`) |
| - **No globals**: embeds use IIFEs, no `window` pollution |
| - **Accessibility**: `aria-label` on interactive elements, `alt` on images, focus-visible styles |
|
|
