119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
|
## 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.
|