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:

<!-- 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:

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

Changing Link Colors

Edit assets/scss/_variables.scss:

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

Adding Custom Component Styles

Edit assets/scss/_custom.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

hugo server

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

Production Build

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+):

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:

hugo server --disableFastRender

References

• Hugo Pipes SCSS Processing
• Bootstrap 5.3 Customization
• SCSS Documentation