@mtldev514/retro-portfolio-maker

A portfolio engine for creators who want to own their work on the web.

Why This Exists

The internet was built for sharing what you create. You shouldn't need a corporate platform to display your art, music, code, photography, or writing. Your portfolio should be yours — hosted where you choose, designed how you like, updated without asking permission.

This engine lets you build a portfolio that:

• Hosted anywhere you want — GitHub Pages, Netlify, Vercel, any static host. No server required
• Updates with a git push — edit locally, push, done
• Stays yours forever — plain files you own, not rows in someone else's database
• Looks however you want — 8 built-in views, or create your own from scratch

You keep only your data. The engine handles everything else.

Quick Start

# Create your portfolio
npx @mtldev514/retro-portfolio-maker init my-portfolio
cd my-portfolio && npm install

# Launch locally
npm start
# Site:  http://localhost:8000
# Admin: http://localhost:8000/admin.html

Use the admin panel to add your content — upload images, write descriptions, manage translations. When you're happy:

npm run build
git add . && git commit -m "update portfolio"
git push   # GitHub Actions deploys to Pages automatically

That's it. Your portfolio is live.

How It Works

You edit data locally          The engine builds a static site       Any static host serves it
┌──────────────────┐           ┌──────────────────────────┐          ┌──────────────┐
│  config/         │           │                          │          │              │
│  data/           │──build──▶ │  dist/  (HTML/CSS/JS)    │──push──▶ │  yoursite.io │
│  lang/           │           │                          │          │              │
│  styles/         │           └──────────────────────────┘          └──────────────┘
└──────────────────┘

• config/ — site settings, categories, languages, media types
• data/ — your content (paintings, music, projects, whatever you create)
• lang/ — translations (add as many languages as you need)
• styles/ — themes (CSS files + design token overrides)

No engine code in your repo. Just your data.

Features

• Full translation system — write your content in multiple languages. Visitors switch languages instantly. Every field (titles, descriptions, categories) supports multilingual values. Your content is accessible to everyone
• Built-in audio player — music portfolios get a Winamp-style player with playlists, track switching, and play controls baked into the gallery. Click a track, it plays
• Image-first display — image cards let the photo take the entire card space. No title, subtitle, or metadata cluttering the visual. Details live in the detail view where they belong
• Schema-driven navigation — categories, filters, detail views, and routing are generated from your data. Add a new category in config/categories.json and it shows up everywhere — filter bar, gallery, detail pages

Views

A view is how your portfolio looks and feels. Pick one in config/app.json:

{ "view": "retro" }

| View | Style | Best for | |------|-------|----------| | retro | DOS/terminal with CRT effects | Nostalgia, dev portfolios | | modern | Dark editorial | Photography, design | | aurora | Airy and light | Art, illustration | | pastel | Soft magazine layout | Mixed media | | blueprint | Technical wireframe | Architecture, engineering | | zine | 70s editorial scroll | Editorial, long-form | | terminal | Green phosphor monitor | Code, writing | | atelier | Art studio pinboard | Fine art, crafts |

Or build your own view from scratch. You get the engine's data loading, i18n, audio player, and admin panel for free. You control everything visual — HTML, CSS, JS, Canvas, WebGL, whatever you want. See VIEWS.md for the guide.

Commands

| Command | What it does | |---------|-------------| | npm start | Dev server + admin panel together | | npm run build | Generate static site in dist/ | | npm run dev | Dev server only (port 8000) | | npm run admin | Admin API only (port 5001) | | npm run validate | Check config and data files | | npx retro-portfolio sync | Update templates after engine update |

Updating

npm update @mtldev514/retro-portfolio-maker
npx retro-portfolio sync   # adds new files, never overwrites your data
npm run build

Deployment

The output is a static dist/ folder. Host it anywhere.

GitHub Pages

The init command creates a deploy workflow. Push to main and it builds + deploys automatically.

1. Go to repo Settings > Pages > Source: GitHub Actions
2. Push your code
3. Done

Netlify / Vercel / Any Static Host

Build command: npm run build | Publish directory: dist

Prerequisites

Node.js >= 18

Links

• NPM | GitHub | Issues

Made for creators who believe the internet is for sharing what you make.