diff --git a/openspec/changes/add-blog-section/proposal.md b/openspec/changes/add-blog-section/proposal.md new file mode 100644 index 0000000..2b61fe5 --- /dev/null +++ b/openspec/changes/add-blog-section/proposal.md @@ -0,0 +1,57 @@ +# Add Blog Section + +## Problem +The website currently lacks a blog section for publishing articles and sharing knowledge. There is existing content (article "KI Generierte Website - ein Praxisbeispiel" in Notion) ready to be published, but no structure to support blog posts. + +## Proposed Solution +Add a blog section to the Hugo site that: +- Provides a dedicated blog listing page showing all published articles +- Supports individual blog post pages with proper formatting +- Maintains multilingual support (German/English) consistent with the rest of the site +- Includes navigation links to access the blog +- Uses Hugo's content organization and templating for maintainability + +The first article to be published will be "KI Generierte Website - ein Praxisbeispiel" (available in Notion), which discusses the experience of building this website using AI-assisted development with OpenSpec. + +## Scope +**In Scope:** +- Blog list page template (showing all blog posts) +- Blog post single page template +- Blog content structure in Hugo +- Navigation menu integration for blog +- First blog post: "KI Generierte Website - ein Praxisbeispiel" (German version) +- Multilingual support for blog posts + +**Out of Scope:** +- Taxonomies/categories/tags (site currently has these disabled) +- Comments system +- RSS feed (can be added later if needed) +- Search functionality +- Blog post pagination (can be added when needed) + +## Success Criteria +- Blog section is accessible from main navigation +- Blog listing page shows published articles with title, date, and excerpt +- Individual blog posts display with proper formatting and styling +- First article "KI Generierte Website - ein Praxisbeispiel" is published in German +- Blog supports both German and English content structure (even if English translation comes later) +- Blog pages follow site's responsive design and accessibility standards +- Lighthouse score remains >90 + +## Dependencies +- Existing Hugo site infrastructure (already in place) +- Internationalization system (already implemented) +- Bootstrap styling (already in place) + +## Risks & Mitigations +**Risk:** Blog content structure might conflict with existing content organization +**Mitigation:** Use Hugo sections (`content/blog/`) which is the standard Hugo pattern + +**Risk:** Blog post styling might need specific customization beyond current templates +**Mitigation:** Start with minimal styling, iterate based on actual needs + +## Timeline Estimate +Small change, estimated 2-3 hours of implementation work: +- Blog templates: 1 hour +- Content structure and first article: 1 hour +- Testing and refinement: 30-60 minutes diff --git a/openspec/changes/add-blog-section/specs/blog-content/spec.md b/openspec/changes/add-blog-section/specs/blog-content/spec.md new file mode 100644 index 0000000..e51353a --- /dev/null +++ b/openspec/changes/add-blog-section/specs/blog-content/spec.md @@ -0,0 +1,81 @@ +# Blog Content Structure + +## ADDED Requirements + +### Requirement: Blog Section Organization +Blog posts SHALL be organized in a dedicated `content/blog/` directory following Hugo's content organization conventions. + +#### Scenario: Blog section exists in content directory +**Given** the Hugo site structure +**When** examining the content directory +**Then** a `content/blog/` directory SHALL exist +**And** section index files `_index.de.md` and `_index.en.md` SHALL exist in `content/blog/` +**And** these index files SHALL contain appropriate front matter (title, description) + +#### Scenario: Blog posts use page bundles +**Given** a blog post to be published +**When** adding the post to the site +**Then** the post SHALL be organized as a page bundle (directory with `index.de.md` or `index.en.md`) +**And** the bundle directory name SHALL be URL-friendly (lowercase, hyphens, no special characters) +**And** any post-specific assets (images, files) CAN be stored within the bundle directory + +--- + +### Requirement: Blog Post Front Matter +Each blog post SHALL include properly structured front matter with essential metadata. + +#### Scenario: Blog post front matter is complete +**Given** a blog post markdown file +**When** the post is processed by Hugo +**Then** the front matter SHALL include a `title` field +**And** the front matter SHALL include a `date` field in ISO 8601 format (YYYY-MM-DD) +**And** the front matter MAY include a `description` or `summary` field for excerpts +**And** the front matter MAY include a `draft` field to control publication status + +#### Scenario: First blog post is ready +**Given** the Notion article "KI Generierte Website - ein Praxisbeispiel" +**When** converting it to Hugo format +**Then** a blog post SHALL exist at `content/blog/ki-generierte-website-praxisbeispiel/index.de.md` +**And** the post SHALL contain the full article content from Notion +**And** the front matter SHALL include title "KI Generierte Website - ein Praxisbeispiel" +**And** the front matter SHALL include an appropriate publication date + +--- + +### Requirement: Multilingual Blog Support +Blog content SHALL support both German and English following the site's internationalization pattern. + +#### Scenario: Blog section metadata is multilingual +**Given** the blog section +**When** accessing the blog in different languages +**Then** `content/blog/_index.de.md` SHALL exist with German metadata +**And** `content/blog/_index.en.md` SHALL exist with English metadata +**And** both SHALL have appropriate translated titles and descriptions + +#### Scenario: Blog posts can exist in multiple languages +**Given** a blog post +**When** translations are available +**Then** the post MAY have both `index.de.md` and `index.en.md` in the same bundle +**And** Hugo SHALL serve the appropriate language version based on the URL path +**And** language switching SHALL work between translated blog posts + +--- + +### Requirement: Content Formatting +Blog post content SHALL be written in Markdown with proper formatting support. + +#### Scenario: Markdown content renders correctly +**Given** a blog post with Markdown content +**When** Hugo processes the post +**Then** headings (H1-H6) SHALL be rendered correctly +**And** paragraphs, lists, and emphasis SHALL be formatted properly +**And** code blocks with syntax highlighting SHALL be supported +**And** links and images SHALL be rendered correctly +**And** HTML content SHALL be allowed (Hugo's unsafe renderer is enabled in config) + +#### Scenario: Special characters and formatting are preserved +**Given** blog post content with German special characters (ä, ö, ü, ß) +**When** the post is rendered +**Then** all special characters SHALL display correctly +**And** quotation marks and em dashes SHALL be preserved +**And** UTF-8 encoding SHALL be maintained throughout diff --git a/openspec/changes/add-blog-section/specs/blog-templates/spec.md b/openspec/changes/add-blog-section/specs/blog-templates/spec.md new file mode 100644 index 0000000..7904d31 --- /dev/null +++ b/openspec/changes/add-blog-section/specs/blog-templates/spec.md @@ -0,0 +1,122 @@ +# Blog Templates + +## ADDED Requirements + +### Requirement: Blog List Template +A blog list template SHALL display all published blog posts in a organized, user-friendly format. + +#### Scenario: Blog list page renders with posts +**Given** published blog posts exist in `content/blog/` +**When** a user navigates to `/de/blog/` or `/en/blog/` +**Then** a blog list page SHALL be rendered using `layouts/blog/list.html` +**And** the page SHALL display all non-draft blog posts +**And** posts SHALL be sorted by date (most recent first) + +#### Scenario: Blog list shows post metadata +**Given** the blog list page +**When** displaying each blog post entry +**Then** each entry SHALL show the post title as a link to the full post +**And** each entry SHALL show the publication date +**And** each entry MAY show a summary or excerpt of the post +**And** the title link SHALL navigate to the full blog post page + +#### Scenario: Blog list is responsive +**Given** the blog list page +**When** viewed on different screen sizes +**Then** the layout SHALL be responsive using Bootstrap grid +**And** the page SHALL be readable on mobile devices (≥320px width) +**And** the page SHALL adapt to tablet and desktop viewports +**And** spacing and typography SHALL remain consistent with site design + +--- + +### Requirement: Blog Post Single Template +Individual blog posts SHALL be displayed with a dedicated single post template providing optimal reading experience. + +#### Scenario: Blog post page renders content +**Given** a blog post at `content/blog/ki-generierte-website-praxisbeispiel/index.de.md` +**When** a user navigates to `/de/blog/ki-generierte-website-praxisbeispiel/` +**Then** the post SHALL be rendered using `layouts/blog/single.html` +**And** the page SHALL display the post title as the main heading (H1) +**And** the page SHALL display the publication date +**And** the page SHALL display the full post content with proper formatting + +#### Scenario: Blog post content is readable +**Given** a rendered blog post +**When** viewing the post content +**Then** headings SHALL use appropriate hierarchy (H2, H3, etc. for sections) +**And** paragraphs SHALL have readable line height and spacing +**And** code blocks SHALL be distinguishable with appropriate styling +**And** links SHALL be clearly identifiable and accessible +**And** images SHALL be responsive and properly sized + +#### Scenario: Blog post has navigation +**Given** a blog post page +**When** a user finishes reading +**Then** the page SHALL include a link back to the blog list +**And** the navigation link SHALL be clearly visible +**And** the site's main navigation SHALL remain accessible + +--- + +### Requirement: Blog Navigation Integration +The blog section SHALL be accessible through the site's main navigation. + +#### Scenario: Blog link in main navigation +**Given** the site configuration +**When** rendering the main navigation menu +**Then** a "Blog" link SHALL appear in the navigation for German pages +**And** a "Blog" link SHALL appear in the navigation for English pages +**And** the link SHALL point to `/de/blog/` for German +**And** the link SHALL point to `/en/blog/` for English + +#### Scenario: Active state for blog pages +**Given** a user is on a blog page (list or single post) +**When** viewing the navigation menu +**Then** the "Blog" link SHALL have an active state indicator +**And** the active state SHALL use the same styling as other active navigation items +**And** the active state SHALL be maintained on both blog list and single post pages + +--- + +### Requirement: Blog Template Semantic HTML +Blog templates SHALL use semantic HTML5 elements for accessibility and SEO. + +#### Scenario: Blog list uses semantic structure +**Given** the blog list template +**When** rendering the page +**Then** the main content SHALL be wrapped in a `
` element +**And** individual blog post entries SHALL use `
` elements +**And** post metadata SHALL use appropriate semantic tags (e.g., `