Init Astro site with Docker and AI workflows
- Add landing page and base layout with cozy theme - Configure Astro, TypeScript, and project settings - Add Dockerfile, Nginx config, and docker-compose - Include favicon and site metadata - Add documentation: README, DEVELOPMENT, PROJECT_CONTEXT, TODO, CLAUDE - Add Gitea workflows for AI chat, PR review, issue triage, and codebase review
This commit is contained in:
+292
@@ -0,0 +1,292 @@
|
||||
# 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
|
||||
│ └── components/ # (Empty - ready for future components)
|
||||
├── public/
|
||||
│ └── favicon.svg # Site favicon (coffee emoji)
|
||||
├── astro.config.mjs # Astro configuration
|
||||
├── 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`:
|
||||
|
||||
```css
|
||||
--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 Mats
|
||||
4. **Services** - List of self-hosted services
|
||||
5. **Support** - Ways to help/contribute
|
||||
6. **Footer** - Links and credits
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Local Development
|
||||
|
||||
1. Install dependencies:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
2. Start dev server (with hot reload):
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
Server runs at `http://localhost:4321`
|
||||
|
||||
3. Build for production:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
Output goes to `dist/` directory
|
||||
|
||||
4. Preview production build:
|
||||
```bash
|
||||
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)
|
||||
|
||||
```bash
|
||||
docker build -t cozy-den .
|
||||
```
|
||||
|
||||
### Running Locally
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:80 --name cozy-den cozy-den
|
||||
```
|
||||
|
||||
Access at `http://localhost:3000`
|
||||
|
||||
### Using Docker Compose
|
||||
|
||||
```bash
|
||||
# Start
|
||||
docker-compose up -d
|
||||
|
||||
# Stop
|
||||
docker-compose down
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
### Deploying to Gitea Registry
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```astro
|
||||
---
|
||||
// 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:
|
||||
```astro
|
||||
---
|
||||
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:
|
||||
```astro
|
||||
<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:
|
||||
```css
|
||||
@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](https://docs.astro.build)
|
||||
- [Astro Components](https://docs.astro.build/en/core-concepts/astro-components/)
|
||||
- [Astro Styling](https://docs.astro.build/en/guides/styling/)
|
||||
- [Docker Documentation](https://docs.docker.com)
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user