nerderland/README.md

# NERDER.LAND - Event Management Documentation

A Hugo static site for listing nerdy events in your local community with a cyberpunk/console theme.

## Site Overview

- **Framework**: Hugo v0.147.7+ static site generator
- **Theme**: Custom cyberpunk/console theme (no external dependencies)
- **Content**: Event listings with detailed individual pages
- **Styling**: Pure CSS with cyberpunk aesthetics (no JavaScript)

## Prerequisites

1. **Go 1.24.3+** (managed via gvm)
2. **Hugo v0.147.7+** (installed via Go)

## Initial Setup

```bash
# Set up Go environment
source ~/.gvm/scripts/gvm
gvm use go1.24.3

# Install Hugo
go install -tags extended github.com/gohugoio/hugo@latest

# Verify installation
hugo version
```

## Site Structure

```
nerder.land/
├── content/
│   ├── events/           # Event markdown files
│   └── _index.md         # Homepage content
├── layouts/
│   ├── _partials/        # Header, footer components
│   ├── events/           # Event page templates
│   ├── baseof.html       # Base template
│   ├── home.html         # Homepage template
│   └── single.html       # Default single page template
├── static/
│   └── css/
│       └── style.css     # Cyberpunk theme styles
├── public/               # Generated site (auto-created)
└── hugo.toml            # Site configuration
```

## Managing Events

### Creating a New Event

1. Generate the event file:
```bash
source ~/.gvm/scripts/gvm && gvm use go1.24.3
hugo new content events/your-event-name.md
```

2. Edit the event file with proper front matter:
```yaml
+++
title = 'Your Event Title'
date = '2025-07-15T19:00:00-06:00'        # Start date/time (with timezone)
end_date = '2025-07-15T23:00:00-06:00'    # End date/time (optional)
location = 'Venue Name, Address'           # Event location
organizer = 'Organization Name'            # Who's organizing
capacity = 50                              # Max attendees (optional)
cost = 'Free' # or '$25'                  # Event cost
registration_url = 'https://...'           # Registration link (optional)
contact = 'email@domain.com'               # Contact info
draft = false                              # Set to false to publish
+++

Brief event description that appears on homepage. Keep this to 1-2 sentences that give a clear overview of what the event is about.

<!--more-->

## Full Event Details

Add detailed information here including:
- Event description
- What to expect
- Requirements
- Schedule
- Any other relevant information
```

### Event Front Matter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `title` | Yes | Event name/title |
| `date` | Yes | Start date and time (ISO format) |
| `end_date` | No | End date and time |
| `location` | No | Venue/address |
| `organizer` | No | Who's running the event |
| `capacity` | No | Maximum attendees |
| `cost` | No | Event price (e.g., "Free", "$25") |
| `registration_url` | No | Link to registration page |
| `contact` | No | Contact email/info |
| `draft` | Yes | Set to `false` to publish |

### Content Structure

**Summary Section (before `<!--more-->`)**:
- Brief 1-2 sentence description
- Appears on homepage event listing
- Should give clear overview without details

**Full Content (after `<!--more-->`)**:
- Detailed event information
- Use markdown formatting (headers, lists, etc.)
- Only appears on individual event pages

### Event Dates and Timezones

- **Important**: Set `buildFuture = true` in `hugo.toml` to show future events
- Events automatically sort chronologically on homepage
- Past events won't appear on homepage but remain accessible via direct URL

**Timezone Handling:**
- Use ISO 8601 format with timezone offset: `2025-07-15T19:00:00-06:00`
- The site currently displays "MST" (Mountain Time) and "UTC-6" 
- To change timezone display, update the `dateFormat` calls in templates:
  - `layouts/home.html` (homepage event listing)
  - `layouts/events/single.html` (event detail pages)
  - `layouts/events/rss.xml` (RSS feeds)
- Update the hardcoded timezone info in `layouts/events/single.html`

## Development Workflow

### Local Development

```bash
# Start development server
source ~/.gvm/scripts/gvm && gvm use go1.24.3
hugo server --bind 0.0.0.0 --port 1313

# View site at: http://localhost:1313
```

### Building for Production

```bash
# Build static site
source ~/.gvm/scripts/gvm && gvm use go1.24.3
hugo

# Generated files will be in public/ directory
```

## RSS Feeds & Calendar Integration

The site automatically generates multiple feed formats:

### RSS Feeds
- **All content**: `https://your-site.com/feed.xml`
- **Events only**: `https://your-site.com/events/feed.xml`

### iCal Calendar Feeds  
- **Master calendar subscription**: `https://your-site.com/events/calendar.ics`
- **Individual event downloads**: `https://your-site.com/events/event-name/calendar.ics`

### Feed Features
**RSS feeds include:**
- Event title and description
- Date, location, and cost information
- Direct links to full event pages
- Properly formatted for feed readers

