mcp-steroid / website

# MCP Steroid Website

This directory contains the Hugo source for the MCP Steroid website at https://mcp-steroid.jonnyzzz.com

> **Scope note:** the public website targets *end users* — install instructions,
> demo videos, the strategy page. Agent-facing design tenets live in
> [`docs/PHILOSOPHY.md`](../docs/PHILOSOPHY.md) (canonical, mirrored at
> runtime as `mcp-steroid://skill/design-philosophy`); contributor guidance
> for the plugin / prompts / tests lives in the per-folder `CLAUDE.md`
> and `AGENTS.md` files. Site copy and agent docs evolve on different
> cadences and to different audiences; don't conflate them.

## Architecture Overview

The website is built from this directory using Hugo and deployed via GitHub Pages.

**Deploys from the `website` branch, not `main`.** GitHub Pages (`.github/workflows/github-pages.yml`)
builds on a push to the long-lived **`website`** branch. `website` tracks `main` (advanced via
`git merge main → website`, normally often) but can deliberately lag it so website changes that depend
on an **unreleased** devrig binary — e.g. a new `install.sh`/`install.ps1` CLI contract — stay off the
live site until a matching GitHub release exists. A push to `main` does NOT deploy. The release process
advances `website` after publishing the release (`release/release-instructions.md` → "Stage 7c").
`website` is origin-only (never synced to `jb`).

### What is `mcp-steroid-public/`?

The `mcp-steroid-public/` directory is a **separate clone of the same repository** (`jonnyzzz/mcp-steroid`). This setup allows:

1. **Hugo builds to `mcp-steroid-public/docs/`** - Hugo outputs the static site here
2. **GitHub Pages serves from `docs/` folder** - The main repository's `docs/` folder is served at https://mcp-steroid.jonnyzzz.com
3. **Independent commits** - Website changes can be committed and pushed separately from plugin code changes

This is a common pattern for GitHub Pages deployment where the source (Hugo markdown) and output (HTML) live in different places but the same repository.

**Note:** The `mcp-steroid-public/` directory is ignored in `.gitignore` - it's a local clone used only for building and publishing.

## Requirements

- Docker and Docker Compose (for Hugo builds)
- JDK 25 (for the `:website-gen` Gradle task that generates `version.json` + `updatePlugins.xml`).
  No `gh`, `uv`, `jq`, or Python needed — `:website-gen` resolves the GitHub release itself over HTTP.

## Directory Structure

- `hugo.toml` - Hugo configuration with site parameters and featured videos
- `layouts/` - Hugo templates
- `static/` - Static assets (logo, CNAME) + the generated `version.json` / `updatePlugins.xml`
- `content/` - Content files (markdown)
- `mcp-steroid-public/` - Checkout of the public repository (build output destination)

`version.json` + `updatePlugins.xml` are generated by the `:website-gen` Kotlin module (repo root,
`website-gen/`), invoked from the Makefile's `update-config` as `./gradlew :website-gen:generateWebsite`.

## Adding Documentation Pages

Create new markdown docs under `content/docs/`. Front matter is optional, but recommended:

```markdown
---
title: "My Doc Page"
description: "Short summary shown on the docs landing page"
weight: 3
---

Intro paragraph...

## Overview

Details go here.
```

Notes:
- If `description` is missing, the docs list uses the first paragraph as a summary.
- Nested folders under `content/docs/` are supported; pages are listed by `weight` then title.

## Quick Start

```bash
# Start development server with live reload at http://localhost:1313
make dev

# Build the site to mcp-steroid-public/docs
make build
```

## Manual Setup (if needed)

```bash
# Explicitly clone the public repository
make setup
```

## Development

```bash
# Start development server with live reload at http://localhost:1313
make dev

# Build the site to mcp-steroid-public/docs
make build
```

## Publishing

After running `make build`, commit and push changes in `mcp-steroid-public/`:

```bash
cd mcp-steroid-public
git add docs README.md
git commit -m "Update website"
git push origin main
```

## Important Notes

1. **Version Sync**: The release version is read from `../VERSION` to find the GitHub release and update `hugo.toml`. The actual plugin version used in `updatePlugins.xml` comes from the JAR artifact's `plugin.xml` (e.g. `0.89.0-b8388824`), not from the VERSION file.

2. **Build Output Layout**: The website root lives under `mcp-steroid-public/docs`. Do not create a `public/` folder in this repository.

3. **Public Repository README**: The public repository at https://github.com/jonnyzzz/mcp-steroid contains issues and is user-facing. The README.md in that repository should be kept in sync with the website content and provide similar information about the plugin.

4. **What's New**: Add new entries to `[[params.whatsnew]]` in `hugo.toml` with `date` and `text` fields. Entries are displayed in the order they appear in the file (newest first).

5. **Featured Videos**: Update the `[[params.featuredVideos]]` entries in `hugo.toml` to change which videos appear on the homepage.

6. **CNAME**: The `static/CNAME` file configures the custom domain. Do not remove it.

7. **version.json**: Published at `/version.json` with the current version. Generated automatically during build.

