gurix/markusgraf_ch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: initialize Hugo static site with Bootstrap 5.x

Browse Source 
Initialize minimal Hugo site structure with Bootstrap 5.3.2 integration for
markusgraf.ch conversion. Implements OpenSpec proposal add-minimal-hugo-site.

Features:
- Hugo project structure with standard directories
- Base layout template (baseof.html) with Bootstrap 5.3.2 via CDN
- Homepage (index.html) and single page (single.html) templates
- Reusable partials: header, footer, navigation
- Responsive Bootstrap grid layout
- Mobile-first design with semantic HTML5
- Valid HTML output with basic accessibility features
- Taxonomies disabled for minimal site (see docs/TAXONOMIES.md)

Documentation:
- IMPLEMENTATION_SUMMARY.md - Complete implementation guide
- docs/TAXONOMIES.md - Guide for re-enabling categories/tags
- static/README.md - Guide for placing static assets

Configuration:
- hugo.toml configured for markusgraf.ch
- .gitignore for Hugo build artifacts

All 24 tasks from OpenSpec proposal completed successfully.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Markus Graf
2025-10-27 10:25:11 +01:00
co-authored by Claude
commit d36a18d28b
25 changed files with 1532 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
openspec/AGENTS.md
+454
View File
@@ -0,0 +1,454 @@
# OpenSpec Instructions
Instructions for AI coding assistants using OpenSpec for spec-driven development.
## TL;DR Quick Checklist
- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search)
- Decide scope: new capability vs modify existing capability
- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`)
- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability
- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement
- Validate: `openspec validate [change-id] --strict` and fix issues
- Request approval: Do not start implementation until proposal is approved
## Three-Stage Workflow
### Stage 1: Creating Changes
Create proposal when you need to:
- Add features or functionality
- Make breaking changes (API, schema)
- Change architecture or patterns
- Optimize performance (changes behavior)
- Update security patterns
Triggers (examples):
- "Help me create a change proposal"
- "Help me plan a change"
- "Help me create a proposal"
- "I want to create a spec proposal"
- "I want to create a spec"
Loose matching guidance:
- Contains one of: `proposal`, `change`, `spec`
- With one of: `create`, `plan`, `make`, `start`, `help`
Skip proposal for:
- Bug fixes (restore intended behavior)
- Typos, formatting, comments
- Dependency updates (non-breaking)
- Configuration changes
- Tests for existing behavior
**Workflow**
1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context.
2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes/<id>/`.
3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.
4. Run `openspec validate <id> --strict` and resolve any issues before sharing the proposal.
### Stage 2: Implementing Changes
Track these steps as TODOs and complete them one by one.
1. **Read proposal.md** - Understand what's being built
2. **Read design.md** (if exists) - Review technical decisions
3. **Read tasks.md** - Get implementation checklist
4. **Implement tasks sequentially** - Complete in order
5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses
6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality
7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved
### Stage 3: Archiving Changes
After deployment, create separate PR to:
- Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
- Update `specs/` if capabilities changed
- Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly)
- Run `openspec validate --strict` to confirm the archived change passes checks
## Before Any Task
**Context Checklist:**
- [ ] Read relevant specs in `specs/[capability]/spec.md`
- [ ] Check pending changes in `changes/` for conflicts
- [ ] Read `openspec/project.md` for conventions
- [ ] Run `openspec list` to see active changes
- [ ] Run `openspec list --specs` to see existing capabilities
**Before Creating Specs:**
- Always check if capability already exists
- Prefer modifying existing specs over creating duplicates
- Use `openspec show [spec]` to review current state
- If request is ambiguous, ask 1–2 clarifying questions before scaffolding
### Search Guidance
- Enumerate specs: `openspec spec list --long` (or `--json` for scripts)
- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available)
- Show details:
- Spec: `openspec show <spec-id> --type spec` (use `--json` for filters)
- Change: `openspec show <change-id> --json --deltas-only`
- Full-text search (use ripgrep): `rg -n "Requirement:|Scenario:" openspec/specs`
## Quick Start
### CLI Commands
```bash
# Essential commands
openspec list # List active changes
openspec list --specs # List specifications
openspec show [item] # Display change or spec
openspec validate [item] # Validate changes or specs
openspec archive <change-id> [--yes|-y] # Archive after deployment (add --yes for non-interactive runs)
# Project management
openspec init [path] # Initialize OpenSpec
openspec update [path] # Update instruction files
# Interactive mode
openspec show # Prompts for selection
openspec validate # Bulk validation mode
# Debugging
openspec show [change] --json --deltas-only
openspec validate [change] --strict
```
### Command Flags
- `--json` - Machine-readable output
- `--type change|spec` - Disambiguate items
- `--strict` - Comprehensive validation
- `--no-interactive` - Disable prompts
- `--skip-specs` - Archive without spec updates
- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive)
## Directory Structure
```
openspec/
├── project.md # Project conventions
├── specs/ # Current truth - what IS built
│ └── [capability]/ # Single focused capability
│ ├── spec.md # Requirements and scenarios
│ └── design.md # Technical patterns
├── changes/ # Proposals - what SHOULD change
│ ├── [change-name]/
│ │ ├── proposal.md # Why, what, impact
│ │ ├── tasks.md # Implementation checklist
│ │ ├── design.md # Technical decisions (optional; see criteria)
│ │ └── specs/ # Delta changes
│ │ └── [capability]/
│ │ └── spec.md # ADDED/MODIFIED/REMOVED
│ └── archive/ # Completed changes
```
## Creating Change Proposals
### Decision Tree
```
New request?
├─ Bug fix restoring spec behavior? → Fix directly
├─ Typo/format/comment? → Fix directly
├─ New feature/capability? → Create proposal
├─ Breaking change? → Create proposal
├─ Architecture change? → Create proposal
└─ Unclear? → Create proposal (safer)
```
### Proposal Structure
1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique)
2. **Write proposal.md:**
```markdown
## Why
[1-2 sentences on problem/opportunity]
## What Changes
- [Bullet list of changes]
- [Mark breaking changes with **BREAKING**]
## Impact
- Affected specs: [list capabilities]
- Affected code: [key files/systems]
```
3. **Create spec deltas:** `specs/[capability]/spec.md`
```markdown
## ADDED Requirements
### Requirement: New Feature
The system SHALL provide...
#### Scenario: Success case
- **WHEN** user performs action
- **THEN** expected result
## MODIFIED Requirements
### Requirement: Existing Feature
[Complete modified requirement]
## REMOVED Requirements
### Requirement: Old Feature
**Reason**: [Why removing]
**Migration**: [How to handle]
```
If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs/<capability>/spec.md`—one per capability.
4. **Create tasks.md:**
```markdown
## 1. Implementation
- [ ] 1.1 Create database schema
- [ ] 1.2 Implement API endpoint
- [ ] 1.3 Add frontend component
- [ ] 1.4 Write tests
```
5. **Create design.md when needed:**
Create `design.md` if any of the following apply; otherwise omit it:
- Cross-cutting change (multiple services/modules) or a new architectural pattern
- New external dependency or significant data model changes
- Security, performance, or migration complexity
- Ambiguity that benefits from technical decisions before coding
Minimal `design.md` skeleton:
```markdown
## Context
[Background, constraints, stakeholders]
## Goals / Non-Goals
- Goals: [...]
- Non-Goals: [...]
## Decisions
- Decision: [What and why]
- Alternatives considered: [Options + rationale]
## Risks / Trade-offs
- [Risk] → Mitigation
## Migration Plan
[Steps, rollback]
## Open Questions
- [...]
```
## Spec File Format
### Critical: Scenario Formatting
**CORRECT** (use #### headers):
```markdown
#### Scenario: User login success
- **WHEN** valid credentials provided
- **THEN** return JWT token
```
**WRONG** (don't use bullets or bold):
```markdown
- **Scenario: User login** ❌
**Scenario**: User login ❌
### Scenario: User login ❌
```
Every requirement MUST have at least one scenario.
### Requirement Wording
- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative)
### Delta Operations
- `## ADDED Requirements` - New capabilities
- `## MODIFIED Requirements` - Changed behavior
- `## REMOVED Requirements` - Deprecated features
- `## RENAMED Requirements` - Name changes
Headers matched with `trim(header)` - whitespace ignored.
#### When to use ADDED vs MODIFIED
- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement.
- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.
- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
Authoring a MODIFIED requirement correctly:
1) Locate the existing requirement in `openspec/specs/<capability>/spec.md`.
2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios).
3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.
4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.
Example for RENAMED:
```markdown
## RENAMED Requirements
- FROM: `### Requirement: Login`
- TO: `### Requirement: User Authentication`
```
## Troubleshooting
### Common Errors
**"Change must have at least one delta"**
- Check `changes/[name]/specs/` exists with .md files
- Verify files have operation prefixes (## ADDED Requirements)
**"Requirement must have at least one scenario"**
- Check scenarios use `#### Scenario:` format (4 hashtags)
- Don't use bullet points or bold for scenario headers
**Silent scenario parsing failures**
- Exact format required: `#### Scenario: Name`
- Debug with: `openspec show [change] --json --deltas-only`
### Validation Tips
```bash
# Always use strict mode for comprehensive checks
openspec validate [change] --strict
# Debug delta parsing
openspec show [change] --json | jq '.deltas'
# Check specific requirement
openspec show [spec] --json -r 1
```
## Happy Path Script
```bash
# 1) Explore current state
openspec spec list --long
openspec list
# Optional full-text search:
# rg -n "Requirement:|Scenario:" openspec/specs
# rg -n "^#|Requirement:" openspec/changes
# 2) Choose change id and scaffold
CHANGE=add-two-factor-auth
mkdir -p openspec/changes/$CHANGE/{specs/auth}
printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md
printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md
# 3) Add deltas (example)
cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF'
## ADDED Requirements
### Requirement: Two-Factor Authentication
Users MUST provide a second factor during login.
#### Scenario: OTP required
- **WHEN** valid credentials are provided
- **THEN** an OTP challenge is required
EOF
# 4) Validate
openspec validate $CHANGE --strict
```
## Multi-Capability Example
```
openspec/changes/add-2fa-notify/
├── proposal.md
├── tasks.md
└── specs/
├── auth/
│ └── spec.md # ADDED: Two-Factor Authentication
└── notifications/
└── spec.md # ADDED: OTP email notification
```
auth/spec.md
```markdown
## ADDED Requirements
### Requirement: Two-Factor Authentication
...
```
notifications/spec.md
```markdown
## ADDED Requirements
### Requirement: OTP Email Notification
...
```
## Best Practices
### Simplicity First
- Default to <100 lines of new code
- Single-file implementations until proven insufficient
- Avoid frameworks without clear justification
- Choose boring, proven patterns
### Complexity Triggers
Only add complexity with:
- Performance data showing current solution too slow
- Concrete scale requirements (>1000 users, >100MB data)
- Multiple proven use cases requiring abstraction
### Clear References
- Use `file.ts:42` format for code locations
- Reference specs as `specs/auth/spec.md`
- Link related changes and PRs
### Capability Naming
- Use verb-noun: `user-auth`, `payment-capture`
- Single purpose per capability
- 10-minute understandability rule
- Split if description needs "AND"
### Change ID Naming
- Use kebab-case, short and descriptive: `add-two-factor-auth`
- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-`
- Ensure uniqueness; if taken, append `-2`, `-3`, etc.
## Tool Selection Guide
| Task | Tool | Why |
|------|------|-----|
| Find files by pattern | Glob | Fast pattern matching |
| Search code content | Grep | Optimized regex search |
| Read specific files | Read | Direct file access |
| Explore unknown scope | Task | Multi-step investigation |
## Error Recovery
### Change Conflicts
1. Run `openspec list` to see active changes
2. Check for overlapping specs
3. Coordinate with change owners
4. Consider combining proposals
### Validation Failures
1. Run with `--strict` flag
2. Check JSON output for details
3. Verify spec file format
4. Ensure scenarios properly formatted
### Missing Context
1. Read project.md first
2. Check related specs
3. Review recent archives
4. Ask for clarification
## Quick Reference
### Stage Indicators
- `changes/` - Proposed, not yet built
- `specs/` - Built and deployed
- `archive/` - Completed changes
### File Purposes
- `proposal.md` - Why and what
- `tasks.md` - Implementation steps
- `design.md` - Technical decisions
- `spec.md` - Requirements and behavior
### CLI Essentials
```bash
openspec list # What's in progress?
openspec show [item] # View details
openspec validate --strict # Is it correct?
openspec archive <change-id> [--yes|-y] # Mark complete (add --yes for automation)
```
Remember: Specs are truth. Changes are proposals. Keep them in sync.
openspec/changes/add-minimal-hugo-site/design.md
+118
View File
@@ -0,0 +1,118 @@
## 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.
openspec/changes/add-minimal-hugo-site/proposal.md
+15
View File
@@ -0,0 +1,15 @@
## Why
The current markusgraf.ch website uses static HTML files. Converting to Hugo will provide a maintainable template-based structure that simplifies future content updates and enables easy addition of new sections (CV, blog) without duplicating code.
## What Changes
- Initialize Hugo project structure with standard directories
- Create base layout template with Bootstrap 5.x integration
- Set up reusable partials (header, footer, navigation)
- Convert existing HTML content to Hugo templates
- Configure Hugo site settings
- Add static assets from current website
## Impact
- Affected specs: hugo-site (new capability)
- Affected code: This is a greenfield implementation - no existing code affected
- Migration: Current static HTML will be referenced to recreate in Hugo templates
openspec/changes/add-minimal-hugo-site/specs/hugo-site/spec.md
+129
View File
@@ -0,0 +1,129 @@
## ADDED Requirements
### Requirement: Hugo Project Structure
The system SHALL initialize a Hugo static site with the standard directory structure including layouts, content, static, and data directories.
#### Scenario: Hugo site initialized
- **WHEN** Hugo site is created
- **THEN** the following directories exist: layouts/, content/, static/, data/
- **AND** a hugo.toml configuration file is present at the root
#### Scenario: Hugo builds successfully
- **WHEN** running `hugo` command
- **THEN** the site builds without errors
- **AND** generates static HTML files in the public/ directory
### Requirement: Base Layout Template
The system SHALL provide a baseof.html template that defines the common HTML structure for all pages, including Bootstrap 5.x integration.
#### Scenario: Base layout includes Bootstrap
- **WHEN** any page is rendered
- **THEN** the HTML output includes Bootstrap 5.x CSS from CDN
- **AND** the page has proper HTML5 doctype and meta tags
- **AND** the page is responsive with Bootstrap's viewport meta tag
#### Scenario: Base layout includes header and footer
- **WHEN** any page is rendered
- **THEN** the page includes the header partial
- **AND** the page includes the footer partial
- **AND** the main content block is properly positioned between them
### Requirement: Reusable Partials
The system SHALL provide reusable partial templates for header, footer, and navigation components.
#### Scenario: Header partial exists
- **WHEN** baseof.html calls the header partial
- **THEN** the header is rendered with consistent styling across all pages
#### Scenario: Footer partial exists
- **WHEN** baseof.html calls the footer partial
- **THEN** the footer is rendered with consistent styling across all pages
#### Scenario: Navigation partial exists
- **WHEN** header includes navigation
- **THEN** the navigation menu renders with links to main pages
- **AND** uses Bootstrap navigation components
### Requirement: Homepage Template
The system SHALL provide an index.html template for the homepage that extends baseof.html and displays the main landing content.
#### Scenario: Homepage renders correctly
- **WHEN** accessing the root URL
- **THEN** the homepage template is used
- **AND** displays content from content/_index.md
- **AND** matches the structure of the existing markusgraf.ch homepage
### Requirement: Single Page Template
The system SHALL provide a default single.html template for individual content pages.
#### Scenario: Single page renders correctly
- **WHEN** accessing any content page
- **THEN** the single page template is used
- **AND** displays the page title
- **AND** renders the markdown content as HTML
### Requirement: Static Assets
The system SHALL serve static assets (images, fonts, CSS files) from the static/ directory.
#### Scenario: Static files are accessible
- **WHEN** a static file is placed in static/
- **THEN** it is accessible at the site root in the built site
- **AND** preserves the directory structure from static/
### Requirement: Content Management
The system SHALL support markdown files in the content/ directory that are rendered into HTML pages.
#### Scenario: Markdown content is rendered
- **WHEN** a markdown file exists in content/
- **THEN** Hugo processes it into an HTML page
- **AND** front matter variables are accessible in templates
#### Scenario: Page metadata
- **WHEN** a content file has front matter
- **THEN** title, date, and other metadata are available in templates
- **AND** can be used for page titles and navigation
### Requirement: Configuration
The system SHALL use hugo.toml for site configuration including baseURL, title, and language settings.
#### Scenario: Site configuration is applied
- **WHEN** hugo.toml contains site settings
- **THEN** those settings are used during site generation
- **AND** site title appears in page titles
- **AND** baseURL is used for absolute URLs
### Requirement: Responsive Design
The system SHALL render pages that are responsive and mobile-friendly using Bootstrap's grid system and responsive utilities.
#### Scenario: Mobile viewport
- **WHEN** viewing the site on mobile devices
- **THEN** the layout adapts to small screens
- **AND** navigation is accessible
- **AND** content is readable without horizontal scrolling
#### Scenario: Tablet and desktop viewports
- **WHEN** viewing the site on larger screens
- **THEN** the layout utilizes available space appropriately
- **AND** maintains readability and visual hierarchy
### Requirement: HTML Validity
The system SHALL generate valid HTML5 markup that passes standard validation.
#### Scenario: Valid HTML output
- **WHEN** pages are generated
- **THEN** HTML is well-formed
- **AND** includes required DOCTYPE and meta tags
- **AND** uses semantic HTML5 elements where appropriate
### Requirement: Accessibility Basics
The system SHALL implement basic accessibility features including semantic HTML and proper heading hierarchy.
#### Scenario: Semantic HTML structure
- **WHEN** pages are rendered
- **THEN** content uses appropriate semantic elements (header, nav, main, footer, article)
- **AND** maintains logical heading hierarchy (h1, h2, h3)
#### Scenario: Navigation accessibility
- **WHEN** keyboard navigation is used
- **THEN** all interactive elements are focusable
- **AND** focus order is logical
openspec/changes/add-minimal-hugo-site/tasks.md
+31
View File
@@ -0,0 +1,31 @@
## 1. Hugo Project Setup
- [x] 1.1 Initialize Hugo site structure
- [x] 1.2 Create hugo.toml/yaml configuration file
- [x] 1.3 Set up directory structure (layouts, content, static, data)
## 2. Layout Templates
- [x] 2.1 Create baseof.html layout template
- [x] 2.2 Create index.html template for homepage
- [x] 2.3 Create default single page template
## 3. Partials
- [x] 3.1 Create header partial
- [x] 3.2 Create footer partial
- [x] 3.3 Create navigation partial
## 4. Bootstrap Integration
- [x] 4.1 Add Bootstrap 5.x CSS to project
- [x] 4.2 Configure Bootstrap in base layout
- [x] 4.3 Apply Bootstrap classes to templates
## 5. Content Migration
- [x] 5.1 Review existing markusgraf.ch HTML structure
- [x] 5.2 Create content files in Hugo format
- [x] 5.3 Migrate static assets (images, fonts, etc.)
## 6. Testing and Validation
- [x] 6.1 Test Hugo build locally
- [x] 6.2 Verify all pages render correctly
- [x] 6.3 Check responsive design on mobile/tablet/desktop
- [x] 6.4 Validate HTML output
- [x] 6.5 Test accessibility basics
openspec/project.md
+65
View File
@@ -0,0 +1,65 @@
# Project Context
## Purpose
Converting the existing static HTML website at markusgraf.ch into a Hugo-based static site. This project maintains the current content while establishing a foundation for future expansion with CV and blog sections.
## Tech Stack
- **Static Site Generator**: Hugo (latest stable version)
- **Templating**: Go templates (Hugo's templating engine)
- **Styling**: Bootstrap (upgrading from current version to latest Bootstrap 5.x)
- **Scripting**: None (no JavaScript/TypeScript at this stage)
- **Deployment**: Static HTML output
- **Version Control**: Git
## Project Conventions
### Code Style
- Use semantic HTML5 elements
- Follow Hugo best practices for template organization
- Use consistent indentation (2 spaces) in HTML and templates
- Keep templates DRY (Don't Repeat Yourself) using partials
- Use descriptive names for partials and layouts
- Comment complex template logic
### Architecture Patterns
- **Hugo Structure**: Follow standard Hugo directory structure
- `/layouts` - Template files (baseof.html, partials, shortcodes)
- `/content` - Markdown content files
- `/static` - Static assets (images, fonts, etc.)
- `/assets` - Files to be processed (SCSS, if needed)
- `/data` - Data files (YAML, JSON, TOML)
- `/config.toml` (or config.yaml) - Site configuration
- **Template Hierarchy**: Use Hugo's template lookup order effectively
- **Partials**: Break down templates into reusable partials (header, footer, nav, etc.)
- **Content Organization**: Use page bundles and sections as appropriate
### Testing Strategy
- No automated testing currently implemented
- Manual testing in browsers for layout and functionality
- Playwright for E2E testing will be introduced in a future phase
### Git Workflow
- **Branching**: Feature branches from `main` (e.g., `feature/convert-homepage`)
- **Commits**: Conventional commits format (feat:, fix:, docs:, refactor:, etc.)
- **PRs**: Required for all changes, squash and merge
- **Branch Protection**: Main branch requires review
## Domain Context
Currently migrating existing markusgraf.ch content to Hugo:
- Existing static HTML pages and content
- Current design and layout using Bootstrap
Future planned additions:
- Curriculum Vitae (CV) page
- Blog section
The migration focuses on preserving current content and functionality while establishing a maintainable Hugo foundation.
## Important Constraints
- Must be performant (Lighthouse score >90)
- Must be accessible (WCAG 2.1 AA compliance)
- Must be responsive (mobile-first design)
- Keep output file size minimal
## External Dependencies
None currently required. Site is fully self-contained static HTML.