Hub Articles Skill

A system for building educational articles that teach through interactive demonstration. These articles combine prose with inline widgets that let readers learn by doing.

When to use this skill: Creating technical tutorials, explainers, or educational content for the Academy that benefits from hands-on interaction rather than passive reading.

Phase 0: Understand the Teaching Goal

Do this first, every time.

  1. What concept are you teaching?
  2. Who is the audience? (Beginners? Technical users? General public?)
  3. What’s the “aha moment”? — The key insight the reader should walk away with
  4. Can this concept be demonstrated rather than just explained?

Output: A one-sentence summary of what the reader will understand after completing the article.

Phase 1: Narrative Outline

Plan the story before writing anything.

Articles should follow a narrative arc, not a feature list. A typical structure:

  1. Hook — Start with something familiar (what they already know)
  2. Problem — Reveal the gap or limitation they didn’t realise existed
  3. Demonstration — Let them experience the problem firsthand (widget)
  4. Solution — Introduce the concept that solves it
  5. Try It — Let them practice the solution (widget)
  6. Implications — Why this matters for their work
  7. Takeaway — Practical next steps

Outline Format

Create a simple outline with widget placement markers:

## Hook: What they already know
Prose introducing familiar context

## Problem: The gap they don't see
Prose setting up the issue
[WIDGET: Demonstrate the problem]

## Solution: The key insight
Prose explaining the concept
[WIDGET: Show solution in action]

## Practice: Let them try
[WIDGET: Interactive practice]

## Why it matters
Prose connecting to their real work

## Takeaway
3 practical things they can do immediately

Output: Complete narrative outline with widget placements marked.

Phase 2: Widget Design

Design each widget before implementing.

For each [WIDGET] marker in your outline, define:

### Widget: [Name]
**Purpose:** What this widget teaches (one sentence)
**Interaction:** What the user does (click, type, drag, toggle)
**Revelation:** What they discover through the interaction
**States:** Initial state → User action → Result state

Widget Design Principles

  1. One insight per widget — Don’t overload with multiple lessons
  2. Real interaction over simulation — Use actual clipboard, actual typing, actual results
  3. Immediate feedback — Show results as they interact, not after
  4. Progressive disclosure — Reveal explanations after they’ve tried it
  5. Mobile-friendly — Touch targets, responsive layouts, no hover-only interactions

See modules/01-widget-patterns.md for implementation patterns.

Output: Widget specifications for each interactive element.

Phase 3: Prose Writing

Write for your specific audience.

Know Your Reader

Audience Vocabulary Sentence Length Metaphors
Beginners (“normies”) Everyday words, no jargon Short, direct Familiar objects
Technical users Some technical terms okay Can be longer Industry concepts
Mixed Define terms on first use Varied Both types

Prose Guidelines

  1. Lead with what they know — Start from familiar ground before introducing new concepts
  2. Avoid jargon walls — If you must use a technical term, explain it immediately
  3. Short paragraphs — 2-4 sentences max. White space is your friend.
  4. Active voice — “Markdown uses symbols” not “Symbols are used by Markdown”
  5. Second person — “You” not “the user” or “one”

Phrases to Avoid

Instead of Use
“Heavy lifting” “Does a lot of work” or just explain what it does
“Under the hood” “Behind the scenes” or explain directly
“Leverage” “Use”
“Robust” Say what makes it strong
“Seamlessly” Describe the actual experience
“Paradigm” “Approach” or “way of thinking”
“Utilize” “Use”

For tone guidance, see ../hub-designer/modules/06-tone-of-voice.md.

Output: Complete prose draft with widget placeholders.

Phase 4: Widget Implementation

Build widgets using vanilla JavaScript patterns.

Technical Approach

File Structure

Articles live in /_articles/ and use the article layout:

---
layout: article
title: "Your Title Here"
description: "One-line summary"
date: 2026-01-21
author: "Peregian Digital Hub"
tags: ["Category", "Topic"]
back_link: "/academy/"
back_text: "Academy"
---

Layout Breakout Classes

Article content sits in a narrow reading column (max-w-3xl). Use these classes to break out for widgets and visualizations:

Class Behavior
.full-width Full viewport width with padding (good for colored sections)
.full-width-flush Full viewport width, no padding (edge-to-edge images)
.wide Wider than text column, scales with screen size

Examples:

<!-- Full-width section with background -->
<div class="full-width bg-base-100 py-12">
    <div class="max-w-6xl mx-auto">
        <!-- Widget content centered -->
    </div>
</div>

<!-- Edge-to-edge image -->
<div class="full-width-flush">
    <img src="..." alt="..." class="w-full">
</div>

<!-- Wider chart/diagram -->
<div class="wide">
    <!-- Needs more room than text column -->
</div>

Implementation Order

  1. Write all prose and HTML structure
  2. Add CSS in a <style> block at the end
  3. Add JS in a <script> block after the styles
  4. Test each widget independently
  5. Test the full narrative flow

See modules/01-widget-patterns.md for code patterns. See snippets/ for copy-paste widget templates.

Output: Complete article with working widgets.

Phase 5: Polish

Review against these checklists.

Prose Checklist

Widget Checklist

Visual Checklist

Brand Checklist

For colours, typography, and brand application, see ../hub-designer/modules/04-brand-system.md.

Key colours for articles:

Module Index

Module Purpose
modules/01-widget-patterns.md Widget types, state management, JS patterns
modules/02-article-structure.md Front matter, sections, layout features
modules/03-prose-guidelines.md Writing for different audiences

Snippet Index

Snippet Use Case
snippets/copy-paste-demo.html Before/after clipboard demonstration
snippets/toggle-view.html Raw/rendered toggle widget
snippets/live-editor.html Real-time input/output editor
snippets/tooltip-mockup.html Hover-reveal information display

Cross-References to Hub Designer

These hub-designer modules apply to articles:

Module Relevant For
../hub-designer/modules/04-brand-system.md Colours, typography, contrast rules
../hub-designer/modules/06-tone-of-voice.md Brand voice and language style

Example: Teaching Workflow

Here’s how the phases come together:

Phase 0: “Teaching beginners why Markdown matters when working with AI”

Phase 1 Outline:

  1. Hook: You format documents to organise information
  2. Problem: That formatting disappears when you paste into AI
  3. Demo: [WIDGET: Copy formatted text, see it degrade]
  4. Solution: Markdown encodes structure in plain text
  5. Show: [WIDGET: Toggle between raw/rendered]
  6. Practice: [WIDGET: Live Markdown editor]
  7. Proof: [WIDGET: Copy Markdown, see it survive]
  8. Implications: How this changes AI workflows
  9. Takeaway: Three symbols to learn today

Phase 2 Widgets:

Phase 3 Prose: Written for “normies” — no jargon, short sentences, familiar metaphors

Phase 4 Implementation: Vanilla JS, embedded styles, progressive enhancement

Phase 5 Polish: Reviewed against all checklists

Critical Rules

  1. Demonstrate, don’t just explain. If readers can experience the concept, they’ll remember it.

  2. One insight per widget. Don’t make widgets do too much.

  3. Write for your actual audience. “Normies” and developers need different language.

  4. Real interactions over simulations. Use the actual clipboard, actual typing, actual results.

  5. Test the narrative flow. The article should feel like a journey, not a reference manual.