8. **updatePlugins.xml**: Published at `/updatePlugins.xml` — IntelliJ custom plugin repository XML. Generated automatically during build by the `:website-gen` Kotlin module (`website-gen/`). It resolves the published GitHub release for `VERSION` over the REST API, downloads the `mcp-steroid-*.zip`, extracts the `ij-plugin-*.jar`, reads `META-INF/plugin.xml` for the exact plugin version + `since-build`, and renders the XML (DOM) with the change-notes from `release/notes/<version>.md`. The version + URL always match the actual artifact. The build fails if the release doesn't exist or URL/version validation fails — no fallbacks. Unit-tested offline in `WebsiteArtifactsTest` (the network is an injected seam).
   - **ZIP selection (since 0.100):** the GitHub release carries **two** zips — the plugin (`mcp-steroid-*.zip`) **and** the devrig CLI (`devrig-*.zip`). `:website-gen` matches `startsWith("mcp-steroid")` specifically; a bare `.zip` match would wrongly pick `devrig-*.zip`.

9. **Release Pages**: Releases are sorted by **numeric semantic version** (`partials/releases-sorted.html`, used by both `releases/list.html` and `releases/single.html`), newest first. Do **not** revert to `.ByTitle.Reverse` — that string-sorts titles, so `v0.95.0` outranks `v0.100` (`"9" > "1"`), which wrongly promotes an old release as "Latest" and flags the newest as obsolete. The latest release is the featured tile; older releases get an auto-generated obsolete banner (`single.html`). No manual obsolete banners in content files.
   - **Support footer:** the release-page sponsor footer and the homepage `#support` section both render `partials/support-section.html` (single source of truth). Release content `.md` files must **not** carry their own "Support the Project" block.

10. **Plugin Repository Promotion**: The custom plugin repository URL (`https://mcp-steroid.jonnyzzz.com/updatePlugins.xml`) is promoted on the releases list page and in the Download section of release pages (starting from 0.88.0).

## Homepage, branding & the devrig diagram (0.100+)

The site is **devrig-first**: the homepage hero leads with the `devrig` CLI (primary CTA),
the plugin is the stable secondary path. Conventions established for that:

- **Top-left brand badge.** `layouts/partials/nav.html` shows the MCP Steroid logo + name +
  a `devrig` gradient pill (`.nav-devrig` in `static/css/site.css`). Because the brand row is
  now wider, the **hamburger breakpoint was raised from 768px → 960px** (the `@media` block in
  `site.css` that flips `.nav-toggle`/`.nav-links`); below that the menu would overlap the badge.
  Verify nav fit at small widths before changing the brand.

- **The shared bridge diagram — `static/devrig-bridge.svg` is the single source.** It renders the
  "one bridge → every IDE at once" story (AI Agent → `devrig` (CLI + MCP) → IntelliJ IDEA /
  PyCharm / Managed backend). It is referenced as an `<img>` by **three** places — the homepage
  devrig section (`layouts/index.html`), the devrig docs page (`content/docs/devrig.md`), and the
  root **`README.md`** (relative `website/static/devrig-bridge.svg`, since GitHub strips inline
  `<svg>`). Edit the one file and all three update. Design constraints (from a 3-agent review):
  labels must stay legible at social-thumbnail size (titles 16–18px/700, subtitles ~12.5px,
  bright `#c7c4d6`), the panel needs a visible border (`#2e2e50` on `#1b1b34`) so it doesn't melt
  into the page gradient, and keep the `viewBox` tight (currently `0 0 780 280`).

- **Social/OG preview image.** `og:image` / `twitter:image` (in `layouts/_default/baseof.html`)
  point to **`static/og-devrig.png`** (1200×630) — a branded card built FROM the bridge diagram
  (MCP Steroid logo + name + `devrig` badge + slogan + the diagram). The older `og-image.png` /
  `og-image.svg` are **kept in place** but are no longer the active preview. To regenerate
  `og-devrig.png`: render an HTML composition with Playwright (`page.setContent(...)`,
  viewport 1200×630, `deviceScaleFactor: 2`, screenshot). **Gotcha:** `file://` images do NOT
  load under `setContent` — **inline** the SVG markup (read `pluginIcon.svg` + `devrig-bridge.svg`
  with `fs` and embed) rather than `<img src="file://…">`.

- **Footer copyright.** `layouts/partials/footer.html` carries `© 2025–2026 Eugene Petrenko`
  (name links to jonnyzzz.com) + the JetBrains-independence line (`.footer-copyright` in `site.css`).

- **Responsive checks.** Verify the homepage has no horizontal overflow at 320 / 390 / 768 / 1280px
  (Playwright: compare `document.documentElement.scrollWidth` to `innerWidth`). **Known pre-existing
  issue:** docs *content* pages (e.g. `/docs/devrig/`) overflow at ≤~600px — the `.docs-content`
  column is effectively fixed-width; this is independent of the marketing pages and not yet fixed.

## Workflow Summary

```
┌─────────────────────────────────────────────────────────────────┐
│  Main Repository (jonnyzzz/mcp-steroid)                         │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │  website/                                                    ││
│  │  ├── content/           ← Hugo source (markdown)             ││
│  │  ├── layouts/           ← Hugo templates                     ││
│  │  ├── hugo.toml          ← Configuration                      ││
│  │  └── mcp-steroid-public/ ← Clone of main repo (ignored)      ││
│  │      └── docs/          ← Hugo build output                  ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
                              │
                    make build │ (Hugo outputs to docs/)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  GitHub Pages serves from jonnyzzz/mcp-steroid:main/docs/       │
│  → https://mcp-steroid.jonnyzzz.com                             │
└─────────────────────────────────────────────────────────────────┘
```