apps-ose-platform-web__developing-content

Original source / Raw SKILL.md

---
name: apps-ose-platform-web__developing-content
description: Guide for creating content on ose-platform-web Hugo site using PaperMod theme. Covers English-only landing page structure, update posts with date-prefixed filenames, PaperMod frontmatter (cover images, table of contents, author field), simple flat organization, and ose-platform-web specific conventions. Essential for ose-platform-web content creation tasks
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash]
tags:
  - hugo
  - ose-platform-web
  - papermod
  - landing-page
  - english-only
---

# Hugo OSE Platform Development Skill

## Purpose

This Skill provides guidance for creating and managing content on the **ose-platform-web** Hugo site, which uses the PaperMod theme and serves as an English-only project landing page.

**When to use this Skill:**

- Creating platform updates on ose-platform-web
- Writing about page content
- Managing landing page structure
- Configuring PaperMod frontmatter
- Understanding ose-platform-web specific patterns

## Core Concepts

### Site Overview

**ose-platform-web** (`apps/ose-platform-web/`):

- **Site**: oseplatform.com
- **Theme**: PaperMod v7.0+ (compatible with v8.0)
- **Purpose**: English-only project landing page
- **Content Types**: Platform updates, about page
- **Structure**: Flat, simple organization

### English-Only Content

**NO Multi-Language Structure**:

- All content in English
- No language subdirectories
- Simple, flat content organization
- No bilingual content management

**Contrast with ayokoding-web**:

- ayokoding-web: Bilingual (`/en/`, `/id/`) with complex structure
- ose-platform-web: English-only with flat structure

## Content Structure

```
apps/ose-platform-web/content/
├── updates/                               # Platform updates
│   ├── _index.md
│   ├── 2025-12-07-initial-release.md    # Date-prefixed
│   └── 2025-11-20-announcement.md        # Date-prefixed
└── about.md                               # About page
```

**Simplicity principle**: No deep hierarchies, no complex organization.

## Date-Prefixed Filenames

### Update Post Naming

**CRITICAL**: All update posts use date prefix for automatic chronological sorting

**Format**: `YYYY-MM-DD-title.md`

**Examples**:

- `2025-12-07-beta-release.md`
- `2025-11-20-platform-announcement.md`
- `2025-10-15-architecture-overview.md`

**Rationale**:

- Automatic chronological ordering (no weight management needed)
- Clear publication date from filename
- Easy sorting in file system

### About Page Naming

**Format**: Simple slug without date prefix

**Example**: `about.md`

## PaperMod Frontmatter

### Required Fields

```yaml
---
title: "Post Title"
date: 2025-12-07T14:30:00+07:00
draft: false
---
```

**Minimal frontmatter** - PaperMod has fewer required fields than Hextra.

### Recommended Fields

```yaml
---
title: "OSE Platform Beta Release"
date: 2025-12-07T14:30:00+07:00
draft: false
description: "Brief description for meta tags and summaries"
summary: "Summary text for list pages"
tags: ["release", "beta", "announcement"]
categories: ["updates"]
showtoc: true # Enable table of contents
cover:
  image: "/images/beta-release.png"
  alt: "OSE Platform Dashboard Screenshot"
  caption: "New dashboard interface"
---
```

### PaperMod-Specific Fields

**Table of Contents**:

```yaml
showtoc: true # Show ToC
tocopen: false # ToC collapsed by default
```

**Metadata Display**:

```yaml
hidemeta: false # Show post metadata (date, reading time)
comments: true # Show comments section (if enabled)
```

**Search & SEO**:

```yaml
searchHidden: false # Include in site search
hideSummary: false # Show in list pages
robotsNoIndex: false # Allow search engine indexing
```

**Cover Image**:

```yaml
cover:
  image: "/images/cover.png" # Path to image
  alt: "Image description" # REQUIRED for accessibility
  caption: "Optional caption" # Displayed under image
  relative: false # Use absolute paths from /static/
  responsiveImages: true # Generate responsive variants
  hidden: false # Show on current page
```

### Author Field Rules

**FLEXIBLE** (unlike ayokoding-web):

- `author:` field allowed per-post
- Can be single author or multiple authors
- No site-level default restriction

**Examples**:

```yaml
# Single author
author: "OSE Platform Team"

# Multiple authors
author: ["John Doe", "Jane Smith"]
```

**Contrast with ayokoding-web**: ayokoding-web restricts `author` field to rants/celoteh only. ose-platform-web has no such restriction.

## Content Types

### Update Posts

**Location**: `content/updates/`

**Purpose**: Platform progress, feature releases, announcements

**Frontmatter example**:

```yaml
---
title: "OSE Platform Beta Release"
date: 2025-12-07T14:30:00+07:00
draft: false
tags: ["release", "beta", "announcement"]
categories: ["updates"]
summary: "Introducing the beta version of Open Sharia Enterprise Platform"
showtoc: true
cover:
  image: "/images/beta-release.png"
  alt: "OSE Platform Dashboard Screenshot"
---
```

### About Page

**Location**: `content/about.md`

**Purpose**: Project information, team details, contact info

**Frontmatter example**:

```yaml
---
title: "About OSE Platform"
url: "/about/"
summary: "Learn about Open Sharia Enterprise Platform"
showtoc: false
---
```

## Internal Links

**Format**: Absolute paths without `.md` extension

**Hugo shortcodes available**:

```markdown
# Using ref shortcode for content references

Check out our [getting started guide]({{< ref "/updates/getting-started" >}})

# Direct absolute paths

[Beta Release](/updates/2025-12-07-beta-release)
```

**Contrast with ayokoding-web**:

- ayokoding-web: MUST use absolute paths with language prefix (`/en/`, `/id/`)
- ose-platform-web: Absolute paths without language prefix (English-only)

## Asset Organization

**Location**: `apps/ose-platform-web/static/`

**Structure**:

```
static/
├── images/
│   ├── updates/
│   └── about/
└── casts/                    # Asciinema recordings
```

**Image References**:

```markdown
# Markdown image

![OSE Platform Dashboard](/images/updates/dashboard.png)

# Hugo figure shortcode

{{< figure src="/images/updates/architecture.png" alt="System Architecture" caption="OSE Platform Architecture" >}}
```

**Paths from `/static/`**:

- `static/images/dashboard.png` → `/images/dashboard.png`
- `static/casts/demo.cast` → `/casts/demo.cast`

## PaperMod Features

### Navigation

PaperMod provides:

- **Breadcrumbs**: Automatic breadcrumb navigation
- **Archive**: Chronological post listing
- **Smooth scrolling**: Anchor link behavior
- **Table of contents**: Per-page ToC (configurable)

### Theme Toggle

```yaml
# Site config (hugo.yaml)
params:
  defaultTheme: auto # Options: light, dark, auto
```

**User preference**: Stored in localStorage, persists across sessions.

### Social Sharing

```yaml
# Site config (hugo.yaml)
params:
  ShareButtons:
    - twitter
    - linkedin
    - reddit
```

**Per-page control**:

```yaml
---
ShowShareButtons: true # Enable share buttons for this post
---
```

### Home Page Configuration

```yaml
# Site config (hugo.yaml)
params:
  homeInfoParams:
    Title: "Welcome to OSE Platform"
    Content: "Open Sharia Enterprise Platform documentation and updates"

  socialIcons:
    - name: github
      url: "https://github.com/wahidyankf/open-sharia-enterprise"
    - name: twitter
      url: "https://twitter.com/oseplatform"
```

## Comparison with ayokoding-web

| Aspect               | ose-platform-web                 | ayokoding-web                                     |
| -------------------- | -------------------------------- | ------------------------------------------------- |
| **Theme**            | PaperMod                         | Hextra                                            |
| **Languages**        | English only                     | Bilingual (Indonesian/English)                    |
| **Structure**        | Flat (updates/, about.md)        | Deep hierarchy (learn/archived/crash-courses/...) |
| **Archetypes**       | 1 (default)                      | 5 (learn, celoteh, konten-video, etc.)            |
| **Weight Ordering**  | Optional (date-prefix for posts) | Strict level-based system (mandatory)             |
| **Navigation**       | Breadcrumbs, archive             | Auto-sidebar, 3-layer nav                         |
| **Author Field**     | Per-post (flexible)              | Site-level default (exceptions for rants/celoteh) |
| **Complexity**       | Simple, minimal                  | Feature-rich, complex                             |
| **Content Types**    | Updates, about                   | Tutorials, essays, videos                         |
| **Overview Files**   | Not required                     | Required (overview.md, ikhtisar.md)               |
| **Internal Links**   | Absolute paths                   | Absolute paths with language prefix               |
| **Primary Purpose**  | Landing page & updates           | Educational platform                              |
| **Target Audience**  | Enterprise users                 | Indonesian developers (bilingual)                 |
| **Tutorial Content** | No                               | Yes (detailed programming tutorials)              |

**Key Takeaway**: ose-platform-web is MUCH simpler than ayokoding-web.

## Common Patterns

### Creating Update Post

```bash
# 1. Create file with date prefix
hugo new content/updates/2025-12-07-feature-release.md

# 2. Edit frontmatter
# (add title, date, tags, cover image)

# 3. Write content
# (markdown content)

# 4. Set draft: false when ready to publish
```

### Creating About Page

```bash
# 1. Create file
hugo new content/about.md

# 2. Edit frontmatter
# (add title, url, summary)

# 3. Write content
# (project info, team details)

# 4. Set draft: false to publish
```

## Content Validation Checklist

Before publishing:

- [ ] Frontmatter uses YAML format (2-space indentation)
- [ ] Date format is `YYYY-MM-DDTHH:MM:SS+07:00`
- [ ] Description length is 150-160 characters (if present)
- [ ] Internal links use absolute paths without `.md`
- [ ] All images have descriptive alt text
- [ ] Update posts use date-prefixed filenames (`YYYY-MM-DD-title.md`)
- [ ] Cover images have alt text
- [ ] Summary field provided for list pages
- [ ] Draft status set correctly (`draft: true/false`)
- [ ] Tags and categories are arrays (if present)

## Common Mistakes

### ❌ Mistake 1: Using language prefixes

**Wrong**: `/en/updates/post` (ose-platform-web is English-only)

**Right**: `/updates/post`

### ❌ Mistake 2: Forgetting date prefix for updates

