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

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

Minimal frontmatter - PaperMod has fewer required fields than Hextra.

Recommended Fields

---
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:

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

Metadata Display:

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

Search & SEO:

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

Cover Image:

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:

# 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:

---
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:

---
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:

# 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 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

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

User preference: Stored in localStorage, persists across sessions.

Social Sharing

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

Per-page control:

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

Home Page Configuration

# 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

# 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

# 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

# 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

Related Conventions:

• Hugo Content Shared - Shared Hugo patterns
• Content Quality Principles - 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
• PaperMod GitHub Repository

---

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

# 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

# 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

Related Conventions:

• Hugo Content Shared - Shared Hugo patterns
• Content Quality Principles - Universal quality standards

Related Skills:

• apps__ayokoding-web__developing-content

  - Comparison with ayokoding-web patterns

• docs__creating-accessible-diagrams

  - Accessible diagrams for technical content