100 lines
3.7 KiB
Markdown
100 lines
3.7 KiB
Markdown
# 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"`. |