**Wrong**: `feature-release.md` (no chronological ordering)

**Right**: `2025-12-07-feature-release.md`

### ❌ Mistake 3: Missing cover image alt text

```yaml
# Wrong
cover:
  image: "/images/cover.png"
  # No alt text - accessibility violation

# Right
cover:
  image: "/images/cover.png"
  alt: "OSE Platform Dashboard showing metrics"
```

### ❌ Mistake 4: Using Hextra conventions

**Wrong**: Applying ayokoding-web conventions (weight system, ikhtisar files)

**Right**: Use simple PaperMod conventions (optional weight, no overview files)

## Best Practices

### Update Post Workflow

1. **Plan content**: Outline key points
2. **Create file**: Use date-prefixed filename
3. **Write frontmatter**: Title, date, tags, cover image
4. **Write content**: Clear, concise updates
5. **Add visuals**: Cover image, diagrams if needed
6. **Validate**: Check frontmatter, links, alt text
7. **Publish**: Set `draft: false`

### About Page Maintenance

1. **Keep current**: Update as project evolves
2. **Clear structure**: Sections for vision, team, contact
3. **No date needed**: About page is timeless
4. **Link to updates**: Reference update posts for news

## Reference Documentation

**Primary Convention**: [Hugo Content Convention - ose-platform-web](../../../governance/conventions/hugo/ose-platform.md)

**Related Conventions**:

- [Hugo Content Shared](../../../governance/conventions/hugo/shared.md) - Shared Hugo patterns
- [Content Quality Principles](../../../governance/conventions/content/quality.md) - Universal quality standards

**Related Skills**:

- `hugo-ayokoding-development` - Comparison with ayokoding-web patterns
- `color-accessibility-diagrams` - Accessible diagrams for technical content

**Related Agents**:

- `apps__ose-platform-web__content-maker` - Creates ose-platform-web content
- `apps__ose-platform-web__content-checker` - Validates ose-platform-web content
- `apps__ose-platform-web__deployer` - Deploys ose-platform-web

**External Resources**:

