markusgraf_ch/openspec/changes/archive/2025-10-30-add-minimal-hugo-site/design.md

Context

Converting an existing static HTML website (markusgraf.ch) to Hugo to enable template-based content management. The current site uses Bootstrap for styling, which will be preserved and upgraded to Bootstrap 5.x. This is a greenfield Hugo implementation with no existing templating infrastructure.

Goals / Non-Goals

Goals

• Create a maintainable Hugo project structure
• Preserve current website content and design
• Enable easy content updates through templates
• Establish foundation for future CV and blog sections
• Upgrade Bootstrap to latest 5.x version

Non-Goals

• Redesigning the website appearance
• Adding new content sections (CV, blog) in this change
• Implementing JavaScript features
• Setting up automated deployment pipelines
• SEO optimization

Decisions

Hugo Configuration Format

Decision: Use hugo.toml (TOML format) for configuration.

Rationale: TOML is Hugo's default and most commonly used format, providing good readability for simple configurations.

Alternatives considered:

• YAML: More verbose for simple configs, but we'll keep it as an option if complex nested structures are needed later
• JSON: Less human-readable for configuration files

Bootstrap Integration Method

Decision: Use CDN links for Bootstrap CSS in the base layout template.

Rationale:

• Simplest approach for static site
• No build process needed for CSS
• Fast loading via CDN
• Easy to upgrade versions

Alternatives considered:

• Local Bootstrap files: Adds unnecessary files to repository
• Hugo Pipes with SCSS: Overkill for current needs (no custom SCSS)
• npm integration: Unnecessary complexity without JavaScript build needs

Template Organization

Decision: Use standard Hugo template hierarchy with baseof.html and minimal partials.

Rationale:

• Follows Hugo best practices
• Keeps templates DRY (Don't Repeat Yourself)
• Makes future extensions straightforward
• Header, footer, and nav are natural partial candidates

Structure:

layouts/
├── _default/
│   ├── baseof.html      # Base template with Bootstrap integration
│   ├── single.html      # Single page template
│   └── list.html        # List template (future blog)
├── index.html           # Homepage template
└── partials/
    ├── header.html      # Site header with nav
    ├── footer.html      # Site footer
    └── nav.html         # Navigation menu

Content Structure

Decision: Start with simple markdown files in /content directory, one file per page.

Rationale:

• Simple and sufficient for current needs
• Easy to understand and maintain
• Can evolve to page bundles when needed for CV/blog

Risks / Trade-offs

Risk: Bootstrap CDN Availability

Mitigation: Use well-established CDN (jsDelivr or official Bootstrap CDN) with high uptime. Can switch to local files later if needed.

Risk: Content Migration Accuracy

Mitigation: Manual review of each page after conversion. Keep reference to original HTML during development.

Trade-off: CDN vs Local Assets

Chosen: CDN for simplicity and performance Trade-off: Slight dependency on external service, but acceptable for personal site

Migration Plan

Phase 1: Setup (Tasks 1.1-1.3)

1. Run hugo new site to scaffold structure
2. Create and configure hugo.toml
3. Verify directory structure

Phase 2: Templates (Tasks 2.1-3.3)

1. Build baseof.html with Bootstrap CDN links
2. Create homepage template based on current site
3. Create reusable partials
4. Test template rendering with placeholder content

Phase 3: Content (Tasks 5.1-5.3)

1. Review and document current site structure
2. Create markdown content files
3. Copy static assets to /static directory

Phase 4: Validation (Tasks 6.1-6.5)

1. Build site with hugo
2. Run local server with hugo server
3. Test all pages and responsive behavior
4. Validate HTML and accessibility

Rollback

If Hugo migration fails or is unsatisfactory:

• Original static HTML is preserved separately
• Can revert to static hosting immediately
• No database or external dependencies to roll back

Open Questions

None at this time. Implementation is straightforward following Hugo conventions.