Merge pull request #293 from OpenElements/origin/actions-auto

Enhance documentation for blog post creation and content structure

Author: danielmarv

README.md

@@ -91,6 +91,7 @@ Netlify builds run `pnpm install` and `pnpm run build` (see `netlify.toml`).
 
 ## Documentation
 
-- **[Docs Hub](docs/README.md)** - First stop for contributors (repo overview, content guide, first contribution checklist, automation)
-- **[Adding New Pages Guide](ADDING_PAGES.md)** - Complete guide on how to add new pages with EN/DE versions, including image handling and layout options
+- **[Docs Hub](docs/README.md)** - First stop for contributors (repository architecture, content workflows, quality checks)
+- **[Adding Blog Posts](docs/04-adding-blog-post.md)** - Post-specific workflow for `content/posts/`, front matter, and `/posts/...` linking conventions
+- **[Adding New Pages Guide](ADDING_PAGES.md)** - Legacy page-creation guide with EN/DE examples and image/layout notes
 

docs/02-content-folder.md

@@ -72,6 +72,8 @@ content/posts/
 
 **Usage**: Blog articles, release notes, announcements
 
+For a complete, post-specific workflow (including front matter and link conventions), see [04 - Adding Blog Posts](./04-adding-blog-post.md).
+
 ### Pattern 3: Version Updates CHANGELOG
 
 Release notes and version updates use semantic versioning for organization.
@@ -117,21 +119,26 @@ Every markdown file begins with YAML front matter enclosed by `---` delimiters.
 
 ### Common Front Matter Fields
 
-| Field | Type | Purpose | Example |
-|-------|------|---------|---------|
-| `title` | String | Page title displayed in browser tab and page header | `"Getting Started with Open Elements"` |
-| `description` | String | SEO description for search results and social sharing | `"Learn how to set up and use Open Elements in your projects"` |
-| `layout` | String | Template/layout used for rendering (defines page structure) | `"article"`, `"page"`, `"post"` |
-| `url` | String | URL path for the page (must match routing structure) | `"/getting-started"` or `"/de/getting-started"` |
-| `keywords` | Array | SEO keywords for search optimization | `["open-elements", "tutorial", "setup"]` |
-| `aliases` | Array | Alternative URLs that redirect to this page (for migrations) | `["/old-path", "/another-path"]` |
-| `date` | String | Publication or creation date in YYYY-MM-DD format | `"2024-02-25"` |
-| `author` | String | Content author name (for blog posts) | `"John Smith"` |
-| `newsletterPopup` | Boolean | Whether to show newsletter signup popup | `true` or `false` |
-
-### Minimum Required Front Matter
-
-Every content file must include these fields at minimum:
+Different content types use different metadata shapes.
+
+| Field | Type | Primary Use | Example |
+|-------|------|-------------|---------|
+| `title` | String | Pages and posts | `"Getting Started with Open Elements"` |
+| `description` | String | Standard pages (SEO) | `"Learn how to set up and use Open Elements"` |
+| `layout` | String | Standard pages | `"article"`, `"single"`, `"contact"` |
+| `url` | String | Standard pages only | `"/getting-started"` or `"/de/getting-started"` |
+| `keywords` | Array | Standard pages (optional SEO) | `["open-elements", "tutorial", "setup"]` |
+| `aliases` | Array | Standard pages redirects | `["/old-path", "/another-path"]` |
+| `newsletterPopup` | Boolean | Standard pages where needed | `true` or `false` |
+| `date` | String | Blog posts (publication date) | `"2024-02-25"` |
+| `author` | String | Blog posts (team id) | `"hendrik"` |
+| `excerpt` | String | Blog posts (listing/meta summary) | `"Short preview for cards"` |
+| `categories` | Array | Blog posts (tags) | `["open-source", "maven"]` |
+| `preview_image` | String | Blog posts card/OG image | `"/posts/preview-images/open-source-green.svg"` |
+| `showInBlog` | Boolean | Blog posts visibility filter | `true` or `false` |
+| `outdated` | Boolean | Blog posts visibility filter | `false` |
+
+### Minimum Required Front Matter for Standard Pages
 
 ```yaml
 ---
@@ -142,39 +149,54 @@ url: "/page-slug"
 ---
 ```
 
+### Minimum Required Front Matter for Blog Posts
+
+```yaml
+---
+outdated: false
+showInBlog: true
+title: "How to Build Scalable Java Applications"
+date: 2024-02-25
+author: hendrik
+excerpt: "Discover best practices and patterns for scalable Java applications."
+categories: [java, scalability, performance, architecture]
+preview_image: "/posts/preview-images/software-development-green.svg"
+---
+```
+
 ### Front Matter Best Practices
 
 - **Title**: Keep it concise (50-60 characters), clear, and descriptive