- [PaperMod Official Documentation](https://adityatelange.github.io/hugo-PaperMod/)
- [PaperMod GitHub Repository](https://github.com/adityatelange/hugo-PaperMod)

---

This Skill packages essential ose-platform-web development knowledge for creating simple, effective landing page content. For comprehensive details, consult the primary convention document.

## Deployment Workflow

Deploy ose-platform-web to production using Vercel integration.

### Production Branch

**Branch**: `prod-ose-platform-web`  
**Purpose**: Deployment-only branch that Vercel monitors  
**Build System**: Vercel (Hugo SSG with PaperMod theme)

### Deployment Process

**Step 1: Validate Current State**

```bash
# Ensure on main branch
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [ "$CURRENT_BRANCH" != "main" ]; then
  echo "❌ Must be on main branch"
  exit 1
fi

# Check for uncommitted changes
if [ -n "$(git status --porcelain)" ]; then
  echo "❌ Uncommitted changes detected"
  exit 1
fi
```

**Step 2: Force Push to Production**

```bash
# Deploy to production
git push origin main:prod-ose-platform-web --force
```

**Step 3: Vercel Auto-Build**

Vercel automatically:

- Detects push to prod-ose-platform-web branch
- Pulls latest content
- Builds Hugo site with PaperMod theme
- Deploys to production URL

### Why Force Push

**Safe for deployment branches**:

- prod-ose-platform-web is deployment-only (no direct commits)
- Always want exact copy of main branch
- Trunk-based development: main is source of truth

### Deployment Safety

**Pre-deployment checks**:

- ✅ On main branch
- ✅ No uncommitted changes
- ✅ Latest from remote

**No local build**: Vercel handles all build operations

## References

**Primary Convention**: [Hugo Content Convention - ose-platform-web](../../../governance/conventions/hugo/ose-platform.md)

**Related Conventions**:

- [Hugo Content Shared](../../../governance/conventions/hugo/shared.md) - Shared Hugo patterns
- [Content Quality Principles](../../../governance/conventions/content/quality.md) - Universal quality standards

**Related Skills**:

- `apps__ayokoding-web__developing-content` - Comparison with ayokoding-web patterns
- `docs__creating-accessible-diagrams` - Accessible diagrams for technical content


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### ../../../governance/conventions/hugo/ose-platform.md

```markdown
---
title: "Hugo Content Convention - ose-platform-web"
description: Hugo content conventions specific to ose-platform-web (PaperMod theme, project landing page)
category: explanation
subcategory: conventions
tags:
  - hugo
  - content
  - ose-platform-web
  - papermod
  - landing-page
created: 2025-12-13
updated: 2025-12-13
---

# Hugo Content Convention - ose-platform-web

This document defines Hugo content conventions specific to **ose-platform-web** - an English-only project landing page using the PaperMod theme.

## Principles Implemented/Respected

This convention implements the following core principles:

- **[Simplicity Over Complexity](../../principles/general/simplicity-over-complexity.md)**: Flat content structure (updates/ and about.md) - no deep hierarchies or complex organization. English-only, single theme, minimal configuration. Updates sorted by date automatically - no manual weight management.

- **[Explicit Over Implicit](../../principles/software-engineering/explicit-over-implicit.md)**: Update filenames encode the date (YYYY-MM-DD prefix) making chronological order explicit and sortable.

## Purpose

This convention defines content creation standards specific to the ose-platform-web Hugo site, which uses the PaperMod theme and serves as an English-only landing page. It establishes frontmatter requirements and content patterns unique to ose-platform-web, complementing the shared Hugo conventions.

## Scope

### What This Convention Covers

- **OSE platform frontmatter** - Required YAML fields specific to PaperMod theme
- **Landing page structure** - English-only single-page design
- **PaperMod theme specifics** - Cover image, author info, table of contents, and other PaperMod features
- **Navigation patterns** - Simple navigation structure for landing page
- **Content organization** - How to structure landing page sections

### What This Convention Does NOT Cover

- **Shared Hugo conventions** - Covered in [Hugo Content Shared Convention](./shared.md)
- **Bilingual content** - This site is English-only, see ayokoding-web for bilingual patterns
- **Hugo theme development** - Covered in [Hugo Development Convention](../development/hugo/development.md)
- **Deployment** - Covered by ose-platform-web-deployer agent

## Prerequisites

**IMPORTANT**: This document assumes familiarity with [Shared Hugo Content Conventions](./shared.md).

Read the shared conventions first, as they cover:

- Inherited conventions (8 standards from docs/)
- Adapted conventions (5 Hugo-specific modifications)
- Hugo-specific conventions (6 basic concepts)

This document covers **ose-platform-web specific patterns only**.

---

## ose-platform-web Overview

**Site**: [oseplatform.com](https://oseplatform.com)
**Theme**: PaperMod v7.0+ (compatible with v8.0)
**Purpose**: English-only project landing page with progress updates
**Languages**: English only
**Repository Path**: `apps/ose-platform-web/`

**Content Types**:

- Platform updates (progress, releases, announcements)
- About page (project information)

---

## Content Structure

```
apps/ose-platform-web/content/
├── updates/                               # Platform updates
│   ├── _index.md
│   ├── 2025-12-07-initial-release.md
│   └── 2025-11-20-announcement.md
└── about.md                               # About page
```

**Simple flat structure** - no deep hierarchies, no multi-language subdirectories.

---

## PaperMod Theme

**Official Documentation**: [PaperMod Site](https://adityatelange.github.io/hugo-PaperMod/)
**GitHub**: [adityatelange/hugo-PaperMod](https://github.com/adityatelange/hugo-PaperMod)
**Last Updated**: 2025-10-26 | **GitHub Stars**: 12,755
**Theme Version Compatibility**: Targets v7.0+, compatible with v8.0

**Description**: Fast, clean, responsive Hugo theme based on hugo-paper, focused on simplicity with useful features.

### PaperMod Key Features

- **Design**: Clean, simple, fast, and responsive
- **Theme Support**: Light/dark mode with localStorage preference
- **Navigation**: Smooth scrolling, breadcrumbs, archive, search
- **Social**: Share buttons for multiple platforms
- **SEO**: Built-in SEO optimization
- **Accessibility**: Reduced-motion support, semantic HTML
- **Analytics**: Google Analytics, Bing, Yandex site verification

### PaperMod-Specific Frontmatter Fields

```yaml
---
title: "Post Title"
date: 2025-12-07T14:30:00+07:00
draft: false
description: "Post description" # Subtitle/description
summary: "Brief summary" # For list pages
showtoc: true # Enable table of contents
tocopen: false # ToC collapsed by default
hidemeta: false # Show post metadata
comments: true # Show comments section
searchHidden: false # Include in search
hideSummary: false # Show in lists
author: "Author Name" # Single or multiple authors
weight: 1 # Page order/pin position
canonicalURL: "https://..." # Canonical link
robotsNoIndex: false # Exclude from indexing
cover:
  image: "/images/cover.png" # Cover image
  caption: "Image caption" # Cover caption
  alt: "Image description" # Alt text
  relative: false # Use relative paths
  responsiveImages: true # Generate responsive variants
  hidden: false # Hide on current page
tags: ["tag1", "tag2"]
categories: ["updates"]
---
```

### PaperMod Shortcodes

PaperMod is minimal and relies primarily on **Hugo's built-in shortcodes**:

```markdown
{{< figure src="/images/dashboard.png" caption="OSE Platform Dashboard" >}}

Check out our [getting started guide]({{< ref "/updates/getting-started" >}})
```

**Available Hugo Built-in Shortcodes**:

- `{{< ref >}}` - Internal content reference
- `{{< relref >}}` - Relative content reference
- `{{< figure >}}` - Image with caption
- `{{< highlight >}}` - Syntax highlighting
- `{{< youtube >}}` - Embed YouTube video
- `{{< tweet >}}` - Embed tweet

---

## ose-platform-web Site Patterns

### English-Only Content

**No Multi-Language Structure**:

- All content in English
- No language subdirectories
- Simple, flat content organization

### Simple Content Organization

**Content Types**:

1. **Updates** (`content/updates/`)
   - Platform progress reports
   - Feature releases
   - Announcements
   - Date-prefixed filenames: `YYYY-MM-DD-title.md`

2. **About Page** (`content/about.md`)
   - Project information
   - Team details
   - Contact information

**File Naming Pattern**:

```
content/
├── updates/
│   ├── _index.md
│   ├── 2025-12-07-beta-release.md         # Date-prefixed
│   └── 2025-11-20-announcement.md          # Date-prefixed
└── about.md                                 # Simple slug
```

### Frontmatter Patterns

**Updates Content**:

```yaml
---
title: "OSE Platform Beta Release"
date: 2025-12-07T14:30:00+07:00
draft: false
tags: ["release", "beta", "announcement"]
categories: ["updates"]
summary: "Introducing the beta version of Open Sharia Enterprise Platform"
showtoc: true
cover:
  image: "/images/beta-release.png"
  alt: "OSE Platform Dashboard Screenshot"
---
```

**About Page**:

```yaml
---
title: "About OSE Platform"
url: "/about/"
summary: "Learn about Open Sharia Enterprise Platform"
showtoc: false
---
```

### Author Field Usage

**Flexible Author Field**:

- `author:` field is allowed and used per-post
- Can be single author or multiple authors
- No site-level default author restriction (unlike ayokoding-web)

**Example**:

```yaml
---
title: "Platform Architecture Overview"
author: "OSE Platform Team"
# or
author: ["John Doe", "Jane Smith"]
---
```

---

## Archetypes

**Location**: `apps/ose-platform-web/archetypes/`

**Available Archetypes** (1 total):

### default.md - All Content Types

```yaml
---
title: '{{ replace .File.ContentBaseName "-" " " | title }}'
date: { { .Date } }
draft: false
tags: []
categories: []
summary: ""
---
```

**Simple archetype** - applies to all content (updates, about pages, etc.)

---

## Taxonomy

**Categories**:

- `["updates"]` - Platform updates (primary category)
- Flexible - can add new categories as needed

**Tags**:

- Flexible topics (e.g., "release", "feature", "announcement", "architecture")
- Multiple tags allowed per content
- Use lowercase format

**Series** (optional):

- `series: ["platform-architecture"]` - For multi-part series
- Groups related posts together

**Example**:

```yaml
---
title: "Platform Architecture Overview - Part 1"
tags: ["architecture", "system-design"]
categories: ["updates"]
series: ["platform-architecture"]
---
```

---

## Configuration Highlights

**File**: `apps/ose-platform-web/hugo.yaml`

### Basic Configuration

```yaml
baseURL: "https://oseplatform.com/"
title: "OSE Platform"
languageCode: "en-us"
defaultContentLanguage: "en"

theme: "PaperMod"
```

### PaperMod Parameters

```yaml
params:
  env: production
  author: "OSE Platform Team"

  # Content display
  ShowReadingTime: true
  ShowShareButtons: true
  ShowCodeCopyButtons: true
  ShowPostNavLinks: true
  ShowBreadCrumbs: true

  # Theme
  defaultTheme: auto # light/dark/auto

  # Social sharing
  ShareButtons:
    - twitter
    - linkedin
    - reddit
```

### Home Page Configuration

```yaml
params:
  homeInfoParams:
    Title: "Welcome to OSE Platform"
    Content: "Open Sharia Enterprise Platform documentation and updates"

  socialIcons:
    - name: github
      url: "https://github.com/wahidyankf/open-sharia-enterprise"
    - name: twitter
      url: "https://twitter.com/oseplatform"
```

### Cover Image Defaults

```yaml
params:
  cover:
    responsiveImages: true
    hidden: false
    linkFullImages: true
```

---

## Content Creation Workflow

### Creating New Content

```bash
# Create update post
hugo new content/updates/2025-12-07-feature-release.md

# Create about page
hugo new content/about.md
```

### Content Validation Checklist

Before publishing, verify:

- [ ] Frontmatter uses YAML format with 2-space indentation
- [ ] Date format is `YYYY-MM-DDTHH:MM:SS+07:00`
- [ ] Description length is 150-160 characters (if present)
- [ ] Internal links use absolute paths without `.md` extension
- [ ] All images have descriptive alt text
- [ ] Mermaid diagrams use accessible color palette (if used)
- [ ] Tags and categories are properly formatted arrays
- [ ] Draft status is set correctly (`draft: true/false`)
- [ ] Update posts use date-prefixed filenames
- [ ] Cover images have alt text
- [ ] Summary field is provided for list pages
- [ ] Assets are organized in appropriate `static/` subdirectories

---

## Asset Organization

**Location**: `apps/ose-platform-web/static/`

**Structure**:

```
static/
├── images/
│   ├── updates/
│   └── about/
└── casts/                    # Asciinema recordings
```

**Image References**:

```markdown
![OSE Platform Dashboard](/images/updates/dashboard.png)

{{< figure src="/images/updates/architecture.png" alt="System Architecture" caption="OSE Platform Architecture" >}}
```

**Asciinema Casts**:

```markdown
<!-- Reference terminal recordings -->

![Terminal Demo](/casts/demo.cast)
```

---

## Comparison with ayokoding-web

| Aspect                 | ose-platform-web                       | ayokoding-web                                     |
| ---------------------- | -------------------------------------- | ------------------------------------------------- |
| **Theme**              | PaperMod                               | Hextra                                            |
| **Languages**          | English only                           | Bilingual (Indonesian/English)                    |
| **Content Types**      | Updates, about page                    | Learning, essays, video content                   |
| **Content Structure**  | Flat (updates/, about.md)              | Deep hierarchy (learn/archived/crash-courses/...) |
| **Archetypes**         | 1 type (default)                       | 5 types (learn, celoteh, konten-video, etc.)      |
| **Primary Purpose**    | Project landing & progress updates     | Educational platform for developers               |
| **Target Audience**    | Enterprise users (international)       | Indonesian developers (bilingual)                 |
| **Tutorial Content**   | No (not applicable)                    | Yes (id/belajar/, en/learn/)                      |
| **Navigation**         | Breadcrumbs, archive, smooth scrolling | Auto-sidebar, 3-layer nav, breadcrumbs            |
| **Author Field**       | Per-post (flexible)                    | Site-level default (rants/celoteh exceptions)     |
| **Complexity**         | Simple, minimal                        | Feature-rich, complex structure                   |
| **Weight Ordering**    | Optional                               | Strict rules (1=index, 2=overview, 3+=content)    |
| **Overview Files**     | Not required                           | Required in every folder                          |
| **Diátaxis Structure** | Not applicable                         | Optional at topic level                           |

---

## References

**Required Reading**:

- [Shared Hugo Content Conventions](./shared.md) - Read this first!

**Theme Documentation**:

- [PaperMod Official Documentation](https://adityatelange.github.io/hugo-PaperMod/)
- [PaperMod GitHub Repository](https://github.com/adityatelange/hugo-PaperMod)

**Related AI Agents**:

- [ose-platform-web-content-maker](https://github.com/wahidyankf/open-sharia-enterprise/blob/main/.claude/agents/ose-platform-web-content-maker.md) - Creates ose-platform-web content
- [ose-platform-web-content-checker](https://github.com/wahidyankf/open-sharia-enterprise/blob/main/.claude/agents/ose-platform-web-content-checker.md) - Validates ose-platform-web content
- [ose-platform-web-deployer](https://github.com/wahidyankf/open-sharia-enterprise/blob/main/.claude/agents/ose-platform-web-deployer.md) - Deploys ose-platform-web to production

```

### ../../../governance/conventions/hugo/shared.md

```markdown
---
title: "Hugo Content Convention - Shared"
description: Common Hugo conventions shared between ayokoding-web and ose-platform-web
category: explanation
subcategory: conventions
tags:
  - hugo
  - content
  - conventions
  - markdown
  - frontmatter
  - shared
created: 2025-12-13
updated: 2025-12-22
---

# Hugo Content Convention - Shared

This document defines **common Hugo conventions** that apply to ALL Hugo sites in this repository:

- **ayokoding-web** - Educational platform using Hextra theme ([site-specific conventions](./ayokoding.md))
- **ose-platform-web** - Project landing page using PaperMod theme ([site-specific conventions](./ose-platform.md))

## Principles Implemented/Respected

This convention implements the following core principles:

- **[Accessibility First](../../principles/content/accessibility-first.md)**: Requires alt text for images, color-blind friendly palettes in diagrams, proper heading hierarchy, and WCAG-compliant content across all Hugo sites.

- **[No Time Estimates](../../principles/content/no-time-estimates.md)**: Inherited from docs/ - forbids time-based framing in Hugo content ("takes 30 minutes", "complete in 2 weeks").

- **[Simplicity Over Complexity](../../principles/general/simplicity-over-complexity.md)**: Shared conventions document eliminates duplication between site-specific documents. Common standards in one place, site-specific patterns separated cleanly.

## Purpose

This convention establishes shared standards that apply to **all Hugo sites** in the repository (ayokoding-web and ose-platform-web). It defines universal frontmatter requirements, markdown formatting, and content quality rules that every Hugo site must follow, providing a common foundation before site-specific conventions apply.

## Scope

### What This Convention Covers

- **Universal frontmatter** - YAML fields required by all Hugo sites
- **Markdown syntax** - How to write content for Hugo markdown processing
- **Content formatting** - Headings, lists, code blocks, and other markdown elements
- **Asset management** - Images, diagrams, and other media files
- **Cross-site standards** - Quality requirements for all Hugo content

### What This Convention Does NOT Cover

- **Site-specific conventions** - See [ayokoding-web convention](./ayokoding.md) and [ose-platform-web convention](./ose-platform.md)
- **Hugo theme development** - Covered in [Hugo Development Convention](../development/hugo/development.md)
- **Content strategy** - What content to create (covered in domain conventions)
- **Deployment** - Covered by site-specific deployer agents

## Document Structure

This shared document contains conventions that apply to **both sites**:

1. **Inherited Conventions** (8) - Standards from `docs/` that apply to Hugo content
2. **Adapted Conventions** (5) - Standards modified for Hugo's requirements
3. **Hugo-Specific Conventions** (7) - Basic Hugo concepts that apply to both sites

**Site-specific patterns** (themes, configurations, workflows) are documented in separate files:

- [ayokoding-web specific conventions](./ayokoding.md)
- [ose-platform-web specific conventions](./ose-platform.md)

```mermaid
%% Color Palette: Blue #0173B2, Orange #DE8F05, Teal #029E73, Purple #CC78BC, Brown #CA9161
%% All colors are color-blind friendly and meet WCAG AA contrast standards
graph TD
    A[Hugo Content] --> B[Shared Conventions<br/>This Document]
    A --> C[ayokoding-web<br/>Site-Specific]
    A --> D[ose-platform-web<br/>Site-Specific]

    B --> B1[Inherited<br/>8 standards]
    B --> B2[Adapted<br/>5 standards]
    B --> B3[Hugo-Specific<br/>7 concepts]

    C --> C1[Hextra Theme]
    C --> C2[Bilingual Educational]

    D --> D1[PaperMod Theme]
    D --> D2[Landing Page]

    style B fill:#0173B2,stroke:#000,color:#fff
    style C fill:#DE8F05,stroke:#000,color:#000
    style D fill:#029E73,stroke:#000,color:#fff
```

---

## Inherited Conventions

These conventions from `docs/` directory apply to Hugo content without modification.

### 1. Mathematical Notation Convention

**Reference**: [Mathematical Notation Convention](../formatting/mathematical-notation.md)

**Application to Hugo**: Use LaTeX notation for all mathematical equations and formulas in Hugo content.

- **Inline math**: `$...$` for inline equations (e.g., $r_f$, $\beta$)
- **Display math**: `$$...$$` for block equations
- **Applies to**: Learning content in ayokoding-web (tutorials, technical explanations)

**Example (ayokoding-web learning content)**:

```markdown
The risk-free rate $r_f$ is typically represented using the formula:

$$
r_f = r_{real} + \pi
$$

where $\pi$ represents the expected inflation rate.
```

**Important**: Do NOT use LaTeX inside code blocks, Mermaid diagrams, or ASCII art.

### 2. Color Accessibility Convention

**Reference**: [Color Accessibility Convention](../formatting/color-accessibility.md)

**Application to Hugo**: All Mermaid diagrams in Hugo content MUST use the verified accessible color palette.

**Accessible Color Palette**:

- Blue: `#0173B2`
- Orange: `#DE8F05`
- Teal: `#029E73`
- Purple: `#CC78BC`
- Brown: `#CA9161`

**Applies to**: All diagrams in both sites (ayokoding-web and ose-platform-web)

**Example**:

````markdown
```mermaid
%% Color Palette: Blue #0173B2, Orange #DE8F05, Teal #029E73, Purple #CC78BC, Brown #CA9161
%% All colors are color-blind friendly and meet WCAG AA contrast standards
graph LR
    A[Start] --> B[Process]
    B --> C[End]

    style A fill:#0173B2,stroke:#000,color:#fff
    style B fill:#DE8F05,stroke:#000,color:#000
    style C fill:#029E73,stroke:#000,color:#fff
```
````

**Never use**: Red, green, or yellow (invisible to color blindness types)

### 3. Diagrams Convention

**Reference**: [Diagrams and Schema Convention](../formatting/diagrams.md)

**Application to Hugo**: Use Mermaid diagrams as primary format. Prefer vertical orientation (top-down) for mobile-friendly viewing.

**Applies to**: All visual content in both sites

**Diagram Types**:

- Flowcharts for processes
- Sequence diagrams for interactions
- Class diagrams for architecture
- State diagrams for workflows

**Example (ayokoding-web tutorial)**:

````markdown
```mermaid
%% Color Palette: Blue #0173B2, Orange #DE8F05, Teal #029E73, Purple #CC78BC, Brown #CA9161
%% All colors are color-blind friendly and meet WCAG AA contrast standards
flowchart TD
    A[User Request] --> B{Authentication?}
    B -->|Yes| C[Access Granted]
    B -->|No| D[Access Denied]

    style A fill:#0173B2,stroke:#000,color:#fff
    style B fill:#DE8F05,stroke:#000,color:#000
    style C fill:#029E73,stroke:#000,color:#fff
    style D fill:#CC78BC,stroke:#000,color:#000
```
````

**CRITICAL: Mermaid Syntax Rules**

Hugo's Mermaid renderer has strict syntax requirements:

1. **Comments**: Use `%% Comment %%` (NO curly braces)
2. **Text with special characters**: Quote text containing forward slashes, brackets, or special symbols

✅ **Good (correct Mermaid syntax)**:

````markdown
```mermaid
%% Color Palette: Blue #0173B2, Orange #DE8F05, Teal #029E73, Purple #CC78BC, Brown #CA9161 %%
flowchart LR
    A["Path: /admin"] --> B["Route: /api/v1/users"]
    C[Simple Text] --> D[Another Node]
```
````

❌ **Bad (syntax errors)**:

````markdown
```mermaid
%%{ Color Palette: ... }%% <!-- WRONG! Curly braces cause "syntax error in text" -->
flowchart LR
    A[/admin] --> B[/api/v1/users] <!-- WRONG! Unquoted forward slashes cause "syntax error in text" -->
```
````

**Rationale**:

- `%%{ }%%` is reserved for Mermaid directives (init config), not comments
- Forward slashes in unquoted bracket text break Mermaid's parser
- Quoting text containing special characters prevents parsing errors

### 4. Emoji Usage Convention

**Reference**: [Emoji Usage Convention](../formatting/emoji.md)

**Application to Hugo**: Selective use of semantic emojis to enhance document scannability.

**Applies to**: Both ayokoding-web and ose-platform-web content

**Allowed Usage**:

- Section markers (✅ Success, ❌ Error, ⚠️ Warning)
- Status indicators (🚀 Launch, 🔧 Maintenance, 📊 Analytics)
- Category icons (📚 Tutorial, 🎯 Goal, 💡 Tip)

**Example (ose-platform-web update)**:

```markdown
## Release Update 🚀

✅ **Completed Features**

- User authentication system
- Dashboard analytics

⚠️ **Known Issues**

- Search optimization in progress
```

**Forbidden**: Overuse, decorative emojis without semantic meaning

### 5. Timestamp Format Convention

**Reference**: [Timestamp Format Convention](../formatting/timestamp.md)

**Application to Hugo**: All timestamps MUST use ISO 8601 format with UTC+7 timezone.

**Format**: `YYYY-MM-DDTHH:MM:SS+07:00`

**Applies to**: All frontmatter date fields in both sites

**Example**:

```yaml
---
title: "Getting Started with Hugo"
date: 2025-12-07T14:30:00+07:00
lastmod: 2025-12-07T15:45:00+07:00
---
```

**Important**: Hugo's frontmatter parser requires this exact format. Do NOT omit the timezone offset.

### 6. Tutorial Convention

**Reference**: [Tutorial Convention](../tutorial/general.md)

**Application to Hugo**: Applies to learning content in **ayokoding-web only**.

**Scope**: `apps/ayokoding-web/content/id/belajar/` and `apps/ayokoding-web/content/en/learn/`

**Key Requirements**:

- Progressive scaffolding (build on previous knowledge)
- Hands-on elements (code examples, exercises)
- Visual aids (diagrams, screenshots, code blocks)
- Clear learning objectives
- Narrative flow with context

**Example (ayokoding-web tutorial structure)**:

```markdown
---
title: "Building Your First API with Node.js"
date: 2025-12-07T10:00:00+07:00
draft: false
description: "Step-by-step tutorial for creating a REST API"
weight: 10
tags: ["nodejs", "api", "tutorial"]
categories: ["learn"]
---

## What You'll Learn

By the end of this tutorial, you'll be able to:

- Create a basic Express.js server
- Define REST API endpoints
- Handle JSON requests and responses

## Prerequisites

Before starting, ensure you have:

- Node.js 18+ installed
- Basic JavaScript knowledge
- A code editor (VS Code recommended)

## Step 1: Project Setup

Let's start by creating a new project...
```

### 7. Tutorial Naming Convention

**Reference**: [Tutorial Naming Convention](../tutorial/naming.md)

**Application to Hugo**: Use standardized tutorial types in **ayokoding-web learning content only**.

**Scope**: ayokoding-web only (ose-platform-web does not use tutorials)

**Tutorial Types**:

- **Initial Setup** (0-5%) - Quick "Hello World" verification
- **Quick Start** (5-30%) - Learn enough to explore independently
- **Beginner** (0-60%) - Comprehensive foundation from scratch
- **Intermediate** (60-85%) - Professional-level expertise
- **Advanced** (85-95%) - Expert-level mastery
- **Cookbook** (Practical) - Day-to-day recipes and real-world problems

**Note**: Coverage percentages indicate depth/scope, NOT time required. See "No Time Estimates" convention below.

**Example (ayokoding-web file naming)**:

```
content/id/belajar/nodejs/
├── initial-setup.md           # Initial Setup tutorial
├── quick-start.md             # Quick Start tutorial
├── beginner-guide.md          # Beginner tutorial
└── cookbook/
    └── error-handling.md      # Cookbook recipe
```

### 8. No Time Estimates in Educational Content

**Reference**: [Content Quality Principles - No Time Estimates](../content/quality.md#no-time-estimates)

**Application to Hugo**: Do NOT include time estimates in educational/tutorial content.

**Scope**: ayokoding-web learning content (`content/en/learn/`, `content/id/belajar/`)

**Rationale**:

- Time estimates create artificial pressure on learners
- Everyone learns at different speeds
- Focus on WHAT learners accomplish, not HOW LONG it takes
- Makes content evergreen (no need to update time claims)

**Forbidden in Hugo Content**:

❌ **Avoid**:

```markdown
This tutorial takes 2-3 hours to complete.
Duration: 45 minutes
Learn this in 30 minutes.
```

✅ **Good**:

```markdown
By the end of this tutorial, you'll be able to...
Coverage: 60-85% of domain knowledge (intermediate depth)
```

**Exception - Coverage Percentages Allowed**:

Coverage percentages indicate **depth/scope**, not **time**, so they're allowed:

- ✅ "Coverage: 0-5%" (initial setup scope)
- ✅ "Coverage: 60-85%" (intermediate depth)

---

## Adapted Conventions

These conventions from `docs/` are modified for Hugo's specific requirements.

### 1. Indentation Convention

**Reference**: [Indentation Convention](../formatting/indentation.md)

**Adaptation for Hugo**:

- **YAML Frontmatter**: MUST use 2 spaces per indentation level (NOT tabs)
- **Markdown Content**: Standard markdown indentation (spaces or tabs acceptable)
- **Code Blocks**: Follow language-specific indentation (see convention doc)

**Why different from docs/?**

- docs/ uses standard markdown with space indentation (2 spaces per level)
- Hugo content is published web content, not Obsidian vault
- Standard markdown practices apply

**Example (correct indentation)**:

```yaml
---
title: "My Post"
tags:
  - nodejs # 2 spaces before dash
  - javascript # 2 spaces before dash
categories:
  - tutorials
---
Content starts here with standard markdown indentation.

- Bullet points use spaces or tabs (both acceptable)
- Nested bullets follow standard markdown
```

❌ **Incorrect (tabs in frontmatter)**:

```yaml
---
title: "My Post"
tags:
  - nodejs # TAB before dash - WRONG!
  - javascript
---
```

### 2. Linking Convention

**Reference**: [Linking Convention](../formatting/linking.md)

**Adaptation for Hugo**:

- **Internal Links**: Use absolute paths starting with `/` (e.g., `/learn/path`) WITHOUT `.md` extension
- **External Links**: Standard markdown `[text](url)`
- **Asset Links**: Reference `/images/` path (served from `static/`)

**Why different from docs/?**

- docs/ uses `.md` extensions for Obsidian compatibility
- Hugo generates URLs without `.md` extensions
- Using `.md` in Hugo links breaks in production builds

#### Internal Link Path Format

**CRITICAL RULE**: Always use **absolute paths** starting with `/` for internal content links. Never use relative paths (`./` or `../`).

**Why absolute paths?**

Hugo renders the same navigation content in different page contexts (sidebar, mobile menu, homepage). Relative links resolve differently depending on where they're rendered:

- From `/en/learn/` page: `./ai/` → `/en/learn/ai/` ✅
- From `/en/` homepage: `./ai/` → `/en/ai/` ❌ (broken)

Absolute paths work correctly from **any page context**.

**Correct (absolute paths)**:

```markdown
<!-- Hugo ref shortcode (recommended for validation) -->

Check out our [getting started guide]({{< ref "/learn/getting-started" >}})

<!-- Absolute path without .md (works in all contexts) -->

[Chat with PDF](/learn/ai/chat-with-pdf)
[Software Engineering](/learn/swe)
[About Us](/about)

<!-- External link (standard markdown) -->

Visit [Hugo Documentation](https://gohugo.io/documentation/)

<!-- Image from static/ directory -->

![Architecture Diagram](/images/architecture.png)
```

❌ **Incorrect (relative paths or .md extension)**:

```markdown
<!-- WRONG! Relative paths break in different rendering contexts -->

[Chat with PDF](./ai/chat-with-pdf/)
[Software Engineering](../swe/)
[Advanced Guide](../../advanced/)

<!-- WRONG! Using .md extension breaks in production -->

[Tutorial](/learn/tutorial.md)
[Guide](./guide.md)
```

**Language Prefix Handling**:

The approach depends on your Hugo configuration:

**For sites with `defaultContentLanguageInSubdir: true`** (like ayokoding-web and ose-platform-web):

- **INCLUDE language prefix** explicitly in internal links
- Both languages are served from subdirectories (`/en/`, `/id/`, etc.)
- Links should specify the target language explicitly

```markdown
✅ Correct: [Tutorial](/en/learn/nodejs)
✅ Correct: [Tutorial](/id/belajar/nodejs)
❌ Wrong: [Tutorial](/learn/nodejs) <!-- Missing language prefix -->
```

**For sites with `defaultContentLanguageInSubdir: false`**:

- Default language served at root (`/learn/nodejs`)
- Other languages in subdirectories (`/id/belajar/nodejs`)
- Omit prefix for default language links

**Using Hugo Shortcodes** (recommended for cross-language safety):

```markdown
{{< ref "/learn/nodejs" >}} <!-- Hugo handles language context automatically -->
{{< relref "/learn/nodejs" lang="id" >}} <!-- Explicit language targeting -->
```

**Verified**: Production ayokoding.com uses `/en/` prefix in all internal links. This is the correct approach for `defaultContentLanguageInSubdir: true` configuration.

### 3. File Naming Convention

**Reference**: [File Naming Convention](../meta/file-naming.md)

**Adaptation for Hugo**:

- **Content Files**: Use simple slugs or date-prefixed slugs (no prefix encoding)
- **Section Files**: Use `_index.md` for directory listings
- **URL Generation**: Hugo uses filename (minus extension) as URL slug

**Patterns**:

```
Hugo Content Naming Patterns:

1. Simple slug (most common):
   getting-started.md
   advanced-tutorial.md

2. Date-prefixed (blog posts):
   2025-12-07-release-update.md
   2025-11-15-feature-announcement.md

3. Section index:
   _index.md (lists content in directory)

4. Multi-language:
   about.id.md (Indonesian)
   about.en.md (English)
```

**Example (ayokoding-web structure)**:

```
content/
├── id/
│   ├── _index.md                      # Indonesian homepage
│   ├── belajar/
│   │   ├── _index.md                  # Learning section index
│   │   └── nodejs/
│   │       ├── _index.md              # Node.js topic index
│   │       ├── getting-started.md     # Simple slug
│   │       └── advanced-patterns.md   # Simple slug
└── en/
    └── learn/
        └── nodejs/
            └── getting-started.md     # English version
```

**Example (ose-platform-web structure)**:

```
content/
├── updates/
│   ├── _index.md                                 # Updates section index
│   ├── 2025-12-07-initial-release.md            # Date-prefixed
│   └── 2025-11-20-platform-announcement.md      # Date-prefixed
└── about.md                                      # Simple slug
```

### 4. Frontmatter Convention

**Format**: YAML (both sites use YAML, not TOML)

**Universal Required Fields**:

- `title` - Page title (string)
- `date` - Publication date (ISO 8601 with UTC+7)
- `draft` - Draft status (boolean)

**Common Optional Fields**:

- `description` - Page description (recommended 150-160 chars for SEO)
- `tags` - Content tags (array)
- `categories` - Content categories (array)
- `weight` - Page ordering (integer)

**Site-Specific Fields**: See site-specific convention documents

**Example (basic frontmatter)**:

```yaml
---
title: "Getting Started with TypeScript"
date: 2025-12-07T10:00:00+07:00
draft: false
description: "Learn TypeScript fundamentals and start building type-safe applications"
weight: 10
tags: ["typescript", "javascript", "tutorial"]
categories: ["learn"]
---
```

### 5. Date Format Convention

**Reference**: [Timestamp Format Convention](../formatting/timestamp.md)

**Adaptation for Hugo**: Same as inherited convention, but emphasized here due to critical importance.

**REQUIRED Format**: `YYYY-MM-DDTHH:MM:SS+07:00` (ISO 8601 with UTC+7)

**Hugo Frontmatter Fields Using This Format**:

- `date` - Publication date (required)
- `lastmod` - Last modification date
- `publishDate` - Future publish date
- `expiryDate` - Content expiration date

**Example**:

```yaml
---
title: "My Post"
date: 2025-12-07T14:30:00+07:00
lastmod: 2025-12-07T15:45:00+07:00
---
```

**Why This Matters**:

- Hugo's frontmatter parser expects ISO 8601 format
- Timezone is REQUIRED for accurate timestamps
- UTC+7 is Western Indonesian Time (WIB) - repository standard

---

## Hugo-Specific Conventions

These conventions are unique to Hugo static site generation and apply to both sites.

### 1. No Duplicate H1 Headings

**CRITICAL**: Hugo content markdown files MUST NOT include H1 headings (`# ...`) that duplicate the frontmatter `title` field.

**Why this matters**: Hugo themes (Hextra for ayokoding-web, PaperMod for ose-platform-web) automatically render the `title` field from frontmatter as the page heading (H1). When markdown content also includes an H1 heading, it creates duplicate heading display on the rendered page.

**Rule**: Content should start with introduction text or H2 headings (`## ...`). If an H1 is needed for structural reasons, it must be semantically different from the title.

**Applies to**: ALL Hugo content files in both ayokoding-web and ose-platform-web.

✅ **Good (no duplicate H1)**:

```markdown
---
title: "Beginner Tutorial - Elixir"
date: 2025-12-22T10:00:00+07:00
draft: false
---

This tutorial covers the fundamentals of Elixir programming...

## What You'll Learn

- Pattern matching
- Functional programming concepts
- Basic syntax

## Prerequisites

Before starting, ensure you have...
```

❌ **Bad (duplicate H1)**:

```markdown
---
title: "Beginner Tutorial - Elixir"
date: 2025-12-22T10:00:00+07:00
draft: false
---

# Beginner Tutorial - Elixir

This tutorial covers the fundamentals...
```

**Issue**: The title "Beginner Tutorial - Elixir" appears twice on the rendered page (once from frontmatter auto-rendering, once from markdown H1).

**Valid Use Case for H1** (semantically different from title):

```markdown
---
title: "Software Engineering Best Practices"
---

# Introduction to Code Quality

This section discusses foundational concepts...

# Design Patterns Overview

This section covers common patterns...
```

**Note**: While multiple H1s are technically allowed when semantically different from the title, most Hugo content should avoid H1s entirely and start with H2s.

### 2. Archetypes

**Definition**: Content templates used to generate new files with pre-populated frontmatter.

**Location**: `archetypes/` directory in each Hugo site

**Usage**: `hugo new content/path/to/file.md --kind archetype-name`

**Purpose**: Ensure consistent frontmatter across content types

**Site-Specific Archetypes**: Each site defines its own archetypes - see site-specific convention documents:

- [ayokoding-web archetypes](./ayokoding.md#archetypes)
- [ose-platform-web archetypes](./ose-platform.md#archetypes)

### 3. Shortcodes

**Definition**: Reusable content snippets that generate HTML dynamically.

**Hugo Built-in Shortcodes** (available in both sites):

- `{{< ref >}}` - Internal content reference
- `{{< relref >}}` - Relative content reference
- `{{< figure >}}` - Image with caption
- `{{< highlight >}}` - Syntax highlighting
- `{{< youtube >}}` - Embed YouTube video
- `{{< tweet >}}` - Embed tweet

**Theme-Specific Shortcodes**: Each theme provides additional shortcodes - see site-specific convention documents:

- [Hextra shortcodes (ayokoding-web)](./ayokoding.md#hextra-shortcodes)
- [PaperMod shortcodes (ose-platform-web)](./ose-platform.md#papermod-shortcodes)

**Example (using Hugo built-in shortcodes)**:

```markdown
{{< figure src="/images/dashboard.png" caption="OSE Platform Dashboard" >}}

Check out our [getting started guide]({{< ref "/updates/getting-started" >}})
```

**CRITICAL: Shortcode Delimiter Rules**

Hugo uses two delimiter types based on content processing needs:

1. **`{{< >}}`** - For shortcodes that output **HTML directly** (no Markdown processing)
2. **`{{% %}}`** - For shortcodes that contain **Markdown content** (requires Markdown processing)

**When to Use Each**:

✅ **Use `{{% %}}` for Markdown content**:

```markdown
{{% steps %}}

### Step 1: Install Dependencies

Run `npm install` to install required packages.

### Step 2: Configure Settings

Edit the configuration file...

{{% /steps %}}
```

✅ **Use `{{< >}}` for HTML content**:

```markdown
{{< figure src="/images/dashboard.png" caption="OSE Platform Dashboard" >}}

{{< ref "/learn/getting-started" >}}
```

❌ **Bad (wrong delimiter for Markdown content)**:

```markdown
{{< steps >}} <!-- WRONG! Displays as plain text instead of rendering -->

### Step 1: Install Dependencies

Run `npm install`

{{< /steps >}}
```

**Rationale**:

- `{{< >}}` treats inner content as raw HTML - Markdown won't be processed
- `{{% %}}` processes inner content as Markdown before rendering
- Using wrong delimiter causes content to display as plain text
- Theme shortcodes often require Markdown processing (steps, callouts, cards)

### 4. Taxonomy

**Definition**: Classification system for content (tags, categories, series).

**Universal Taxonomy** (both sites):

- **tags**: Granular topics (e.g., "nodejs", "api", "tutorial")
- **categories**: Broad content groupings (e.g., "learn", "updates")

**Site-Specific Taxonomy**: Each site defines specific category values - see site-specific convention documents:

- [ayokoding-web taxonomy](./ayokoding.md#taxonomy)
- [ose-platform-web taxonomy](./ose-platform.md#taxonomy)

**Example (generic usage)**:

```yaml
---
title: "Understanding Async/Await in JavaScript"
tags: ["javascript", "async", "promises", "tutorial"]
categories: ["learn"]
---
```

### 5. Asset Organization

**Static Assets Location**: `static/` directory (served at site root)

**Recommended Structure**:

```
static/
├── images/
│   ├── screenshots/
│   ├── diagrams/
│   ├── logos/
│   └── posts/
│       └── 2025/
│           └── 12/
│               └── post-specific-image.png
├── downloads/                # Downloadable files
└── fonts/                    # Custom fonts (if needed)
```

**Image References in Content**:

```markdown
<!-- Absolute path from static/ root -->

![Architecture Diagram](/images/diagrams/system-arch.png)

<!-- Using Hugo figure shortcode -->

{{< figure src="/images/screenshots/dashboard.png" alt="Dashboard View" caption="OSE Platform Dashboard" >}}
```

**Alt Text Requirement**: All images MUST have descriptive alt text for accessibility.

**Site-Specific Asset Organization**: Each site may have additional subdirectories - see site-specific convention documents.

### 6. Content Types

**Regular Content Files**: `file-name.md`

- Individual pages or posts
- Display full content
- Appear in lists and navigation

**Section Index Files**: `_index.md`

- List pages for a directory
- Can include intro content
- Generate taxonomy pages

**Example Structure**:

```
content/en/learn/
├── _index.md                           # Learning section index
├── nodejs/
│   ├── _index.md                       # Node.js topic index
│   ├── getting-started.md              # Regular content
│   └── advanced-patterns.md            # Regular content
└── typescript/
    ├── _index.md                       # TypeScript topic index
    └── basics.md                       # Regular content
```

**\\\_index.md vs Regular Content**:

```yaml
# _index.md (section index)
---
title: "Node.js Learning Resources"
description: "Comprehensive Node.js tutorials and guides"
---
Browse our Node.js learning materials below.
# regular file (e.g., getting-started.md)
---
title: "Getting Started with Node.js"
date: 2025-12-07T10:00:00+07:00
draft: false
---
This tutorial covers...
```

**Site-Specific Content Type Patterns**: Each site has specific rules for index files and content organization - see site-specific convention documents.

### 7. URL Structure

**Hugo URL Generation**:

- Filename (minus extension) becomes URL slug
- Directory structure reflects URL path
- Configured via `hugo.yaml` (permalink patterns)

**URL Pattern Examples**:

```
# ayokoding-web
content/id/belajar/nodejs/getting-started.md
→ URL: https://ayokoding.com/id/belajar/nodejs/getting-started

content/en/learn/typescript/basics.md
→ URL: https://ayokoding.com/en/learn/typescript/basics

# ose-platform-web
content/updates/2025-12-07-initial-release.md
→ URL: https://oseplatform.com/updates/2025-12-07-initial-release

content/about.md
→ URL: https://oseplatform.com/about
```

**Custom URLs** (using frontmatter):

```yaml
---
title: "About Us"
url: "/about/" # Override default URL
slug: "company-info" # Override slug only (keeps path)
---
```

**Site-Specific URL Patterns**: Each site may have custom permalink configurations - see site-specific convention documents.

---

## Content Validation Checklist

Before publishing Hugo content, verify:

- [ ] Frontmatter uses YAML format with 2-space indentation
- [ ] Date format is `YYYY-MM-DDTHH:MM:SS+07:00`
- [ ] Description length is 150-160 characters (if present)
- [ ] **No duplicate H1 headings** - Content does NOT include H1 (`# ...`) that duplicates frontmatter title
- [ ] Internal links use absolute paths without `.md` extension
- [ ] All images have descriptive alt text
- [ ] Mermaid diagrams use accessible color palette
- [ ] Tags and categories are properly formatted arrays
- [ ] Draft status is set correctly (`draft: true/false`)
- [ ] Assets are organized in appropriate `static/` subdirectories

**Site-Specific Validation**: Each site has additional validation requirements - see site-specific convention documents.

---

## References

**Inherited Conventions**:

- [Mathematical Notation Convention](../formatting/mathematical-notation.md)
- [Color Accessibility Convention](../formatting/color-accessibility.md)
- [Diagrams and Schema Convention](../formatting/diagrams.md)
- [Emoji Usage Convention](../formatting/emoji.md)
- [Timestamp Format Convention](../formatting/timestamp.md)
- [Tutorial Convention](../tutorial/general.md)
- [Tutorial Naming Convention](../tutorial/naming.md)
- [Content Quality Principles](../content/quality.md)

**Related Conventions**:

- [File Naming Convention](../meta/file-naming.md)
- [Linking Convention](../formatting/linking.md)
- [Indentation Convention](../formatting/indentation.md)

**Site-Specific Conventions**:

- [ayokoding-web Hugo Content Convention](./ayokoding.md)
- [ose-platform-web Hugo Content Convention](./ose-platform.md)

**External Resources**:

- [Hugo Documentation](https://gohugo.io/documentation/)
- [Hextra Theme Documentation](https://imfing.github.io/hextra/docs/)
- [PaperMod Theme Documentation](https://adityatelange.github.io/hugo-PaperMod/)

```

### ../../../governance/conventions/content/quality.md

```markdown
---
title: "Content Quality Principles"
description: Universal markdown content quality standards applicable to all repository markdown contexts
category: explanation
subcategory: conventions
tags:
  - content-quality
  - markdown
  - writing-standards
  - accessibility
  - documentation
created: 2025-12-07
updated: 2025-12-22
---

# Content Quality Principles

This convention establishes universal content quality standards for **ALL markdown content** in this repository.

## Principles Implemented/Respected

This convention implements the following core principles:

- **[Accessibility First](../../principles/content/accessibility-first.md)**: Requires alt text for images, proper heading hierarchy, WCAG AA color contrast, semantic HTML structure, and screen reader support. Accessibility is not optional - it's a baseline requirement for all content.

- **[No Time Estimates](../../principles/content/no-time-estimates.md)**: Explicitly forbids time-based framing ("takes 30 minutes", "2-3 weeks to complete"). Focus on outcomes and deliverables, not arbitrary time constraints that create pressure.

## Purpose

This convention establishes universal quality standards that apply to **all markdown content** in the repository. It ensures consistent writing quality, accessibility compliance, and professional presentation across documentation, Hugo sites, planning documents, and repository root files. These standards make content readable, maintainable, and accessible to all users including those using assistive technologies.

## Scope

These principles apply to markdown content in:

- **docs/** - Documentation (tutorials, how-to guides, reference, explanations)
- **Hugo sites** - ayokoding-web and ose-platform-web content
- **plans/** - Project planning documents
- **Repository root files** - README.md, CONTRIBUTING.md, SECURITY.md, etc.

**Universal Application**: Every markdown file in this repository should follow these quality principles, regardless of location or purpose.

```mermaid
%% Color Palette: Blue #0173B2, Orange #DE8F05, Teal #029E73, Purple #CC78BC, Brown #CA9161 %%
graph TD
    A[Content Quality Principles] --> B[Writing Style & Tone]
    A --> C[Heading Hierarchy]
    A --> D[Accessibility Standards]
    A --> E[Formatting Conventions]

    B --> B1[Active Voice]
    B --> B2[Professional Tone]
    B --> B3[Clarity & Conciseness]
    B --> B4[Audience Awareness]

    C --> C1[Single H1 Rule]
    C --> C2[Proper Nesting H2-H6]
    C --> C3[Descriptive Headings]
    C --> C4[Semantic Structure]

    D --> D1[Alt Text Required]
    D --> D2[Semantic HTML]
    D --> D3[ARIA Labels]
    D --> D4[Color Contrast]
    D --> D5[Screen Reader Support]

    E --> E1[Code Block Formatting]
    E --> E2[Text Formatting]
    E --> E3[List Formatting]
    E --> E4[Blockquotes & Callouts]
    E --> E5[Table Formatting]
    E --> E6[Line Length Guidelines]

    style A fill:#0173B2,stroke:#000,color:#fff
    style B fill:#DE8F05,stroke:#000,color:#000
    style C fill:#029E73,stroke:#000,color:#fff
    style D fill:#CC78BC,stroke:#000,color:#000
    style E fill:#CA9161,stroke:#000,color:#000
```

## Writing Style and Tone

### Active Voice

**Prefer active voice** over passive voice for clarity and directness.

✅ **Good (Active Voice)**:

```markdown
The agent validates the content against the convention.
```

❌ **Avoid (Passive Voice)**:

```markdown
The content is validated against the convention by the agent.
```

**Exception**: Passive voice is acceptable when:

- The actor is unknown or irrelevant
- Emphasizing the action over the actor
- Scientific or formal contexts require it

**Example of acceptable passive voice**:

```markdown
The configuration file is automatically generated during setup.
```

### Professional Tone

Maintain a **professional yet approachable** tone throughout all content.

**Key Principles**:

- Be respectful and inclusive
- Avoid slang, jargon (unless defined), or colloquialisms
- Use technical terms correctly and consistently
- Assume readers are intelligent but may lack context

✅ **Good (Professional Tone)**:

```markdown
To configure the authentication system, update the `auth.config.js` file
with your OAuth2 credentials. Refer to the [Authentication Guide](./auth-guide.md)
for detailed instructions.
```

❌ **Avoid (Too Casual)**:

```markdown
Just throw your OAuth2 stuff into `auth.config.js` and you're good to go!
```

❌ **Avoid (Too Formal/Stuffy)**:

```markdown
It is incumbent upon the developer to ensure proper configuration of the
aforementioned authentication system by means of modifying the designated
configuration file.
```

### Clarity and Conciseness

**Write clearly and concisely** - say what you mean with minimal words.

**Guidelines**:

- **One idea per sentence** - Complex ideas need multiple sentences
- **Short paragraphs** - 3-5 sentences maximum for web readability
- **Remove filler words** - "basically", "actually", "just", "simply"
- **Use concrete examples** - Show, don't just tell
- **Define acronyms** - First use should be spelled out

✅ **Good (Clear and Concise)**:

````markdown
The API returns a JSON response with status code 200 on success.

```json
{
  "status": "success",
  "data": { ... }
}
```
````

````

❌ **Avoid (Wordy and Vague)**:

```markdown
Basically, what happens is that when the API call actually completes
successfully, it will simply return back a JSON-formatted response that
contains the status code of 200, which indicates success.
````

### Audience Awareness

**Know your audience** and write for their experience level.

**For Beginners**:

- Explain concepts before using them
- Provide step-by-step instructions
- Include more examples and visuals
- Define technical terms

**For Intermediate/Advanced**:

- Assume foundational knowledge
- Focus on nuances and edge cases
- Provide links to prerequisites instead of explaining basics
- Use technical terminology appropriately

**Example (Tutorial for Beginners)**:

```markdown
## What is an API?

An API (Application Programming Interface) is a way for two programs to
communicate with each other. Think of it like a waiter in a restaurant:
you (the client) tell the waiter (the API) what you want, and the waiter
brings your order from the kitchen (the server).

In this tutorial, we'll build a simple API that responds to requests...
```

**Example (Reference for Advanced)**:

```markdown
## API Authentication

Endpoint authentication uses OAuth 2.0 authorization code flow with PKCE.
Token lifetime: 3600s (configurable via `TOKEN_EXPIRY` env var).
Refresh tokens supported with sliding expiration.
```

## Heading Hierarchy

### Single H1 Rule

**Every markdown file MUST have exactly ONE H1 heading** - the document title.

✅ **Correct (Single H1)**:

```markdown
# User Authentication Guide

## Overview

This guide covers authentication implementation.

## Setup

Follow these steps to set up authentication...
```

❌ **Incorrect (Multiple H1s)**:

```markdown
# User Authentication Guide

# Overview

This guide covers authentication implementation.

# Setup

Follow these steps...
```

**Why**: Single H1 provides clear document hierarchy for screen readers and SEO.

### Proper Heading Nesting

**Headings MUST follow semantic hierarchy** - don't skip levels.

✅ **Correct Nesting**:

```markdown
# Document Title (H1)

## Section (H2)

### Subsection (H3)

#### Detail (H4)

## Another Section (H2)

### Another Subsection (H3)
```

❌ **Incorrect (Skipped Levels)**:

```markdown
# Document Title (H1)

### Subsection (H3) <!-- WRONG! Skipped H2 -->

##### Detail (H5) <!-- WRONG! Skipped H4 -->
```

**Why**: Proper nesting creates logical structure for screen readers and document outlines.

### Descriptive Headings

**Headings MUST be descriptive and specific** - avoid vague titles.

✅ **Good (Descriptive)**:

```markdown
## Installing Dependencies with npm

## Configuring Authentication Settings

## Troubleshooting Database Connection Errors
```

❌ **Avoid (Vague)**:

```markdown
## Installation

## Configuration

## Troubleshooting
```

**Why**: Descriptive headings improve scannability and help readers find information quickly.

### Semantic Structure

**Use headings for structure, NOT for styling** - headings convey document hierarchy.

❌ **Incorrect (Using Heading for Emphasis)**:

```markdown
This is important content.

#### NOTICE: READ THIS CAREFULLY <!-- WRONG! This isn't a section heading -->

More content continues here...
```

✅ **Correct (Use Blockquote or Callout)**:

```markdown
This is important content.

> **NOTICE**: Read this carefully - this is a critical step.

More content continues here...
```

## Accessibility Standards

### Alt Text for Images

**ALL images MUST have descriptive alt text** for screen readers and accessibility.

✅ **Good Alt Text**:

```markdown
![Architecture diagram showing client-server communication flow with database](./images/architecture.png)

![Screenshot of the authentication form with username and password fields](./screenshots/login-form.png)
```

❌ **Bad Alt Text**:

```markdown
![image](./images/architecture.png) <!-- Too vague -->

![Screenshot](./screenshots/login-form.png) <!-- Not descriptive -->
```

**Alt Text Guidelines**:

- **Describe the content** - What does the image show?
- **Explain the purpose** - Why is this image here?
- **Keep it concise** - Aim for 1-2 sentences (screen readers)
- **Avoid "image of" or "picture of"** - It's implied
- **Include text from image** - If image contains important text

**Decorative Images**: Use empty alt text `![](image.png)` for purely decorative images that don't add information.

### Semantic HTML

**Use semantic HTML elements** appropriately in markdown.

✅ **Good (Semantic)**:

```markdown
## Section Title <!-- Semantic heading -->

> **Note**: This is a callout using blockquote <!-- Semantic blockquote -->

- Unordered list item <!-- Semantic list -->
- Another item

1. Ordered list item <!-- Semantic ordered list -->
2. Next step
```

❌ **Avoid (Non-Semantic)**:

```markdown
**Section Title** <!-- Using bold instead of heading -->

**Note**: This is a callout <!-- Just bold text, not semantic blockquote -->

**•** List item <!-- Manual bullets instead of list syntax -->
**•** Another item
```

**Why**: Semantic HTML provides meaning and structure for screen readers and assistive technologies.

### ARIA Labels and Accessibility Attributes

**Use ARIA labels when HTML alone is insufficient** for accessibility.

**When to use ARIA**:

- Complex interactive components
- Custom widgets or controls
- Additional context for screen readers
- Landmark regions in documentation

**Example (Using HTML with ARIA in documentation)**:

```html
<details>
  <summary aria-label="Expand to see advanced configuration options">Advanced Configuration</summary>
  <p>Advanced options content here...</p>
</details>
```

**Note**: In most cases, proper markdown structure provides sufficient accessibility. Use ARIA sparingly and only when semantic HTML is insufficient.

### Color Contrast

**Ensure sufficient color contrast** in diagrams and custom styling.

**Reference**: [Color Accessibility Convention](../formatting/color-accessibility.md)

**Requirements**:

- **Text contrast**: Minimum 4.5:1 ratio for normal text (WCAG AA)
- **Large text contrast**: Minimum 3:1 ratio for large text (≥18pt)
- **Non-text contrast**: Minimum 3:1 ratio for UI components and diagrams

**Use Accessible Color Palette** in all Mermaid diagrams:

- Blue: `#0173B2`
- Orange: `#DE8F05`
- Teal: `#029E73`
- Purple: `#CC78BC`
- Brown: `#CA9161`

**Never rely on color alone** to convey information - use text labels, patterns, or icons as well.

### Screen Reader Considerations

**Structure content for screen reader comprehension**.

**Best Practices**:

1. **Logical reading order** - Content flows naturally from top to bottom
2. **Descriptive link text** - Links describe destination, not "click here"
3. **Table headers** - Use header rows in tables for column identification
4. **List structure** - Use proper list syntax (not manual bullets)
5. **Heading hierarchy** - Proper H1-H6 nesting for document outline

✅ **Good (Descriptive Link Text)**:

```markdown
See the [Authentication Guide](./auth-guide.md) for setup instructions.
```

❌ **Avoid (Generic Link Text)**:

```markdown
For setup instructions, click [here](./auth-guide.md).
```

## Formatting Conventions

### Code Block Formatting

**Code blocks follow language-specific indentation standards**.

**JavaScript/TypeScript** (2 spaces):

```javascript
function authenticate(user) {
  if (user.isValid) {
    return generateToken(user);
  }
  return null;
}
```

**Python** (4 spaces):

```python
def authenticate(user):
    if user.is_valid:
        return generate_token(user)
    return None
```

**YAML** (2 spaces):

```yaml
config:
  authentication:
    enabled: true
    provider: oauth2
```

**Guidelines**:

- **Always specify language** - Use syntax highlighting (e.g., ` ```javascript `)
- **Keep code examples minimal** - Show only relevant code
- **Include context** - Brief explanation before code block
- **Use realistic examples** - Actual patterns, not abstract foo/bar

### Text Formatting

**Use text formatting purposefully and consistently**.

#### Bold Text

Use **bold** (`**text**`) for:

- **Key terms** on first mention
- **Important concepts** that need emphasis
- **UI element names** (buttons, menus)
- **Status labels** (Required, Optional)

✅ **Good Use of Bold**:

```markdown
The **authentication token** expires after 1 hour. Click the **Login** button
to sign in.
```

❌ **Overuse of Bold**:

```markdown
The **authentication token** **expires** after **1 hour**. **Click** the
**Login button** to **sign in**.
```

#### Italic Text

Use _italic_ (`*text*`) for:

- _Emphasis_ on specific words
- _Foreign terms_ or _Latin phrases_ (e.g., _et cetera_)
- _Variable names_ in prose (when not using code syntax)
- _Titles of books or publications_

✅ **Good Use of Italic**:

```markdown
The _environment_ variable must be set _before_ running the application.
```

#### Inline Code

Use inline code (`` `code` ``) for:

- `variable names`
- `function names`
- `file paths`
- `command names`
- `configuration keys`
- `HTTP status codes` (e.g., `200`, `404`)

✅ **Good Use of Inline Code**:

```markdown
Set the `API_KEY` environment variable in your `.env` file. Run the
`npm install` command to install dependencies.
```

#### Strikethrough

Use ~~strikethrough~~ (`~~text~~`) for:

- Deprecated features (with replacement noted)
- Corrections in changelog or updates

✅ **Good Use of Strikethrough**:

```markdown
~~Use `legacy-auth`~~ **Deprecated** - Use `oauth2-auth` instead.
```

### List Formatting

**Use appropriate list types** for content structure.

#### Unordered Lists

Use for:

- Items without specific order
- Feature lists
- Option lists
- Related items of equal importance

```markdown
Key features:

- User authentication
- Role-based access control
- Session management
- Audit logging
```

#### Ordered Lists

Use for:

- Sequential steps
- Ranked items
- Processes with specific order
- Prerequisites with dependencies

```markdown
Setup steps:

1. Install Node.js 18 or higher
2. Clone the repository
3. Run `npm install`
4. Configure environment variables
5. Start the development server
```

#### Nested Lists

**Use proper nesting** with 2-space or 4-space indentation:

```markdown
Project structure:

- src/
  - components/
    - auth/
      - Login.tsx
      - Signup.tsx
  - utils/
    - validation.ts
- tests/
  - unit/
  - integration/
```

#### Checklist Format

Use checkboxes for task lists:

```markdown
Setup checklist:

- [x] Install dependencies
- [x] Configure database
- [ ] Set up authentication
- [ ] Deploy to production
```

### Blockquotes and Callouts

**Use blockquotes for quotations and callouts**.

#### Simple Blockquote

```markdown
> "Good documentation is like good code - it should be clear, concise, and
> maintainable." — Anonymous Developer
```

#### Callout Boxes

Use blockquotes with emoji or labels for callouts:

```markdown
> **Note**: Configuration changes require server restart.

> ⚠️ **Warning**: Deleting this file will remove all user data permanently.

> ✅ **Success**: Your authentication is now properly configured.

> 💡 **Tip**: Use environment variables for sensitive configuration.
```

**Callout Types**:

- **Note** / 📝: General information
- **Warning** / ⚠️: Caution required
- **Success** / ✅: Confirmation or best practice
- **Tip** / 💡: Helpful suggestion
- **Important** / ❗: Critical information

### Table Formatting

**Use tables for structured data comparison**.

#### Basic Table

```markdown
| Feature         | Free Tier | Pro Tier  |
| --------------- | --------- | --------- |
| Users           | 5         | Unlimited |
| Storage         | 1 GB      | 100 GB    |
| API Calls/month | 1,000     | Unlimited |
| Support         | Community | Priority  |
```

**Table Guidelines**:

- **Align headers** with content using pipes and dashes
- **Keep cells concise** - Long content makes tables hard to read
- **Use header row** - First row should describe columns
- **Consider alternatives** - For complex data, use lists or separate sections

#### Table Alignment

```markdown
| Left Aligned | Center Aligned | Right Aligned |
| :----------- | :------------: | ------------: |
| Default      |    Centered    |       Numbers |
| Text         |      Text      |        123.45 |
```

**Alignment Syntax**:

- Left: `:---` (default)
- Center: `:---:`
- Right: `---:`

### Line Length and Readability

**Optimize line length for readability**.

**Guidelines**:

- **Prose text**: Aim for 80-100 characters per line (hard limit: 120)
- **Code blocks**: Follow language conventions (often 80-120 chars)
- **Tables**: May exceed line length (tables are wider by nature)
- **URLs**: Don't break URLs for line length

**Why**: Studies show ~80 characters per line optimizes reading speed and comprehension.

✅ **Good (Readable Line Length)**:

```markdown
Authentication tokens expire after 1 hour of inactivity. To extend the
session, the client must send a refresh token before expiration. Failed
refresh attempts result in automatic logout.
```

❌ **Avoid (Too Long)**:

```markdown
Authentication tokens expire after 1 hour of inactivity and to extend the session the client must send a refresh token before expiration otherwise failed refresh attempts will result in automatic logout and the user will need to log in again.
```

### Paragraph Structure

**Structure paragraphs for web readability**.

**Guidelines**:

- **One main idea per paragraph** - Split complex ideas into multiple paragraphs
- **3-5 sentences maximum** - Short paragraphs are easier to scan on screens
- **Topic sentence first** - Lead with the main point
- **Blank line between paragraphs** - Visual separation improves scannability

### No Time Estimates

**Do NOT include time estimates in educational or tutorial content.**

**Rationale**:

- Time estimates create artificial pressure on learners
- Everyone learns at different speeds
- Focus should be on WHAT learners accomplish, not HOW LONG it takes
- Makes content evergreen (no need to update time claims)
- Reduces anxiety and creates pressure-free learning environment

**Forbidden Time Estimates**:

❌ **Avoid (time-based claims)**:

```markdown
This tutorial takes 2-3 hours to complete.
Estimated time: 45 minutes
Duration: 1-2 hrs
You'll learn this in 30 minutes.
Time needed: 20 min
```

✅ **Good (focus on outcomes, not duration)**:

```markdown
By the end of this tutorial, you'll be able to...
This tutorial covers the fundamentals of...
You'll learn how to build a complete application.
Coverage: 60-85% of domain knowledge (intermediate depth)
```

**Exception - Coverage Percentages Allowed**:

Coverage percentages are allowed because they indicate **depth/scope**, not **time**:

- ✅ "Coverage: 0-5%" (indicates initial setup scope)
- ✅ "Coverage: 60-85%" (indicates intermediate depth)
- ✅ "Coverage: 85-95%" (indicates advanced depth)

**Where This Applies**:

- All tutorial content (`docs/tutorials/`)
- Educational content in Hugo sites (ayokoding-web learning content)
- How-to guides that teach concepts
- Reference documentation with learning components

**Where This Does NOT Apply**:

- Project planning documents (`plans/`) - can estimate implementation time
- Development task tracking - can estimate effort
- Meeting agendas - can allocate time slots

✅ **Good (Well-Structured Paragraphs)**:

```markdown
Authentication tokens provide secure access to protected resources. Each
token includes user identity, permissions, and expiration time.

Tokens expire after 1 hour of inactivity. Before expiration, clients can
request a new token using the refresh token endpoint. This extends the
session without requiring re-authentication.

Failed refresh attempts trigger automatic logout. The user must log in
again to continue. This security measure prevents unauthorized access
attempts.
```

❌ **Avoid (Wall of Text)**:

```markdown
Authentication tokens provide secure access to protected resources and
each token includes user identity, permissions, and expiration time and
tokens expire after 1 hour of inactivity so before expiration clients can
request a new token using the refresh token endpoint which extends the
session without requiring re-authentication but if refresh attempts fail
then automatic logout is triggered and the user must log in again to
continue which is a security measure that prevents unauthorized access
attempts.
```

## Quality Checklist

Before committing markdown content, verify:

- [ ] **Writing Style**
  - Active voice used (passive only when appropriate)
  - Professional yet approachable tone
  - Clear and concise language (no filler words)
  - Audience-appropriate complexity level

- [ ] **Heading Hierarchy**
  - Single H1 (document title)
  - Proper H2-H6 nesting (no skipped levels)
  - Descriptive heading text
  - Headings used for structure, not styling

- [ ] **Accessibility**
  - All images have descriptive alt text
  - Semantic HTML elements used correctly
  - Color not sole means of conveying information
  - Descriptive link text (not "click here")
  - Proper table headers and list structure

- [ ] **Formatting**
  - Code blocks specify language
  - Text formatting used purposefully (not overused)
  - Lists use proper markdown syntax
  - Blockquotes and callouts formatted consistently
  - Tables aligned and readable
  - Mermaid diagrams use correct comment syntax (`%%`, not `%%{ }%%`)

- [ ] **Readability**
  - Lines ≤80-100 characters (prose)
  - Paragraphs ≤3-5 sentences
  - Blank lines between paragraphs
  - Logical flow and structure

## Related Conventions

**Universal Conventions (apply to all markdown)**:

- [Mathematical Notation Convention](../formatting/mathematical-notation.md) - LaTeX in markdown
- [Color Accessibility Convention](../formatting/color-accessibility.md) - Accessible color palette for diagrams
- [Diagrams and Schema Convention](../formatting/diagrams.md) - Mermaid diagram standards (includes comment syntax requirements)
- [Emoji Usage Convention](../formatting/emoji.md) - Semantic emoji use

**Context-Specific Conventions**:

- [Hugo Content Convention - Shared](../hugo/shared.md) - Shared Hugo content standards
- [Hugo Content Convention - ayokoding](../hugo/ayokoding.md) - ayokoding-web specific standards
- [Hugo Content Convention - OSE Platform](../hugo/ose-platform.md) - ose-platform-web specific standards
- [File Naming Convention](../meta/file-naming.md) - File naming standards
- [Linking Convention](../formatting/linking.md) - Internal and external linking
- [Tutorial Convention](../tutorial/general.md) - Tutorial structure and pedagogy
- [Diátaxis Framework](../meta/diataxis-framework.md) - Documentation organization

## References

**Web Content Accessibility Guidelines (WCAG)**:

- [WCAG 2.1 Level AA](https://www.w3.org/WAI/WCAG21/quickref/)
- [WebAIM: Writing for Screen Readers](https://webaim.org/articles/screenreader/)
- [WebAIM: Contrast Checker](https://webaim.org/resources/contrastchecker/)

**Writing Guides**:

- [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
- [Google Developer Documentation Style Guide](https://developers.google.com/style)
- [The Chicago Manual of Style](https://www.chicagomanualofstyle.org/)

**Markdown References**:

- [CommonMark Spec](https://commonmark.org/)
- [GitHub Flavored Markdown](https://github.github.com/gfm/)

```