markusgraf_ch/docs/SCSS_STYLING.md

# Custom SCSS Styling

This document describes the SCSS-based custom styling system for the markusgraf.ch Hugo site.

## Overview

The site uses a hybrid approach for styling:
- **Bootstrap 5.3.2** loaded from CDN (core framework)
- **Custom SCSS** compiled via Hugo Pipes (overrides and custom styles)

This approach provides the benefits of Bootstrap's CDN (speed, caching) while allowing complete customization through SCSS.

## File Structure

```
assets/scss/
├── main.scss          # Main entry point (imports all partials)
├── _variables.scss    # Bootstrap variable overrides
└── _custom.scss       # Custom component styles
```

### main.scss
The main entry point that Hugo processes. This file imports all SCSS partials in the correct order.

### _variables.scss
Bootstrap variable overrides for customizing design tokens:
- Heading font sizes (h1-h6)
- Link colors and hover states
- Spacing scale (optional)
- Any other Bootstrap variables

### _custom.scss
Custom component styles and utilities that extend Bootstrap or add new styles.

## How It Works

### Compilation Process

1. Hugo reads `assets/scss/main.scss`
2. Hugo processes SCSS with `css.Sass` function
3. Output is minified (`outputStyle: compressed`)
4. CSS is fingerprinted with SHA-384 for cache busting
5. Integrity hash is added to the `<link>` tag

### CSS Load Order

In `layouts/_default/baseof.html`:

```html
<!-- Bootstrap CDN CSS (base styles) -->
<link href="https://cdn.jsdelivr.net/.../bootstrap.min.css" rel="stylesheet">

<!-- Custom compiled CSS (overrides) -->
<link rel="stylesheet" href="/css/main.[fingerprint].css" integrity="sha384-...">
```

This order ensures custom styles cascade over Bootstrap defaults.

## Customization Guide

### Changing Heading Sizes

Edit `assets/scss/_variables.scss`:

```scss
$h1-font-size: 3rem;     // Make h1 larger
$h2-font-size: 2.25rem;  // Make h2 larger
```

### Changing Link Colors

Edit `assets/scss/_variables.scss`:

```scss
$link-color: #0066cc;        // Primary link color
$link-hover-color: #0052a3;  // Hover state color
```

### Adding Custom Component Styles

Edit `assets/scss/_custom.scss`:

```scss
.navbar-brand {
  font-weight: 700;
  letter-spacing: 0.05em;
}

.card {
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}
```

### Adding New SCSS Partials

1. Create a new file: `assets/scss/_mypartial.scss`
2. Import it in `main.scss`: `@import 'mypartial';`

## Development Workflow

### Development Mode

```bash
hugo server
```

- SCSS changes trigger automatic recompilation
- Browser live-reloads with updated styles
- Source maps are available for debugging

### Production Build

```bash
hugo build
```

- SCSS is compiled with minification
- No source maps are included
- CSS is fingerprinted for cache busting

## Performance

- Custom CSS file size: ~154 bytes (current)
- Minified and compressed
- Cached via fingerprinting
- Minimal impact on page load

## Best Practices

1. **Keep it minimal** - Only override what you need
2. **Use SCSS features** - Variables, nesting, mixins when beneficial
3. **Organize by concern** - Use partials to separate different types of styles
4. **Comment your code** - Explain why specific overrides are needed
5. **Test in multiple browsers** - Ensure compatibility

## Troubleshooting

### SCSS Won't Compile

Check Hugo version supports `css.Sass` (v0.128.0+):
```bash
hugo version
```

### Styles Not Applying

1. Check CSS load order in browser DevTools
2. Verify fingerprinted CSS file exists in `public/css/`
3. Check for SCSS syntax errors in Hugo output

### Cache Issues

The fingerprinting ensures cache busting, but during development you can:
```bash
hugo server --disableFastRender
```

## References

- [Hugo Pipes SCSS Processing](https://gohugo.io/hugo-pipes/scss-sass/)
- [Bootstrap 5.3 Customization](https://getbootstrap.com/docs/5.3/customize/sass/)
- [SCSS Documentation](https://sass-lang.com/documentation)