**iCal calendars include:**
- Proper timezone information (America/Denver)
- Start and end times
- Event location and description
- Organizer and contact information
- Compatible with all major calendar apps

### Calendar App Compatibility
The iCal feeds work with:
- **Google Calendar** - Subscribe via URL
- **Apple Calendar** - Subscribe via URL  
- **Outlook** - Import or subscribe
- **Mozilla Thunderbird** - Calendar subscription
- **Any CalDAV client** - Standard iCal format

## Site Configuration

### Basic Settings (`hugo.toml`)

```toml
baseURL = 'https://your-domain.com/'
languageCode = 'en-us'
title = 'NERDER.LAND'
buildFuture = true  # Required for future events

# Ignore README.md from being processed as content
ignoreFiles = ["README.md"]

[params]
description = "Your site description here"
eventSubmissionEmail = "events@your-domain.com"  # Email for event submissions

# RSS and Calendar configuration
[outputs]
home = ["HTML", "RSS"]
section = ["HTML", "RSS", "Calendar"]
page = ["HTML", "Calendar"]

[outputFormats]
[outputFormats.RSS]
mediatype = "application/rss"
baseName = "feed"

[outputFormats.Calendar]
mediatype = "text/calendar"
baseName = "calendar"
isPlainText = true
```

### Theme Customization

The cyberpunk theme is in `static/css/style.css`. Key variables:

```css
:root {
  --neon-green: #00ff41;   # Primary text color
  --neon-blue: #00d4ff;    # Links and accents
  --neon-pink: #ff0080;    # Event titles
  --dark-bg: #0a0a0a;      # Background
  --matrix-green: #41ff00; # Secondary elements
}
```

## Deployment

The `public/` directory contains the complete static site. Deploy options:

1. **Netlify**: Connect to git repo, set build command to `hugo`
2. **GitHub Pages**: Use GitHub Actions with Hugo workflow
3. **Traditional hosting**: Upload `public/` contents to web server
4. **CDN**: Any static hosting service (Vercel, Firebase, etc.)

## Troubleshooting

### Events Not Showing

1. Check `draft = false` in front matter
2. Ensure `buildFuture = true` in `hugo.toml` for future events
3. Verify date format: `2025-07-15T19:00:00-06:00`

### ASCII Art Broken

- Ensure ASCII art is wrapped in `<pre>` tags in templates
- Check for proper escaping in HTML

### Site Not Building

1. Verify Hugo version: `hugo version`
2. Check for syntax errors in content files
3. Ensure Go environment: `go version`

### Template Issues

- Hugo v0.147.7+ uses new template system
- Templates must be in correct directory structure
- Use `hugo --logLevel debug` for detailed error info

## Content Guidelines

### Event Descriptions

- **Homepage summary**: 1-2 sentences, engaging but concise
- **Full description**: Detailed, use markdown formatting
- **Include practical info**: Date, time, location, cost, requirements

### Writing Style

- Match the cyberpunk/tech theme
- Be informative but exciting
- Include clear call-to-action for registration
- Mention skill levels if relevant

### Images

- Add images to `static/images/` directory
- Reference in markdown: `![Alt text](/images/filename.jpg)`
- Keep file sizes reasonable for web

## Maintenance

### Regular Tasks

1. **Remove past events**: Delete old event files periodically
2. **Update dependencies**: Occasionally update Hugo version
3. **Backup content**: Keep `content/` directory in version control
4. **Monitor analytics**: Track which events get most interest

### Content Archival

Consider moving past events to an `archive/` section rather than deleting, to maintain event history and SEO value.

## Community Event Submissions

The site includes a "Submit an Event" link in the footer that allows community members to email event details.

### How It Works

1. **Submission Link**: Footer contains a mailto link with pre-formatted email template
2. **Email Template**: Automatically includes required fields (name, date, location, etc.)
3. **Review Process**: Site administrator receives email and manually creates event pages
4. **Configuration**: Email address configurable via `eventSubmissionEmail` in `hugo.toml`

### Email Template Fields

The submission email includes these pre-filled fields:
- Event Name
- Date & Time  
- Location
- Description
- Organizer
- Contact Info
- Cost
- Registration URL (if any)

### Processing Submissions

When you receive event submissions:

1. **Review the details** for completeness and appropriateness
2. **Create the event file** using `hugo new content events/event-name.md`
3. **Fill in front matter** from the submitted information
4. **Add detailed content** based on the description provided
5. **Set `draft = false`** to publish the event
6. **Reply to submitter** confirming publication or requesting clarification

## Support

For issues with Hugo or Go setup, refer to:
- [Hugo Documentation](https://gohugo.io/documentation/)
- [Hugo Community Forum](https://discourse.gohugo.io/)
- [Go Installation Guide](https://golang.org/doc/install)