SAC Website Development Guide

Guide for working with the Sociedad de Astronomía del Caribe (SAC) website codebase - a non-profit astronomy organization's Spanish-language Next.js site.

Project Context

This is a **Next.js 12** site for a Puerto Rico-based astronomy organization. The site uses:

Development Workflow

Starting Development

1. Copy `.env.template` to `.env` and configure required variables

2. Run `npm run dev` to start the development server with hot reload

3. Navigate to `http://localhost:3000` to view the site

Common Commands

Content Management

Blog Posts

Blog posts live in `data/blog/` organized by year and month (e.g., `data/blog/2024/02/post-slug.mdx`).

**Frontmatter structure:**

```yaml

---

title: 'Post Title in Spanish'

date: 2024-01-01T08:00:00Z

tags: ['astronomía', 'eventos']

draft: false

summary: 'Brief post summary'

images: ['static/images/path/image.png']

imgWidth: 512

imgHeight: 512

authors: ['author-slug'] # References data/authors/*.md

---

```

**Important flags:**

Authors

Author profiles are markdown files in `data/authors/` with frontmatter:

```yaml

---

name: 'Author Name'

avatar: '/static/images/avatar.jpg'

---

```

Reference authors in blog posts using the filename slug (without `.md` extension).

Site Configuration

Architecture Guide

Directory Structure

```

├── pages/ # Next.js pages & API routes

├── components/ # React components

│ ├── widgets/ # Reusable UI widgets

│ ├── articles/ # Article display components

│ └── social-icons/ # Social media icons

├── layouts/ # Page layouts (PostLayout, AuthorLayout, ListLayout)

├── lib/ # Core utilities

│ └── mdx.js # MDX processing logic

├── data/ # Content & config

│ ├── blog/ # MDX/MD blog posts (YYYY/MM/)

│ ├── authors/ # Author profiles

│ ├── siteMetadata.js

│ └── headerNavLinks.js

├── scripts/ # Build utilities (sitemap, cleanup)

└── appsscript/ # Google Apps Script (membership)

```

Path Aliases

Configured in `jsconfig.json`:

API Routes

Located in `pages/api/`:

Environment Variables

Copy `.env.template` to `.env` and configure:

**Required for comments:**

**Required for photo gallery:**

**Optional:**

Testing

Run tests with Jest (jsdom environment):

```bash

npm run test # Run all tests

npx jest path/to/test.js # Run specific test file

```

Tests are located in the `test/` directory.

External Integrations

Content Editing Tools

Prose.io Integration

The site includes a cleanup script (`scripts/clean-prose-mdx.js`) that runs before builds to fix MDX formatting issues introduced by Prose.io editing. Use `npm run start` for dev mode with remote file watching when content is edited via Prose.io.

Build Process

The production build runs three steps:

1. **Cleanup script** - Fixes Prose.io MDX formatting

2. **Next.js build** - Compiles site with Preact substitution

3. **Sitemap generation** - Creates `public/sitemap.xml`

Important Notes