Buddies of Budgie Site

This repository houses the Next.js-based website for Buddies of Budgie, an open source organization building the Budgie Desktop environment.

Live Site: buddiesofbudgie.org

Tech Stack

• Framework: Next.js 16 (App Router) with React 19
• Language: TypeScript
• Styling: Tailwind CSS 4
• UI Components: shadcn/ui with Radix primitives
• Content: MDX with @next/mdx (file-based, statically generated)
• Internationalization: next-intl
• Formatting: bun fmt
• Package Manager: Bun
• Build Tool: Turbopack, with the Rust React Compiler

Project Structure

site/
├── src/
│   ├── app/              # Next.js App Router pages
│   ├── components/       # React components
│   │   ├── about/        # About page components
│   │   ├── blog/         # Blog components
│   │   ├── home/         # Home page components
│   │   ├── mdx/          # MDX component overrides
│   │   └── ui/           # shadcn/ui components
│   ├── content/          # MDX content files
│   │   ├── about/        # About pages (FAQ, etc.)
│   │   └── blog/         # Blog posts
│   ├── data/             # Static data files
│   ├── messages/         # i18n translation files
│   └── styles/           # Global styles
├── public/               # Static assets
├── mdx-components.tsx    # Global MDX components configuration
└── next.config.js        # Next.js configuration

Development

Prerequisites

Bun is the only requirement. It installs dependencies, formats, lints, and runs Next.js in place of Node.js ([run] bun = true in bunfig.toml). bun lint is only in canary builds, so install one with bun upgrade --canary.

Setup

bun install

Development Server

Start the development server:

bun run dev

Open http://localhost:3000 in your browser.

Available Commands

bun run dev              # Start development server
bun run build            # Build for production
bun run start            # Serve the static export
bun run ci               # Type check + format check + lint (what CI runs)
bun run format           # Format code with bun fmt
bun run check-types      # TypeScript type check only

Upgrading Dependencies

To upgrade dependencies interactively:

bun update --interactive

Building for Production

bun run build

The build output is a static site in the out/ directory. To serve it locally, run bun run start.

Content Management

Blog Posts

Blog posts are MDX files in src/content/blog/. Each post requires frontmatter:

---
title: 'Post Title'
author: AuthorId
publishDate: '2026-01-01T00:00:00.000Z'
featuredImage: /images/blog/2026/01/image.jpg
excerpt: Short description
tags:
  - news
  - releases
---

Your content here...

MDX Components

Custom MDX components are defined in:

• src/components/mdx/mdx-components.tsx - Component definitions
• mdx-components.tsx (root) - Global configuration using useMDXComponents

Available custom components:

• <Admonition type="info|note|tip|caution|warning|danger"> - Callout boxes
• <Alert severity="info|warning|error|success"> - Legacy alert component (maps to Admonition)
• <FAQSection> and <FAQItem> - FAQ components
• <OCCallout> - Open Collective donation callout

Architecture Notes

MDX Handling

The site uses @next/mdx with dynamic imports for MDX content. Key points:

• No next-mdx-remote - We use Next.js's native MDX support with @next/mdx
• Dynamic imports - Blog posts and content are imported dynamically: (await import('@site/content/blog/${slug}.mdx')).default
• Frontmatter stripping - Handled by remark-frontmatter and remark-mdx-frontmatter plugins
• Plugins by name - Turbopack can't pass JavaScript functions to Rust, so next.config.js names remark plugins as strings and their options must be serializable

Static Generation

All pages are statically generated at build time:

• Blog posts: Generated via generateStaticParams
• FAQ page: export const dynamic = 'force-static'
• About pages: Fully static

Internationalization

Currently supports English only. Translations are in src/messages/en.json and accessed via useTranslations from next-intl.

Contributing

See CONTRIBUTING.md for commit conventions, DCO sign-off, and the AI policy.

Code Style

• Format with bun fmt before committing; CI rejects unformatted files. Options live in the [fmt] section of bunfig.toml
• TypeScript strict mode enabled - avoid any types
• Components should be functional with TypeScript
• Follow existing naming conventions

Troubleshooting

MDX Build Errors

If you encounter MDX-related build errors:

1. Clear build cache: rm -rf .next && bun run build
2. Verify @mdx-js/loader is installed: bun pm why @mdx-js/loader

Type Errors

Run type checking separately to see detailed errors:

bun run check-types

Resources

• Next.js Documentation
• Next.js App Router Guide
• MDX Documentation
• Tailwind CSS Documentation
• shadcn/ui Components

License

This project is open source and available under the terms specified in the LICENSE file.