npm package: @mtldev514/retro-portfolio-maker
Description: A portfolio manager for multi-passionate creators with a soft spot for early 2000s aesthetics. Display your many projects with soul.
Author: Alex Catus
Latest version: 1.1.22

# @mtldev514/retro-portfolio-maker

[![npm version](https://img.shields.io/npm/v/@mtldev514/retro-portfolio-maker.svg)](https://www.npmjs.com/package/@mtldev514/retro-portfolio-maker)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
# 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:

```bash
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`:

```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](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

```bash
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](https://www.npmjs.com/package/@mtldev514/retro-portfolio-maker) | [GitHub](https://github.com/mtldev514/retro-portfolio-maker) | [Issues](https://github.com/mtldev514/retro-portfolio-maker/issues)

---

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