# Next.js + MDX Website Agent

This document provides context for AI agents working on this project.

## Project Overview

This is a personal website and portfolio built with Next.js and Tailwind CSS. The site is statically generated, with content sourced from local `.mdx` files. The primary purpose is to showcase experience, and publications posts.

## Tech Stack

-   **Framework**: Next.js (App Router)
-   **Language**: TypeScript
-   **Styling**: Tailwind CSS
-   **Package Manager**: `pnpm`
-   **Content**: `next-mdx-remote` for processing `.mdx` files with YAML frontmatter (`gray-matter`).

## Development Environment

-   **Install dependencies**: `pnpm install`
-   **Run development server**: `pnpm dev`
-   **Build for production**: `pnpm build`
-   **Run production server**: `pnpm start`
-   **Lint files**: `pnpm lint`

## Project Structure

-   `content/`: Root directory for all MDX content, organized into subdirectories by category (e.g., `research`, `experience`).
-   `src/app/`: Next.js App Router structure. Pages are dynamically generated based on the content in the `content/` directory.
-   `src/lib/mdx.ts`: Core logic for finding, parsing, and serializing MDX files. It reads the file contents, separates frontmatter using `gray-matter`, and prepares it for rendering.
-   `src/components/`: Contains all reusable React components.
-   `public/`: Static assets like images, figures, and PDFs.

---

## Content Authoring Guide (MDX)

All content is written in `.mdx` files located in the `content/` directory.

### Frontmatter

Each `.mdx` file must contain a YAML frontmatter block at the top. Here are the commonly used fields:

-   `title` (string, required): The title of the post.
-   `tags` (string[], optional): A list of relevant tags.
-   `excerpt` (string, required): A short, one-sentence summary of the content.
-   `teaser` (string): Path to the teaser image (e.g., `/figures/my-image.png`).
**Example Frontmatter:**

```yaml
---
title: "MAS Emergence Safety"
tags: [multi-agent-systems, MARL, safety]
excerpt: "Formalized MAS emergence misalignment; proposed safety mitigation strategies."
teaser: "/figures/21_coins_teaser.png"
---
```

### Available Custom Components

You can import and use standard React components, but the following custom components are globally available in all `.mdx` files without needing to be imported.

#### `<Cite>`

Renders an academic-style citation link. It automatically adds the publication to a reference list on the page.

-   **Props**:
    -   `bibtexKey` (string, required): The BibTeX key for the publication (must exist in the citation context).
-   **Usage**:
    ```mdx
    This is a claim that needs a citation. <Cite bibtexKey="altmann2024emergence" />
    ```

#### `<InfoBox>`

Renders a floating informational box, typically used for metadata or asides.

-   **Props**:
    -   `title` (string, required): The title displayed at the top of the box.
-   **Usage**:
    ```mdx
    <InfoBox title="Project Details">
      - **Status**: Completed
      - **Tech**: Next.js, React
    </InfoBox>
    ```

#### `<Image>`

A wrapper around the Next.js `<Image>` component that automatically adds a `rounded-lg` style. Use it as you would a standard Markdown image, but with the component syntax.

-   **Props**: Same as `next/image`.
-   **Usage**:
    ```mdx
    <Image src="/figures/my-figure.png" alt="Description of the figure" width={800} height={600} />
    ```

#### Standard HTML Elements

-   **Headings (`<h1>` to `<h6>`)**: Automatically generate `id` attributes and anchor links for easy linking.
-   **Links (`<a>`)**: Internal links (`/path`), anchor links (`#id`), and external links (`https://...`) are handled automatically to optimize navigation or add `target="_blank"`.