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 (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:

---
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

# 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)

# Explicitly clone the public repository
make setup

Development

# 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/:

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                             │
└─────────────────────────────────────────────────────────────────┘