Cozy-Den/DEVELOPMENT.md

Cozy Den - Developer Documentation

Project Overview

Cozy Den is a landing page for hiddenden.cafe built with Astro. The site features a warm, cozy aesthetic inspired by coffee shops and hidden dens, representing values of privacy, self-hosting, and open-source software.

Tech Stack:

• Astro 4.x (Static Site Generator)
• TypeScript (strict mode)
• Vanilla CSS with CSS Custom Properties
• Docker + Nginx for deployment
• Node.js 18+

Project Structure

cozy-den/
├── src/
│   ├── layouts/
│   │   └── BaseLayout.astro      # Base HTML layout with global styles
│   ├── pages/
│   │   ├── index.astro            # Main landing page
│   │   └── 404.astro              # Custom 404 error page
│   └── components/                # (Empty - ready for future components)
├── public/
│   ├── favicon.svg                # Site favicon (coffee emoji)
│   └── robots.txt                 # Search engine directives
├── astro.config.mjs               # Astro configuration with sitemap
├── package.json                   # Node dependencies
├── tsconfig.json                  # TypeScript configuration
├── Dockerfile                     # Multi-stage Docker build
├── docker-compose.yml             # Docker Compose setup
├── nginx.conf                     # Nginx configuration for production
├── .gitignore                     # Git ignore rules
└── README.md                      # User-facing documentation

Color Palette

The site uses CSS custom properties for theming. All colors are defined in src/layouts/BaseLayout.astro:

--color-bg: #1a1410           /* Dark background (deep coffee) */
--color-bg-light: #2a1f18     /* Lighter background for cards */
--color-text: #f4e9d8          /* Cream text */
--color-text-dim: #c4b5a0      /* Dimmed text for less emphasis */
--color-accent: #d4a574        /* Warm accent (coffee with cream) */
--color-accent-bright: #e8bf8e /* Brighter accent for highlights */
--color-warm: #8b6f47          /* Warm brown for borders/accents */

Component Architecture

BaseLayout.astro

The base layout provides:

• HTML structure and meta tags
• Global CSS reset and typography
• CSS custom properties for theming
• Global animations (fadeIn)

index.astro

The main page includes these sections:

1. Hero - Title and subtitle
2. About Hidden Den - Information about the site/space
3. About Me - Information about Latte
4. Services - List of self-hosted services
5. Support - Ways to help/contribute
6. Footer - Links and credits

404.astro

Custom error page with:

• Themed styling matching the cozy aesthetic
• Clear error message ("Lost in the Den?")
• Action buttons to return home or visit Gitea
• Responsive design for all devices

Development Workflow

Local Development

1. Install dependencies:

npm install

2. Start dev server (with hot reload):

npm run dev

Server runs at http://localhost:4321

3. Build for production:

npm run build

Output goes to dist/ directory

4. Preview production build:

npm run preview

Making Changes

Adding a new section:

1. Edit src/pages/index.astro
2. Add a new <section class="section new-section"> block
3. Style it in the <style> tag at the bottom
4. Use the .card class for consistent styling

Changing colors:

1. Edit CSS custom properties in src/layouts/BaseLayout.astro
2. All components will automatically update

Adding a service:

1. Add a new .service-item div in the Services section
2. Follow the existing structure with h3 link and description

Adding images:

1. Place images in public/ directory
2. Reference them with /image.jpg in your code
3. They'll be served as static assets

Docker Deployment

Building the Image

The Dockerfile uses a multi-stage build:

• Stage 1: Node builder (builds Astro site)
• Stage 2: Nginx server (serves static files)

docker build -t cozy-den .

Running Locally

docker run -d -p 3000:80 --name cozy-den cozy-den

Access at http://localhost:3000

Using Docker Compose

# Start
docker-compose up -d

# Stop
docker-compose down

# View logs
docker-compose logs -f

Deploying to Gitea Registry

# Tag for Gitea registry
docker tag cozy-den git.hiddenden.cafe/mats/cozy-den:latest

# Login to Gitea
docker login git.hiddenden.cafe

# Push
docker push git.hiddenden.cafe/mats/cozy-den:latest

Astro-Specific Information

File Extensions

• .astro - Astro components (HTML-like syntax with embedded JS)
• .mjs - ES module JavaScript files

Frontmatter

Code between --- at the top of .astro files runs at build time:

---
// This runs at build time (server-side)
const title = "My Page";
---
<h1>{title}</h1>

Styling

• <style> tags in .astro files are scoped by default
• Use <style is:global> for global styles
• CSS is processed and optimized automatically

Static Generation

Astro generates static HTML at build time. No JavaScript runtime needed for this site (pure HTML/CSS output).

Common Tasks

Task: Add a new page

1. Create src/pages/newpage.astro
2. Import BaseLayout
3. Add content
4. Page will be available at /newpage

Example:

---
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="New Page">
  <div class="container">
    <h1>New Page</h1>
  </div>
</BaseLayout>

Task: Add a new section to homepage

1. Open src/pages/index.astro
2. Add new section before footer:

<section class="section my-section">
  <div class="container">
    <div class="card fade-in">
      <h2>My Section</h2>
      <p>Content here</p>
    </div>
  </div>
</section>

3. Add styles in the <style> tag if needed

Task: Change the accent color

1. Open src/layouts/BaseLayout.astro
2. Modify --color-accent and --color-accent-bright
3. Site updates automatically

Task: Add animation to new element

1. Add fade-in class to element
2. Or create new animation in BaseLayout.astro:

@keyframes slideIn {
  from { transform: translateX(-20px); opacity: 0; }
  to { transform: translateX(0); opacity: 1; }
}
.slide-in { animation: slideIn 0.6s ease-out; }

Troubleshooting

Build fails with TypeScript errors

• Check tsconfig.json extends correct config
• Ensure all props are properly typed in components

Styles not applying

• Check if you need is:global on style tag
• Verify CSS custom properties are defined in BaseLayout

Docker build fails

• Ensure package.json and package-lock.json are present
• Check Node version compatibility (needs 18+)

Changes not showing in dev

• Hard refresh browser (Ctrl+Shift+R)
• Restart dev server
• Clear .astro cache directory

Future Enhancements

Ideas for future development:

• Add blog section using Astro's content collections
• Create reusable components for service items
• Add dark/light theme toggle
• Implement contact form
• Add RSS feed for blog
• Create custom 404 page
• Add more animations and transitions
• Integrate with analytics (privacy-friendly)

Resources

• Astro Documentation
• Astro Components
• Astro Styling
• Docker Documentation

Notes for AI Assistants

When working with this project:

1. Maintain the cozy aesthetic (warm colors, soft animations)
2. Keep the site lightweight and fast (static HTML/CSS)
3. Follow the existing component structure
4. Use CSS custom properties for theming
5. Ensure responsive design for mobile
6. Add appropriate TypeScript types when needed
7. Test both dev and production builds
8. Verify Docker build works after changes