diff --git a/openspec/changes/add-custom-bootstrap-styling/proposal.md b/openspec/changes/archive/2025-10-30-add-custom-bootstrap-styling/proposal.md similarity index 100% rename from openspec/changes/add-custom-bootstrap-styling/proposal.md rename to openspec/changes/archive/2025-10-30-add-custom-bootstrap-styling/proposal.md diff --git a/openspec/changes/add-custom-bootstrap-styling/specs/styling/spec.md b/openspec/changes/archive/2025-10-30-add-custom-bootstrap-styling/specs/styling/spec.md similarity index 100% rename from openspec/changes/add-custom-bootstrap-styling/specs/styling/spec.md rename to openspec/changes/archive/2025-10-30-add-custom-bootstrap-styling/specs/styling/spec.md diff --git a/openspec/changes/add-custom-bootstrap-styling/tasks.md b/openspec/changes/archive/2025-10-30-add-custom-bootstrap-styling/tasks.md similarity index 100% rename from openspec/changes/add-custom-bootstrap-styling/tasks.md rename to openspec/changes/archive/2025-10-30-add-custom-bootstrap-styling/tasks.md diff --git a/openspec/changes/add-cv-page/proposal.md b/openspec/changes/archive/2025-10-30-add-cv-page/proposal.md similarity index 100% rename from openspec/changes/add-cv-page/proposal.md rename to openspec/changes/archive/2025-10-30-add-cv-page/proposal.md diff --git a/openspec/changes/add-cv-page/specs/content-management/spec.md b/openspec/changes/archive/2025-10-30-add-cv-page/specs/content-management/spec.md similarity index 100% rename from openspec/changes/add-cv-page/specs/content-management/spec.md rename to openspec/changes/archive/2025-10-30-add-cv-page/specs/content-management/spec.md diff --git a/openspec/changes/add-cv-page/tasks.md b/openspec/changes/archive/2025-10-30-add-cv-page/tasks.md similarity index 100% rename from openspec/changes/add-cv-page/tasks.md rename to openspec/changes/archive/2025-10-30-add-cv-page/tasks.md diff --git a/openspec/changes/add-minimal-hugo-site/design.md b/openspec/changes/archive/2025-10-30-add-minimal-hugo-site/design.md similarity index 100% rename from openspec/changes/add-minimal-hugo-site/design.md rename to openspec/changes/archive/2025-10-30-add-minimal-hugo-site/design.md diff --git a/openspec/changes/add-minimal-hugo-site/proposal.md b/openspec/changes/archive/2025-10-30-add-minimal-hugo-site/proposal.md similarity index 100% rename from openspec/changes/add-minimal-hugo-site/proposal.md rename to openspec/changes/archive/2025-10-30-add-minimal-hugo-site/proposal.md diff --git a/openspec/changes/add-minimal-hugo-site/specs/hugo-site/spec.md b/openspec/changes/archive/2025-10-30-add-minimal-hugo-site/specs/hugo-site/spec.md similarity index 100% rename from openspec/changes/add-minimal-hugo-site/specs/hugo-site/spec.md rename to openspec/changes/archive/2025-10-30-add-minimal-hugo-site/specs/hugo-site/spec.md diff --git a/openspec/changes/add-minimal-hugo-site/tasks.md b/openspec/changes/archive/2025-10-30-add-minimal-hugo-site/tasks.md similarity index 100% rename from openspec/changes/add-minimal-hugo-site/tasks.md rename to openspec/changes/archive/2025-10-30-add-minimal-hugo-site/tasks.md diff --git a/openspec/changes/add-multilingual-support/design.md b/openspec/changes/archive/2025-10-30-add-multilingual-support/design.md similarity index 100% rename from openspec/changes/add-multilingual-support/design.md rename to openspec/changes/archive/2025-10-30-add-multilingual-support/design.md diff --git a/openspec/changes/add-multilingual-support/proposal.md b/openspec/changes/archive/2025-10-30-add-multilingual-support/proposal.md similarity index 100% rename from openspec/changes/add-multilingual-support/proposal.md rename to openspec/changes/archive/2025-10-30-add-multilingual-support/proposal.md diff --git a/openspec/changes/add-multilingual-support/specs/internationalization/spec.md b/openspec/changes/archive/2025-10-30-add-multilingual-support/specs/internationalization/spec.md similarity index 100% rename from openspec/changes/add-multilingual-support/specs/internationalization/spec.md rename to openspec/changes/archive/2025-10-30-add-multilingual-support/specs/internationalization/spec.md diff --git a/openspec/changes/add-multilingual-support/tasks.md b/openspec/changes/archive/2025-10-30-add-multilingual-support/tasks.md similarity index 100% rename from openspec/changes/add-multilingual-support/tasks.md rename to openspec/changes/archive/2025-10-30-add-multilingual-support/tasks.md diff --git a/openspec/changes/migrate-site-content/design.md b/openspec/changes/archive/2025-10-30-migrate-site-content/design.md similarity index 100% rename from openspec/changes/migrate-site-content/design.md rename to openspec/changes/archive/2025-10-30-migrate-site-content/design.md diff --git a/openspec/changes/migrate-site-content/proposal.md b/openspec/changes/archive/2025-10-30-migrate-site-content/proposal.md similarity index 100% rename from openspec/changes/migrate-site-content/proposal.md rename to openspec/changes/archive/2025-10-30-migrate-site-content/proposal.md diff --git a/openspec/changes/migrate-site-content/specs/content-migration/spec.md b/openspec/changes/archive/2025-10-30-migrate-site-content/specs/content-migration/spec.md similarity index 100% rename from openspec/changes/migrate-site-content/specs/content-migration/spec.md rename to openspec/changes/archive/2025-10-30-migrate-site-content/specs/content-migration/spec.md diff --git a/openspec/changes/migrate-site-content/specs/image-assets/spec.md b/openspec/changes/archive/2025-10-30-migrate-site-content/specs/image-assets/spec.md similarity index 100% rename from openspec/changes/migrate-site-content/specs/image-assets/spec.md rename to openspec/changes/archive/2025-10-30-migrate-site-content/specs/image-assets/spec.md diff --git a/openspec/changes/migrate-site-content/tasks.md b/openspec/changes/archive/2025-10-30-migrate-site-content/tasks.md similarity index 100% rename from openspec/changes/migrate-site-content/tasks.md rename to openspec/changes/archive/2025-10-30-migrate-site-content/tasks.md diff --git a/openspec/changes/simple-deployment/proposal.md b/openspec/changes/archive/2025-10-30-simple-deployment/proposal.md similarity index 100% rename from openspec/changes/simple-deployment/proposal.md rename to openspec/changes/archive/2025-10-30-simple-deployment/proposal.md diff --git a/openspec/changes/simple-deployment/specs/deployment/spec.md b/openspec/changes/archive/2025-10-30-simple-deployment/specs/deployment/spec.md similarity index 100% rename from openspec/changes/simple-deployment/specs/deployment/spec.md rename to openspec/changes/archive/2025-10-30-simple-deployment/specs/deployment/spec.md diff --git a/openspec/changes/simple-deployment/tasks.md b/openspec/changes/archive/2025-10-30-simple-deployment/tasks.md similarity index 100% rename from openspec/changes/simple-deployment/tasks.md rename to openspec/changes/archive/2025-10-30-simple-deployment/tasks.md diff --git a/openspec/specs/content-management/spec.md b/openspec/specs/content-management/spec.md new file mode 100644 index 0000000..de4ef77 --- /dev/null +++ b/openspec/specs/content-management/spec.md @@ -0,0 +1,39 @@ +# content-management Specification + +## Purpose +TBD - created by archiving change add-cv-page. Update Purpose after archive. +## Requirements +### Requirement: CV Page Content +The site SHALL provide a dedicated curriculum vitae page that explains how to securely download the CV document and request additional materials. + +#### Scenario: CV page displays download instructions +- **WHEN** a visitor navigates to `/cv/` or clicks "Lebenslauf" in navigation +- **THEN** the page displays a clear explanation of the Tresorit download process +- **AND** the page includes the secure download link +- **AND** the page mentions email verification is required +- **AND** the page explains that certificates and references are available upon personal request + +#### Scenario: CV page uses German language +- **WHEN** the CV page is rendered +- **THEN** all text is displayed in German +- **AND** the tone is professional and suitable for HR personnel and recruiters + +#### Scenario: CV page follows site layout +- **WHEN** the CV page is rendered +- **THEN** it uses the standard single.html layout +- **AND** content is centered and readable +- **AND** it includes the site header and footer + +### Requirement: CV Navigation Link +The site navigation SHALL include a link to the CV page. + +#### Scenario: Navigation menu shows CV link +- **WHEN** a visitor views any page on the site +- **THEN** the navigation menu includes a "Lebenslauf" link +- **AND** the link points to `/cv/` +- **AND** the link follows the same styling as other navigation items + +#### Scenario: CV link active state +- **WHEN** a visitor is on the CV page +- **THEN** the "Lebenslauf" navigation link shows active state styling + diff --git a/openspec/specs/content-migration/spec.md b/openspec/specs/content-migration/spec.md new file mode 100644 index 0000000..b9dbf92 --- /dev/null +++ b/openspec/specs/content-migration/spec.md @@ -0,0 +1,86 @@ +# content-migration Specification + +## Purpose +TBD - created by archiving change migrate-site-content. Update Purpose after archive. +## Requirements +### Requirement: Content Extraction from Live Site +The system SHALL capture all text content, structure, and formatting from the live markusgraf.ch website to migrate into the Hugo project. + +#### Scenario: Extract homepage content from live site +- **GIVEN** the live markusgraf.ch website HTML source is provided +- **WHEN** the HTML is parsed for content extraction +- **THEN** all text content, headings, and structure are captured +- **AND** the content is organized by logical sections (bio, intro, projects, etc.) + +#### Scenario: Extract projects and portfolio content +- **GIVEN** the live site contains project or portfolio information +- **WHEN** projects are identified and extracted +- **THEN** each project has complete description captured +- **AND** project metadata and structure is documented + +### Requirement: Content Conversion to Hugo Format +The system SHALL convert extracted HTML content into Hugo-compatible markdown format while preserving formatting and structure. + +#### Scenario: Convert HTML to markdown +- **GIVEN** extracted HTML content from live site +- **WHEN** content is converted to markdown +- **THEN** all text formatting is preserved (bold, italic, links) +- **AND** HTML-specific elements are converted to markdown or Hugo shortcodes +- **AND** content follows markdown best practices + +#### Scenario: Add Hugo front matter +- **GIVEN** converted markdown content +- **WHEN** content files are created +- **THEN** appropriate YAML front matter is added (title, description, date) +- **AND** front matter variables are correctly configured for templates + +### Requirement: Homepage Content Integration +The system SHALL integrate migrated homepage content into content/_index.md, replacing placeholder content. + +#### Scenario: Update homepage with actual content +- **GIVEN** converted homepage markdown content +- **WHEN** content/_index.md is updated +- **THEN** all placeholder text is replaced with actual content +- **AND** all sections from live site are present +- **AND** content hierarchy and flow matches live site structure + +#### Scenario: Image references in content +- **GIVEN** homepage content references images +- **WHEN** image references are added to markdown +- **THEN** images use Hugo static path conventions (e.g., /images/photo.jpg) +- **AND** all image markdown syntax is correct + +### Requirement: Content Structure Parity +The system SHALL ensure the Hugo site content structure matches the live markusgraf.ch site organization. + +#### Scenario: Section organization matches live site +- **GIVEN** live site has distinct sections +- **WHEN** content is organized in Hugo +- **THEN** all sections are represented +- **AND** section order matches live site +- **AND** navigation between sections works correctly + +#### Scenario: Multi-page structure if needed +- **GIVEN** live site has multiple pages +- **WHEN** pages are created in Hugo +- **THEN** each page has corresponding content file +- **AND** internal links between pages work +- **AND** navigation reflects page structure + +### Requirement: Content Verification +The system SHALL verify that migrated content achieves parity with the live site. + +#### Scenario: Content completeness check +- **GIVEN** Hugo site is built with migrated content +- **WHEN** compared with live markusgraf.ch +- **THEN** all text content from live site is present +- **AND** no content is missing or truncated +- **AND** content meaning and context are preserved + +#### Scenario: Visual structure comparison +- **GIVEN** Hugo site is rendered +- **WHEN** viewed alongside live site +- **THEN** content sections appear in same order +- **AND** heading hierarchy matches +- **AND** overall content flow is equivalent + diff --git a/openspec/specs/deployment/spec.md b/openspec/specs/deployment/spec.md new file mode 100644 index 0000000..c92f6b1 --- /dev/null +++ b/openspec/specs/deployment/spec.md @@ -0,0 +1,100 @@ +# deployment Specification + +## Purpose +TBD - created by archiving change simple-deployment. Update Purpose after archive. +## Requirements +### Requirement: Rsync Deployment Script SHALL be provided +The system SHALL provide an automated deployment script that syncs the built Hugo site to the production server via rsync over SSH, properly mirroring content. + +#### Scenario: User deploys site after building +**Given** the Hugo site has been built successfully (public/ directory exists) +**And** the user has set the SSH_USER and SSH_HOST environment variables +**When** the user runs the deployment script +**Then** the script connects to the specified SSH_HOST via rsync over SSH +**And** syncs all files from the public/ directory to the REMOTE_ROOT directory on the server +**And** deletes remote files that don't exist locally (mirror behavior) +**And** displays sync progress and completion status +**And** exits with status code 0 on success + +#### Scenario: Script fails when credentials are missing +**Given** the Hugo site has been built +**And** the SSH_USER or SSH_HOST environment variable is not set +**When** the user runs the deployment script +**Then** the script displays an error message explaining the missing configuration +**And** exits with a non-zero status code +**And** does not attempt to connect to the server + +#### Scenario: Script handles connection failures gracefully +**Given** the SSH_USER and SSH_HOST are set correctly +**And** the network connection to the server is unavailable or SSH authentication fails +**When** the user runs the deployment script +**Then** the script displays a clear error message about the connection failure +**And** exits with a non-zero status code +**And** does not leave the deployment in a partially completed state + +### Requirement: Secure Credential Management SHALL be enforced +The deployment process SHALL handle credentials securely without exposing them in version control or script output. + +#### Scenario: Configuration stored as environment variables +**Given** the user needs to deploy the site +**When** the user reviews the deployment documentation +**Then** the documentation instructs them to set SSH_USER, SSH_HOST, SSH_PORT, and REMOTE_ROOT as environment variables +**And** the deployment script reads configuration only from environment variables +**And** credentials are never hardcoded in scripts or configuration files +**And** SSH key-based authentication is used for secure, password-less access + +#### Scenario: Script does not expose credentials in output +**Given** the deployment script is running +**When** the script displays status messages or logs +**Then** SSH keys or passwords are never displayed in plain text +**And** connection strings show only the host and user information +**And** error messages do not reveal credential values + +### Requirement: Deployment Status Feedback SHALL be provided +The deployment script SHALL provide clear feedback about the deployment process and outcome. + +#### Scenario: User receives progress updates during deployment +**Given** the deployment script is uploading files +**When** the upload is in progress +**Then** the script displays which files or directories are being uploaded +**And** shows overall progress indicators +**And** provides estimated time or completion percentage when possible + +#### Scenario: Successful deployment confirmation +**Given** all files have been uploaded successfully +**When** the deployment completes +**Then** the script displays a success message +**And** confirms the total number of files uploaded +**And** exits with status code 0 + +#### Scenario: Failed deployment with actionable error +**Given** an error occurs during deployment +**When** the deployment fails +**Then** the script displays the specific error encountered +**And** suggests possible remediation steps +**And** exits with a non-zero status code + +### Requirement: Deployment Prerequisites SHALL be verified +The deployment script SHALL verify that prerequisites are met before attempting deployment. + +#### Scenario: Script checks for built site +**Given** the user runs the deployment script +**When** the script starts +**Then** it verifies that the public/ directory exists +**And** contains files to deploy +**And** exits with an error if the directory is missing or empty + +#### Scenario: Script checks for required tools +**Given** the deployment script starts +**When** it performs prerequisite checks +**Then** it verifies that rsync is installed and available +**And** displays an installation message if rsync is missing +**And** exits with an error if required tools are unavailable + +#### Scenario: Script supports configurable ports and remote directories +**Given** the user needs to deploy to a non-standard SSH port or directory +**When** the user sets SSH_PORT and REMOTE_ROOT environment variables +**Then** the script uses the specified port instead of the default (22) +**And** the script uploads to the specified remote directory instead of the default (/httpsdocs) +**And** if these variables are not set, the script uses sensible defaults + diff --git a/openspec/specs/hugo-site/spec.md b/openspec/specs/hugo-site/spec.md new file mode 100644 index 0000000..dea0aca --- /dev/null +++ b/openspec/specs/hugo-site/spec.md @@ -0,0 +1,133 @@ +# hugo-site Specification + +## Purpose +TBD - created by archiving change add-minimal-hugo-site. Update Purpose after archive. +## 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 + diff --git a/openspec/specs/image-assets/spec.md b/openspec/specs/image-assets/spec.md new file mode 100644 index 0000000..04222c6 --- /dev/null +++ b/openspec/specs/image-assets/spec.md @@ -0,0 +1,90 @@ +# image-assets Specification + +## Purpose +TBD - created by archiving change migrate-site-content. Update Purpose after archive. +## Requirements +### Requirement: Image Asset Discovery +The system SHALL identify and catalog all images from the live markusgraf.ch website for migration. + +#### Scenario: Identify all images on live site +- **GIVEN** the live markusgraf.ch website HTML source +- **WHEN** images are catalogued from the HTML +- **THEN** all image URLs are documented +- **AND** image purposes (profile, project, icon, etc.) are identified +- **AND** image file formats and sizes are noted + +#### Scenario: Create asset inventory +- **GIVEN** identified images from live site +- **WHEN** asset inventory is created +- **THEN** a complete list of images with URLs exists +- **AND** each image is categorized by type/purpose +- **AND** inventory documents source URLs for downloading + +### Requirement: Image Download and Organization +The system SHALL download images from the live site and organize them in Hugo's static directory following logical grouping principles. + +#### Scenario: Download images from live site +- **GIVEN** list of image URLs from inventory +- **WHEN** images are downloaded +- **THEN** all images are successfully retrieved +- **AND** image files are verified for integrity +- **AND** no corrupted or failed downloads exist + +#### Scenario: Organize images in static directory +- **GIVEN** downloaded images +- **WHEN** images are placed in Hugo project +- **THEN** images are saved to static/images/ or appropriate subdirectories +- **AND** directory structure reflects logical grouping (e.g., static/images/projects/, static/images/profile/) +- **AND** filenames are consistent and descriptive + +### Requirement: Image Reference Integration +The system SHALL update all image references in content files to use Hugo's static path conventions correctly. + +#### Scenario: Update image paths in content +- **GIVEN** images are in Hugo static directory +- **WHEN** content files reference images +- **THEN** image paths use Hugo static conventions (e.g., /images/photo.jpg) +- **AND** all image references use correct relative or absolute paths +- **AND** markdown image syntax is properly formatted + +#### Scenario: Verify image links resolve +- **GIVEN** Hugo site is built +- **WHEN** pages with images are rendered +- **THEN** all image references resolve correctly +- **AND** no broken image links exist +- **AND** no 404 errors occur for image resources + +### Requirement: Image Display Verification +The system SHALL ensure all migrated images display correctly in the built Hugo site. + +#### Scenario: Images render correctly +- **GIVEN** Hugo site is built and served +- **WHEN** pages with images are viewed +- **THEN** all images display visually +- **AND** image aspect ratios are appropriate +- **AND** images load from correct static paths +- **AND** no missing or placeholder images appear + +#### Scenario: Image dimensions and quality +- **GIVEN** images are displayed on site +- **WHEN** comparing to live site +- **THEN** image sizes are comparable to originals +- **AND** image quality is maintained +- **AND** no distortion or stretching occurs + +### Requirement: Image Accessibility +The system SHALL ensure all images have appropriate accessibility attributes for screen readers and assistive technologies. + +#### Scenario: Alt text for all images +- **GIVEN** images in content files +- **WHEN** markdown image syntax is used +- **THEN** all images include descriptive alt text +- **AND** alt text meaningfully describes image content +- **AND** decorative images use empty alt text where appropriate + +#### Scenario: Semantic image usage +- **GIVEN** images serve specific purposes +- **WHEN** images are integrated into content +- **THEN** images are used semantically (figures, illustrations, etc.) +- **AND** image context is clear from surrounding content + diff --git a/openspec/specs/internationalization/spec.md b/openspec/specs/internationalization/spec.md new file mode 100644 index 0000000..a692142 --- /dev/null +++ b/openspec/specs/internationalization/spec.md @@ -0,0 +1,120 @@ +# internationalization Specification + +## Purpose +TBD - created by archiving change add-multilingual-support. Update Purpose after archive. +## Requirements +### Requirement: Multilingual Content Support +The site SHALL support multiple languages with German (de) as the default language and English (en) as a secondary language. + +#### Scenario: German content is accessible at /de/ path +- **WHEN** a visitor navigates to `/de/` or any `/de/*` path +- **THEN** the page displays in German language +- **AND** all navigation, content, and UI elements are in German + +#### Scenario: English content is accessible at /en/ path +- **WHEN** a visitor navigates to `/en/` or any `/en/*` path +- **THEN** the page displays in English language +- **AND** all navigation, content, and UI elements are in English + +#### Scenario: All pages have translations +- **WHEN** content exists in one language +- **THEN** a corresponding translation SHALL exist in the other language +- **AND** the content structure mirrors across languages (e.g., `/de/cv` ↔ `/en/cv`) + +### Requirement: Language Switcher +The site navigation SHALL include a language switcher that allows users to change languages while maintaining page context. + +#### Scenario: Language switcher is visible in navigation +- **WHEN** a visitor views any page +- **THEN** the navigation displays language options (DE, EN) +- **AND** the current active language is visually indicated +- **AND** the inactive language is shown as a clickable link + +#### Scenario: Language switching maintains page context +- **WHEN** a visitor is on `/de/cv` and clicks the English language link +- **THEN** the page navigates to `/en/cv` (the English version of the same page) +- **AND** the page content changes to English + +#### Scenario: Language switching from home page +- **WHEN** a visitor is on `/de/` and clicks the English language link +- **THEN** the page navigates to `/en/` +- **AND** the home page content changes to English + +#### Scenario: Language switcher handles missing translations +- **WHEN** a visitor is on a page without a translation +- **THEN** the language link points to the home page of the target language +- **AND** the user is not left on a broken or non-existent page + +### Requirement: Language Persistence +The site SHALL maintain the user's language preference through URL-based routing without requiring cookies or JavaScript. + +#### Scenario: Language preference persists across navigation +- **WHEN** a visitor navigates to `/de/cv` and then clicks a navigation link +- **THEN** all subsequent pages remain in German (e.g., clicking "Home" goes to `/de/`) +- **AND** the language preference is maintained through the URL structure + +#### Scenario: Direct URL access respects language +- **WHEN** a visitor directly accesses `/en/cv` via URL or bookmark +- **THEN** the page displays in English +- **AND** all navigation links point to English pages + +### Requirement: Browser Language Detection +The site configuration SHALL support automatic language selection based on browser language preferences for first-time visitors. + +#### Scenario: Server redirect based on Accept-Language header +- **WHEN** a visitor accesses the root URL `/` for the first time +- **THEN** the server MAY redirect to `/de/` or `/en/` based on the browser's `Accept-Language` header +- **AND** German is used as the fallback if no language preference is detected + +#### Scenario: URL-based access bypasses language detection +- **WHEN** a visitor directly accesses `/de/` or `/en/` +- **THEN** the specified language is used regardless of browser settings +- **AND** no redirect occurs + +### Requirement: Content Translation +All site content SHALL be translated between German and English languages. + +#### Scenario: Home page content is translated +- **WHEN** viewing the home page in German (`/de/`) +- **THEN** all text including introduction, project descriptions, and UI labels are in German +- **WHEN** viewing the home page in English (`/en/`) +- **THEN** all text including introduction, project descriptions, and UI labels are in English + +#### Scenario: CV page content is translated +- **WHEN** viewing the CV page in German (`/de/cv`) +- **THEN** all text including headings, instructions, and contact information are in German +- **WHEN** viewing the CV page in English (`/en/cv`) +- **THEN** all text including headings, instructions, and contact information are in English + +#### Scenario: Navigation menu is translated +- **WHEN** viewing any page in German +- **THEN** navigation menu items are in German (e.g., "Lebenslauf" for CV) +- **WHEN** viewing any page in English +- **THEN** navigation menu items are in English (e.g., "Curriculum Vitae" for CV) + +#### Scenario: Footer content is translated +- **WHEN** viewing any page in German +- **THEN** footer content including address and contact information labels are in German +- **WHEN** viewing any page in English +- **THEN** footer content including address and contact information labels are in English + +### Requirement: SEO and Accessibility +The site SHALL implement proper multilingual SEO practices and accessibility features. + +#### Scenario: HTML lang attribute is set correctly +- **WHEN** viewing a German page +- **THEN** the HTML element has `lang="de"` attribute +- **WHEN** viewing an English page +- **THEN** the HTML element has `lang="en"` attribute + +#### Scenario: Alternative language links are provided +- **WHEN** viewing any page +- **THEN** the HTML head includes `` and `` tags +- **AND** these tags point to the corresponding page in each language + +#### Scenario: Page titles reflect language +- **WHEN** viewing a page in German +- **THEN** the page title is in German +- **WHEN** viewing a page in English +- **THEN** the page title is in English + diff --git a/openspec/specs/styling/spec.md b/openspec/specs/styling/spec.md new file mode 100644 index 0000000..3f0adc5 --- /dev/null +++ b/openspec/specs/styling/spec.md @@ -0,0 +1,69 @@ +# styling Specification + +## Purpose +TBD - created by archiving change add-custom-bootstrap-styling. Update Purpose after archive. +## Requirements +### Requirement: SCSS Processing Pipeline +The system SHALL process SCSS files using Hugo Pipes to generate custom CSS that supplements Bootstrap's CDN-provided styles. + +#### Scenario: SCSS compilation on build +- **WHEN** Hugo builds the site +- **THEN** SCSS files in `assets/scss/` are compiled to CSS +- **AND** the compiled CSS is fingerprinted for cache busting +- **AND** the resulting CSS file is included in the HTML output + +#### Scenario: Development mode with live reload +- **WHEN** running Hugo in development mode (hugo server) +- **THEN** SCSS changes trigger automatic recompilation +- **AND** the browser live-reloads with updated styles + +### Requirement: Bootstrap Variable Customization +The system SHALL allow customization of Bootstrap design tokens through SCSS variables without modifying the CDN-provided Bootstrap CSS. + +#### Scenario: Override heading font sizes +- **WHEN** custom heading sizes are defined in SCSS variables +- **THEN** the compiled CSS applies these sizes to heading elements +- **AND** the Bootstrap CDN CSS is loaded first (base styles) +- **AND** custom CSS is loaded after (overrides) + +#### Scenario: Override link colors +- **WHEN** custom link colors are defined in SCSS variables +- **THEN** links across the site use the custom colors +- **AND** link hover states use appropriate custom colors + +#### Scenario: Override spacing scale +- **WHEN** custom spacing values are defined +- **THEN** elements using those spacing classes reflect the custom values + +### Requirement: Custom Style Organization +The system SHALL organize custom styles in a maintainable SCSS file structure following Hugo and SASS best practices. + +#### Scenario: Main SCSS entry point +- **WHEN** Hugo processes SCSS +- **THEN** a single main SCSS file serves as the entry point +- **AND** this file imports Bootstrap variable overrides +- **AND** this file imports custom component styles +- **AND** this file imports custom utility styles + +#### Scenario: Modular SCSS files +- **WHEN** developers add new custom styles +- **THEN** styles can be organized into separate partial files +- **AND** partial files are imported into the main SCSS file +- **AND** file naming follows SCSS conventions (e.g., `_variables.scss`, `_custom.scss`) + +### Requirement: CSS Output Integration +The system SHALL integrate compiled custom CSS into the base layout template alongside Bootstrap CDN CSS. + +#### Scenario: CSS load order +- **WHEN** a page is rendered +- **THEN** Bootstrap CDN CSS loads first +- **AND** custom compiled CSS loads second +- **AND** CSS files include integrity hashes where applicable +- **AND** the custom CSS file path includes a fingerprint for cache busting + +#### Scenario: Production build optimization +- **WHEN** building for production +- **THEN** SCSS is compiled with minification +- **AND** the output CSS is optimized for file size +- **AND** source maps are not included in production builds +