-- **Description**: Write for search engines (160 characters max), include key terms
-- **URL**: Must match the actual route and locale prefix (`/de/...` for German)
-- **Keywords**: Use 3-7 relevant keywords, separated by commas in array format
-- **Dates**: Use ISO 8601 format (YYYY-MM-DD) for consistency
+- **Description**: Use on standard pages for SEO metadata (150-160 characters)
+- **URL**: Use on standard pages only; must match route and locale prefix for German (`/de/...`)
+- **Dates**: Use ISO 8601 format (`YYYY-MM-DD`) for posts
+- **Author IDs**: Use team ids that exist in `src/data/en/team.json` and `src/data/de/team.json`
+- **Post Images**: Use web paths (for example `/posts/...`), never filesystem paths
 
 ### Example Front Matter
 
-**English Blog Post:**
+**Standard Page (EN):**
 ```yaml
 ---
-title: "How to Build Scalable Java Applications"
-description: "Discover best practices and patterns for building scalable Java applications in production environments"
-layout: "post"
-url: "/blog/scalable-java"
-keywords: ["java", "scalability", "performance", "architecture"]
-author: "Jane Developer"
-date: "2024-02-25"
+title: "Frequently Asked Questions"
+description: "Find answers to common questions about Open Elements."
+layout: "article"
+url: "/faq"
+keywords: ["faq", "help", "support"]
 ---
 ```
 
-**German Translation of Same Post:**
+**Blog Post (EN):**
 ```yaml
 ---
-title: "Skalierbare Java-Anwendungen entwickeln"
-description: "Entdecken Sie Best Practices und Muster für die Entwicklung skalierbarer Java-Anwendungen in Produktionsumgebungen"
-layout: "post"
-url: "/de/blog/skalierbare-java"
-keywords: ["java", "skalierbarkeit", "performance", "architektur"]
-author: "Jane Developer"
-date: "2024-02-25"
+outdated: false
+showInBlog: true
+title: "How to Build Scalable Java Applications"
+date: 2024-02-25
+author: hendrik
+excerpt: "Discover best practices and patterns for scalable Java applications."
+categories: [java, scalability, performance, architecture]
+preview_image: "/posts/preview-images/software-development-green.svg"
 ---
 ```
 
@@ -208,14 +230,15 @@ content/posts/
 ### Parity Requirements
 
 **User-Facing Pages**
-- Pages visible to end users must maintain structural parityBetween English and German
+- Pages visible to end users must maintain structural parity between English and German
 - Both language versions must exist before merging the PR
 - Update simultaneous in the same PR rather than separate PRs
 
 **Content Structure Parity**
-- Headings, section organization should match between EN and DE versions
-- Same media (images, etc.) referenced in both versions
-- Front matter structure identical except for `url` (includes `/de/` prefix) and translated `title`/`description`
+- Headings and section organization should match between EN and DE versions
+- Same media (images, etc.) should generally be referenced in both versions
+- For standard pages: front matter structure is identical except localized `title`/`description` and `url` with `/de/` prefix
+- For blog posts: front matter fields should stay aligned across locales while keeping translated text in `title` and `excerpt`
 
 **When Single-Language Content is Acceptable**
 - Technical documentation or release notes specifically for developers
@@ -229,7 +252,7 @@ When translating content from English to German:
 1. **Maintain Meaning**: Preserve semantic meaning even if literal translation doesn't fit
 2. **Preserve Formatting**: Keep heading levels, lists, code blocks identical
 3. **Terminology**: Use consistent terminology across all German content
-4. **Links**: Update internal links to use German routing (`/de/...`)
+4. **Links**: Update internal links to use German routing (`/de/...` for standard pages, `/de/posts/...` for blog posts)
 5. **Date Format**: Adapt date formatting if appropriate for German audience
 
 ## URL and SEO Configuration
@@ -238,11 +261,11 @@ When translating content from English to German:
 
 **English URLs:**
 - Start with `/` immediately (no locale prefix)
-- Examples: `/about`, `/blog/post-title`, `/contact`
+- Examples: `/about`, `/posts/2024-02-25-post-title`, `/contact`
 
 **German URLs:**
 - Include `/de/` at the beginning
-- Examples: `/de/about`, `/de/blog/post-title`, `/de/kontakt`
+- Examples: `/de/about`, `/de/posts/2024-02-25-post-title`, `/de/kontakt`
 
 ### URL Naming Rules
 
@@ -251,18 +274,22 @@ When translating content from English to German:
    - If a URL change is necessary, implement 301 redirects or use `aliases` in front matter
 
 2. **Consistency**: Use lowercase letters and hyphens (kebab-case)
-   - ✅ `/blog/new-release`
-   - ❌ `/blog/New_Release`
-   - ❌ `/blog/NewRelease`
+   - ✅ `/posts/2024-02-25-new-release`
+   - ❌ `/posts/2024-02-25-New_Release`
+   - ❌ `/posts/2024-02-25-NewRelease`
 
 3. **Descriptiveness**: URLs should indicate content topic
