Imported from David-Li0406/meta-skill-evloving (skill-flow/data/skills-refined-agentskillos-36k/skillsmp/apps-ose-platform-web-developing-content/SKILL.md). Install upstream with npx skills add David-Li0406/meta-skill-evloving --skill apps-ose-platform-web-developing-content. Copyright stays with the author.

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:

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

Plan content: Outline key points
Create file: Use date-prefixed filename
Write frontmatter: Title, date, tags, cover image
Write content: Clear, concise updates
Add visuals: Cover image, diagrams if needed
Validate: Check frontmatter, links, alt text
Publish: Set draft: false

About Page Maintenance

Keep current: Update as project evolves
Clear structure: Sections for vision, team, contact
No date needed: About page is timeless
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:

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