static-spa-conversion

Q: How do I install static-spa-conversion?

Run npx skills add https://github.com/kevintsai1202/teaching-site-skills --skill static-spa-conversion in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/static-spa-conversion/ (personal) or .claude/skills/static-spa-conversion/ (project).

by kevintsai1202Marketing & SEO

Use this skill when you have structured course content (or any chapter-based dataset) in markdown form and need to turn it into a working interactive website — without picking a framework, without a build step. Triggers on phrases like "做成網頁", "轉成 SPA", "course-data.js", "render 函式", "把講義變網頁", "static site from markdown", "vanilla JS site", "no-framework site", "single-page app from markdown". The output is a vanilla HTML + JS single-page app that opens with npx serve and persists state in localStorage. Always invoke AFTER course-content-authoring (content stable), BEFORE static-spa-interactions (this skill produces the scaffold; interactions adorn it).

Installs: 65
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/kevintsai1202/teaching-site-skills --skill static-spa-conversion

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads static-spa-conversion automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Static SPA Conversion

Schema authority: all window.COURSE field names come from _shared/domain-primitives.md. When the schema example below diverges from that file, that file wins.

Starter templates (copy these, don't re-derive):

templates/index.html — scaffold shell with render pipeline skeleton

templates/course-data.template.js — empty schema example with TODO markers for every primitive

../teaching-site-design-system/templates/tokens.css — paste into <style> block, or copy as style.css next to index.html

Reference implementation: d:/GitHub/ai-workshop/index.html (4125 lines, fully populated). Use as visual + render-pattern reference; do not copy course-specific content from it.

Filename convention (English-first): course-package/, day{n}/outline.md, day{n}/content.md, materials/, overview.md. Legacy Chinese names (完整課程包/, 課程大綱.md, 教學素材/, etc.) are deprecated — see _shared/domain-primitives.md §0 for full mapping.

This skill turns chapter-based markdown content into a working single-page app. The architectural commitments are deliberate and worth understanding before you start.

The Three Architectural Commitments

Vanilla HTML + JS, no framework, no bundler. No React, no Vite, no TypeScript build. Why: course websites have multi-year lifespans and are often handed to non-developer instructors. A .html you can open and edit beats a node_modules graveyard every time. Also: the content is the value, not the tech.
Data and rendering live in different files. A course-data.js holds everything the course is as a single JS object (window.COURSE). An index.html holds how the course is shown. Instructors editing tomorrow's lesson never need to touch HTML.
localStorage for persistence, no backend. Progress, theme, zoom — all client-side. Easier hosting, no privacy headaches. The cost: state is per-browser. Accept it.

Standard File Layout

project-root/
├── index.html              ← the single SPA (CSS + JS inline; ~3000 lines is normal)
├── course-data.js          ← window.COURSE = { ... }
├── instructor-data.js      ← optional: window.INSTRUCTOR (if scraped/external)
├── tools-data.js           ← optional: window.TOOLS (if showcasing tools)
├── package.json            ← just `{"scripts": {"serve": "npx serve ."}}` and scraping tooling
├── assets/                 ← images, illustrations
└── course-package/             ← markdown source (read-only from SPA's perspective)
    └── materials/           ← files linked from the SPA via getMaterialUrl()

index.html includes data files via plain <script src="course-data.js"></script> — no module imports, no fetch. The browser loads them in order, populating window.COURSE before init() runs.

The `window.COURSE` Schema

The single most important artifact. Design it carefully — every render function depends on it. Standard shape:

window.COURSE = {
  meta: {                              // top-level course metadata
    title: '...',
    audience: '...',
    hoursTotal: 24,
    days: [                            // index drives sidebar chapter list
      { id: 'day1', title: 'Day 1: ...', hours: 6, schedule: '...' },
      ...
    ],
    classroom: { name: '...', mapUrl: '...' }
  },
  sharedCase: { /* persistent fictional scenario */ },
  day1: {
    hero: { title, lead, illustration },
    units: [
      {
        id: 'u-1',                     // stable, never renamed
        title: '...',
        timeRange: '14:00–14:50',
        goals: [...],                  // learning outcomes
        tasks: [                       // ← these IDs are localStorage keys
          { id: 'd1-u1-t1', text: '...', done: false }
        ],
        prompts: [                     // optional: copyable templates
          { id: '...', title: '...', body: '...' }
        ],
        materials: [                   // optional: per-unit material refs
          { id: '...', name: '...', type: 'PDF 文件' }
        ],
        illustrations: [               // 1–3 entries, see Stage 5 Coverage Floor
          { name: 'day1-u1-hero.png',  kind: 'hero',    alt: '...', spec: '...' },
          { name: 'day1-u1-flow.svg',  kind: 'diagram', alt: '...', spec: '...' }
        ]
        // legacy single `illustration: 'day1-u1.png'` still accepted; treat as
        // illustrations: [{ name, kind: 'hero' }] and migrate when convenient
      },
      ...
    ]
  },
  day2: { /* same shape */ },
  ...
  materials: [                         // cross-day material index for the "all materials" tab
    { id: 'm-1', name: '...', type: '...', desc: '...' }
  ],
  quiz: [                              // optional: end-of-course assessment
    { id: 'q1', question: '...', options: [...], answer: 0, sourceUnit: 'day1.u-2' }
  ]
};

The Render Pipeline

index.html is one big <script> at the bottom. Its shape:

// 1. Utilities (top, ~50 lines)
const el = (tag, attrs, children) => { /* tiny DOM helper */ };
const store = {
  load() { /* read localStorage */ },
  save(state) { /* write localStorage */ },
  reset() { /* clear */ }
};

// 2. Render functions, each takes data → returns/appends DOM
function renderOverview(meta) { ... }
function renderSharedCase(case_) { ... }
function renderDay(day) { ... }
function renderUnit(unit, dayId) { ... }
function renderMaterials(materials) { ... }
function renderToolbox(tools) { ... }    // optional
function renderQuiz(quiz) { ... }        // optional

// 3. Sidebar + scrollspy + theme — see static-spa-interactions

// 4. Entry point
function init() {
  renderOverview(window.COURSE.meta);
  renderSharedCase(window.COURSE.sharedCase);
  for (const dayKey of ['day1', 'day2', 'day3', 'day4']) {
    renderDay(window.COURSE[dayKey]);
  }
  renderMaterials(window.COURSE.materials);
  renderQuiz(window.COURSE.quiz);
  // ... then interactivity wiring (see static-spa-interactions)
}
document.addEventListener('DOMContentLoaded', init);

Keep each render function pure: it receives data, it produces DOM. No reading from globals beyond its parameter. This makes adding a new section trivial.

The Material URL Router (`getMaterialUrl`)

The trickiest piece. The SPA needs to map a material's name and type to a real URL on disk. The router lives near the top of the script section:

function getMaterialUrl(name, type) {
  const base = 'course-package/materials';
  if (type === 'PDF 文件') {
    // PDFs trigger download instead of inline view
    if (name.includes('員工差勤')) return `${base}/pdf/員工差勤辦法.pdf`;
    if (name.includes('客訴SOP')) return `${base}/pdf/客訴處理SOP.pdf`;
    // ... one rule per PDF
    return null;  // unknown PDF → caller hides the link
  }
  // Other types open in new tab
  if (name.includes('FAQ')) return `${base}/FAQ官方版.md`;
  if (name.includes('差勤')) return `${base}/員工差勤辦法.md`;
  // ...
}

The three-place sync rule — when adding a material, update all of:

Drop the file into course-package/materials/
Add an entry to course-data.js:materials[] (and any unit's materials[])
Add the name.includes(...) rule to getMaterialUrl()

Forgetting any one breaks the link. Consider adding a CI check that diffs filesystem vs. data vs. router.

The Task ID Lifecycle

// Save
function toggleTask(taskId) {
  const state = store.load();
  state.tasks[taskId] = !state.tasks[taskId];
  store.save(state);
  // re-render checkbox only, not whole page
}

// Load on render
function renderTask(task) {
  const state = store.load();
  const checked = !!state.tasks[task.id];
  return el('label', {}, [
    el('input', { type: 'checkbox', checked, onchange: () => toggleTask(task.id) }),
    task.text
  ]);
}

Never change task.id once published. The localStorage key tasks[task.id] is what survives across visits. Renaming wipes progress for every student.

Local Development

# Required: file:// blocks localStorage in Chrome — always serve via HTTP
npx serve .
# → http://localhost:3000

Add this to package.json:

{
  "scripts": {
    "serve": "npx serve ."
  }
}

Mention this prominently in any README. Double-clicking index.html produces a confusing "my progress doesn't save" bug that wastes hours.

Migration: Markdown → course-data.js

When porting an existing .md outline + content to course-data.js:

Parse the outline first to get the day/unit skeleton.
For each unit's content .md, extract tasks, prompts, materials references using grep-style passes (look for the marker patterns from course-content-authoring).
Generate course-data.js as one big object literal. Don't try to make it pretty programmatically — let prettier/eslint format it, or just leave it as-is.
Manually review: every unit ID in markdown should exist in course-data.js; the day count and hours should match meta.

When This Skill Hands Off

Tell the user:

"SPA scaffold is live. Run npm run serve and open http://localhost:3000."
"Next: invoke static-spa-interactions for progress persistence, sidebar, theme, RWD."
"Don't rename course-data.js paths or task IDs from this point — students' localStorage depends on them."

FAQ

What does the static-spa-conversion skill do?

How do I install static-spa-conversion?

Run npx skills add https://github.com/kevintsai1202/teaching-site-skills --skill static-spa-conversion in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/static-spa-conversion/ (personal) or .claude/skills/static-spa-conversion/ (project).

Which AI agents can use static-spa-conversion?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is static-spa-conversion safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains static-spa-conversion?

It is published by kevintsai1202 in kevintsai1202/teaching-site-skills. It has 65 recorded installs.