docs: create OpenSpec proposal for blog section
Add proposal, tasks, and specifications for implementing a blog section with multilingual support. First article will be "KI Generierte Website - ein Praxisbeispiel" from Notion. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
@@ -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
|
||||
@@ -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
|
||||
@@ -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 `<main>` element
|
||||
**And** individual blog post entries SHALL use `<article>` elements
|
||||
**And** post metadata SHALL use appropriate semantic tags (e.g., `<time>` for dates)
|
||||
**And** heading hierarchy SHALL be logical and sequential
|
||||
|
||||
#### Scenario: Blog post uses article structure
|
||||
**Given** a blog post template
|
||||
**When** rendering the page
|
||||
**Then** the post SHALL be wrapped in an `<article>` element
|
||||
**And** the post SHALL have a `<header>` with title and metadata
|
||||
**And** the post content SHALL be in a `<div>` or `<section>` with clear semantic structure
|
||||
**And** all headings SHALL follow proper hierarchy
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Blog Styling Consistency
|
||||
Blog templates SHALL maintain visual consistency with the rest of the site.
|
||||
|
||||
#### Scenario: Blog pages use site styling
|
||||
**Given** any blog page (list or single)
|
||||
**When** the page is rendered
|
||||
**Then** the page SHALL use the site's base layout (`baseof.html`)
|
||||
**And** the page SHALL include the site's header and footer partials
|
||||
**And** the page SHALL use Bootstrap classes for styling
|
||||
**And** typography SHALL be consistent with other site pages
|
||||
**And** color scheme SHALL match the site's design
|
||||
|
||||
#### Scenario: Blog pages are accessible
|
||||
**Given** any blog page
|
||||
**When** evaluated for accessibility
|
||||
**Then** the page SHALL meet WCAG 2.1 AA standards
|
||||
**And** all interactive elements SHALL be keyboard accessible
|
||||
**And** color contrast ratios SHALL meet minimum requirements
|
||||
**And** images SHALL have appropriate alt text (if any)
|
||||
**And** the page SHALL have appropriate semantic structure for screen readers
|
||||
@@ -0,0 +1,88 @@
|
||||
# Tasks for add-blog-section
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
### 1. Create blog content structure
|
||||
- [ ] Create `content/blog/` directory for German blog posts
|
||||
- [ ] Create `content/blog/_index.de.md` for German blog section metadata
|
||||
- [ ] Create `content/blog/_index.en.md` for English blog section metadata
|
||||
- [ ] Convert Notion article "KI Generierte Website - ein Praxisbeispiel" to Markdown format
|
||||
- [ ] Create `content/blog/ki-generierte-website-praxisbeispiel/index.de.md` with article content
|
||||
- [ ] Add proper front matter (title, date, description) to blog post
|
||||
|
||||
**Validation:** Files exist in correct locations, front matter is properly formatted
|
||||
|
||||
**Dependencies:** None
|
||||
|
||||
**Parallelizable:** Can be done independently
|
||||
|
||||
---
|
||||
|
||||
### 2. Create blog list template
|
||||
- [ ] Create `layouts/blog/list.html` template for blog listing page
|
||||
- [ ] Display blog post titles, dates, and excerpts/summaries
|
||||
- [ ] Add proper semantic HTML structure
|
||||
- [ ] Apply Bootstrap styling for consistent look
|
||||
- [ ] Ensure responsive design (mobile-first)
|
||||
- [ ] Add pagination structure (even if not needed yet, for future)
|
||||
|
||||
**Validation:** Running `hugo server` shows blog list page at `/de/blog/` with article listed
|
||||
|
||||
**Dependencies:** Task 1 (content structure)
|
||||
|
||||
**Parallelizable:** No (requires content structure)
|
||||
|
||||
---
|
||||
|
||||
### 3. Create blog post single template
|
||||
- [ ] Create `layouts/blog/single.html` template for individual blog posts
|
||||
- [ ] Display post title, date, and full content
|
||||
- [ ] Add article metadata (author, date, reading time if desired)
|
||||
- [ ] Style content appropriately (headings, paragraphs, code blocks, etc.)
|
||||
- [ ] Ensure responsive design
|
||||
- [ ] Add navigation back to blog list
|
||||
|
||||
**Validation:** Blog post accessible at `/de/blog/ki-generierte-website-praxisbeispiel/` with proper formatting
|
||||
|
||||
**Dependencies:** Task 1 (content structure)
|
||||
|
||||
**Parallelizable:** Can be done in parallel with Task 2
|
||||
|
||||
---
|
||||
|
||||
### 4. Add blog navigation
|
||||
- [ ] Add "Blog" link to navigation menu (German: "Blog", English: "Blog")
|
||||
- [ ] Update `config.toml` with blog menu items for both languages
|
||||
- [ ] Verify navigation links work correctly
|
||||
- [ ] Ensure active state highlighting works on blog pages
|
||||
|
||||
**Validation:** Blog link appears in navigation, clicking it navigates to blog list page
|
||||
|
||||
**Dependencies:** Tasks 1, 2 (blog structure and list page)
|
||||
|
||||
**Parallelizable:** No (requires blog pages to exist)
|
||||
|
||||
---
|
||||
|
||||
### 5. Verify and test
|
||||
- [ ] Build site with `hugo` command (no errors)
|
||||
- [ ] Test blog list page rendering
|
||||
- [ ] Test blog post page rendering
|
||||
- [ ] Verify multilingual structure (German blog accessible, English structure ready)
|
||||
- [ ] Test navigation and links
|
||||
- [ ] Verify responsive design on mobile/tablet/desktop viewports
|
||||
- [ ] Run Lighthouse audit (score should remain >90)
|
||||
- [ ] Check accessibility (WCAG 2.1 AA compliance)
|
||||
|
||||
**Validation:** All tests pass, site builds successfully, Lighthouse score >90
|
||||
|
||||
**Dependencies:** All previous tasks
|
||||
|
||||
**Parallelizable:** No (final verification step)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Order
|
||||
Tasks should be completed in sequence: 1 → 2, 3 (parallel) → 4 → 5
|
||||
|
||||
Total estimated time: 2-3 hours
|
||||
Reference in New Issue
Block a user