Hugo OSE Platform Development Skill

Purpose

This Skill provides guidance for creating and managing content on the oseplatform-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 oseplatform-web

• Writing about page content

• Managing landing page structure

• Configuring PaperMod frontmatter

• Understanding oseplatform-web specific patterns

Core Concepts

Site Overview

oseplatform-web (apps/oseplatform-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

• oseplatform-web: English-only with flat structure

Content Structure

apps/oseplatform-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. oseplatform-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

Contrast with ayokoding-web:

• ayokoding-web: MUST use absolute paths with language prefix (/en/ , /id/ )

• oseplatform-web: Absolute paths without language prefix (English-only)

Asset Organization

Location: apps/oseplatform-web/static/

Structure:

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

Image References:

Markdown image

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 oseplatform-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: oseplatform-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 (oseplatform-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 - oseplatform-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-oseplatform-web-content-maker

• Creates oseplatform-web content

• apps-oseplatform-web-content-checker

• Validates oseplatform-web content

• apps-oseplatform-web-deployer

• Deploys oseplatform-web

External Resources:

• PaperMod Official Documentation

• PaperMod GitHub Repository

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

Deployment Workflow

Deploy oseplatform-web to production using automated CI or the deployer agent.

Production Branch

Branch: prod-oseplatform-web

Purpose: Deployment-only branch that Vercel monitors Build System: Vercel (Hugo SSG with PaperMod theme)

Automated Deployment (Primary)

The test-and-deploy-oseplatform-web.yml GitHub Actions workflow handles routine deployment:

• Schedule: Runs at 6 AM and 6 PM WIB (UTC+7) every day

• Change detection: Diffs HEAD vs prod-oseplatform-web scoped to apps/oseplatform-web/ — skips build/deploy when nothing changed

• Build: Runs nx build oseplatform-web (Hugo extended build with PaperMod theme)

• Deploy: Force-pushes main to prod-oseplatform-web ; Vercel auto-builds

Manual trigger: From the GitHub Actions UI, trigger test-and-deploy-oseplatform-web.yml with force_deploy=true to deploy immediately regardless of changes.

Emergency / On-Demand Deployment

For immediate deployment outside the scheduled window:

git push origin main:prod-oseplatform-web --force

Or use the apps-oseplatform-web-deployer agent for a guided deployment.

Why Force Push

Safe for deployment branches:

• prod-oseplatform-web is deployment-only (no direct commits)

• Always want exact copy of main branch

• Trunk-based development: main is source of truth

References

Primary Convention: Hugo Content Convention - oseplatform-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