-   - ✅ `/blog/performance-optimization-tips`
-   - ❌ `/blog/post-123`
-   - ❌ `/blog/article-1`
+   - ✅ `/posts/2024-02-25-performance-optimization-tips`
+   - ❌ `/posts/2024-02-25-post-123`
+   - ❌ `/posts/2024-02-25-article-1`
+
+4. **Front Matter URL Field (Standard Pages Only)**: Must exactly match the route structure
+   - English page: `"url": "/about"`
+   - German page: `"url": "/de/about"`
 
-4. **Front Matter URL Field**: Must exactly match the route structure
-   - English: `"url": "/blog/my-post"`
-   - German: `"url": "/de/blog/my-post"`
+5. **Blog Post URL Source**: URL is derived from filename
+   - English file: `content/posts/2024-02-25-my-post.md` -> `/posts/2024-02-25-my-post`
+   - German file: `content/posts/2024-02-25-my-post.de.md` -> `/de/posts/2024-02-25-my-post`
 
 ### SEO Best Practices
 
@@ -363,7 +390,7 @@ When referencing assets in markdown or JSX, use **web paths only** (not filesyst
 | Mistake | ❌ Wrong | ✅ Right | Impact |
 |---------|---------|---------|--------|
 | Asset path with `public/` | `![](/public/img.png)` | `![](/img.png)` | Assets won't load |
-| Wrong URL in front matter | `url: "/about"` (EN) | `url: "/de/about"` (DE) | Broken routing for German version |
+| Wrong localized page URL in front matter | `url: "/about"` in `index.de.md` | `url: "/de/about"` in `index.de.md` | Broken routing for German version |
 | Inconsistent heading hierarchy | Skip from H2 to H4 | H2 → H3 → H4 | SEO and accessibility issues |
 | Inconsistent filename patterns | Mix `.md` and `.en.md` | Use `.md` and `.de.md` consistently | Localization breaks |
 | Removing old aliases | Delete `aliases` field | Keep for backward compatibility | Broken external links and SEO loss |
@@ -389,14 +416,16 @@ Before submitting a pull request with content changes, systematically verify eac
 
 - [ ] **Front Matter**: 
   - YAML is syntactically valid (no indentation errors)
-  - All required fields present: `title`, `description`, `layout`, `url`
-  - `url` field exactly matches the route structure
+  - Standard pages include required fields: `title`, `description`, `layout`, `url`
+  - Blog posts include required fields: `title`, `date`, `author`, `excerpt`, `categories`, `preview_image`
+  - If blog post visibility is intentional, `showInBlog` and `outdated` are set correctly
 
 - [ ] **Localization Parity**:
-  - Both English and German versions exist
+  - Standard pages: both English and German versions exist
+  - Blog posts: German translation is added when user-facing and intended for DE listing
   - Content is structurally similar between language versions
-  - `url` fields differ only in `/de/` prefix
-  - Titles and descriptions are properly translated
+  - Standard page `url` fields differ only in `/de/` prefix
+  - Localized text fields are translated (`title`, `description` for pages; `title`, `excerpt` for posts)
 
 - [ ] **SEO Optimization**:
   - `title`: 50-60 characters, descriptive, includes keyword

docs/03-adding-pages.md

@@ -9,8 +9,12 @@ This comprehensive guide walks you through the entire process of adding a new pa
 Before starting, ensure you're familiar with:
 - [01 - Repository Overview](./01-repo-overview.md): Project structure and technology stack
 - [02 - Content Folder Guide](./02-content-folder.md): Content organization, front matter standards, and localization
+- [04 - Adding Blog Posts](./04-adding-blog-post.md): Use this instead when your change is in `content/posts/`
 - Basic Next.js App Router concepts (routes, layouts, page components)
 
+This guide is for standard pages (`content/<slug>/index.md` + route files).  
+For posts in `content/posts/`, follow [04 - Adding Blog Posts](./04-adding-blog-post.md).
+
 ## Step-by-Step Implementation Workflow
 
 ### Step 1: Create Markdown Content Files

docs/04-adding-blog-post.md

@@ -0,0 +1,116 @@
+# 04 - Adding Blog Posts
+
+## Purpose
+
+This guide documents the exact workflow for adding posts to the Open Elements article section.
+
+Use this guide for anything under `content/posts/`.  
+For standard pages (for example `content/about/index.md`), use [03 - Adding Pages](./03-adding-pages.md).
+
+## 1. Create Post Files
+
+Blog posts are flat files in `content/posts/`:
+
+```text
+content/posts/
+  YYYY-MM-DD-post-slug.md
+  YYYY-MM-DD-post-slug.de.md
+```
+
+- English file: `YYYY-MM-DD-post-slug.md`
+- German translation: `YYYY-MM-DD-post-slug.de.md` (recommended for user-facing content)
+
+Example:
+
+```text
+content/posts/2026-02-27-dependency-health-checks.md
+content/posts/2026-02-27-dependency-health-checks.de.md
+```
+
+The URL slug is derived from the filename:
+
+- `2026-02-27-dependency-health-checks.md` -> `/posts/2026-02-27-dependency-health-checks`
+- `2026-02-27-dependency-health-checks.de.md` -> `/de/posts/2026-02-27-dependency-health-checks`
+
+## 2. Add Front Matter (Required Fields)
+
+Posts in this repository are parsed by `src/lib/markdown.ts` and must use this schema:
+
+```yaml
+---
+outdated: false
+showInBlog: true
+title: "Dependency Health Checks for Maven Builds"
+date: 2026-02-27
+author: sebastian
+excerpt: "A short teaser shown in article cards and metadata."
+categories: [open-source, maven, security]
+preview_image: "/posts/preview-images/open-source-green.svg"
+---
+```
+
+Field notes:
+
+- `title`: display title and SEO title base
+- `date`: `YYYY-MM-DD`
+- `author`: author id (not free text). Match an id in `src/data/en/team.json` and `src/data/de/team.json`
+- `excerpt`: used in listing cards and metadata description
+- `categories`: array rendered as tags
+- `preview_image`: web path under `public/`
+- `showInBlog`: set `false` to hide from listing pages
+- `outdated`: set `true` to hide from listing pages
+
+## 3. Write Content and Use Correct Links
+
+Write markdown below the front matter. Keep heading structure consistent between EN/DE versions.
+
+Internal link rules:
+
+- Standard pages:
+  - EN: `/about`, `/contact`
+  - DE: `/de/about`, `/de/contact`
+- Blog posts:
+  - EN: `/posts/<YYYY-MM-DD-slug>`
+  - DE: `/de/posts/<YYYY-MM-DD-slug>`
+
+Do not use `/blog/...` in new content. The active route is `/posts/...`.
+
+## 4. Add Images
+
+Store post-specific assets in a folder matching the post slug:
+
+```text
+public/posts/2026-02-27-dependency-health-checks/
+  architecture.png
+  pipeline-diff.png
+```
+
+Reference them with web paths:
+
+```markdown
+![Pipeline comparison](/posts/2026-02-27-dependency-health-checks/pipeline-diff.png)
+```
+
+## 5. Validate Locally
+
+1. Run `pnpm run dev`
+2. Open:
+   - EN listing: `http://localhost:3000/posts`
+   - DE listing: `http://localhost:3000/de/posts`
+   - EN post: `http://localhost:3000/posts/<slug>`
+   - DE post: `http://localhost:3000/de/posts/<slug>`
+3. Verify preview image, excerpt, categories, author card, and all links
+
+## 6. Common Pitfalls
+
+- Wrong route prefix in links (`/blog/...` instead of `/posts/...`)
+- Missing `.de.md` suffix for German files
+- `author` not matching a team id
+- Using filesystem-like image paths (`public/...`) instead of web paths (`/...`)
+- Missing `excerpt` or `preview_image`, causing weak list cards and metadata
+
+## Related Docs
+
+- [02 - Content Folder Guide](./02-content-folder.md)
+- [05 - First Contribution Checklist](./05-first-contribution-checklist.md)
+- [06 - Testing and Quality Checks](./06-testing-and-quality-checks.md)

docs/04-first-contribution-checklist.md docs/05-first-contribution-checklist.mddocs/04-first-contribution-checklist.md renamed to docs/05-first-contribution-checklist.md

@@ -1,4 +1,4 @@
-# 04 - First Contribution Checklist
+# 05 - First Contribution Checklist
 
 ## Purpose and Scope
 
@@ -438,4 +438,4 @@ git push origin fix/issue-123-description
 - **Stuck on implementation?** → Check [01 - Repository Overview](./01-repo-overview.md)
 - **Content structure unclear?** → See [02 - Content Folder Guide](./02-content-folder.md)
 - **Adding a new page?** → Follow [03 - Adding Pages](./03-adding-pages.md)
-- **Build or test failures?** → Check [05 - Testing and Quality Checks](./05-testing-and-quality-checks.md)
+- **Build or test failures?** → Check [06 - Testing and Quality Checks](./06-testing-and-quality-checks.md)

docs/05-testing-and-quality-checks.md docs/06-testing-and-quality-checks.mddocs/05-testing-and-quality-checks.md renamed to docs/06-testing-and-quality-checks.md

@@ -1,4 +1,4 @@
-# 05 - Testing and Quality Checks
+# 06 - Testing and Quality Checks
 
 ## Overview