cubesite

Adopt it

Ten minutes for a repo with nothing, less for one that already has a site.

A repo with no site

  1. Scaffold

    From a cubesite checkout, pointed at the project:

    node scripts/scaffold.mjs ../mcp-actual

    This writes site/ and .github/workflows/pages.yml. It never overwrites a file it does not own, so it is safe to re-run.

  2. Fill in the TODOs

    Three in site/src/_data/site.js (tagline, description, and the optional npm/docker links), and the rest in site/src/index.njk: what it does, three capabilities, and the shortest command that gets someone running. 

    cd site && npm install && npm run dev

  3. Commit the lockfile too

    The workflow runs npm ci, which needs site/package-lock.json in the repo. 

    git add site .github/workflows/pages.yml
git commit -m "Add a project site"

  4. Turn Pages on

    Settings → Pages → Source: GitHub Actions. This is the one step no script does for you — the workflow cannot enable the feature it deploys to. Push, and the site is live at cubicecho.github.io/<repo>/.

  5. Point the repo at it

    Set the repo's Website field to the Pages URL, link it from the first lines of the README, and add the project to cubicecho.com.

A repo that already has a site

Don't re-scaffold it. Sync the parts cubesite owns and leave your pages alone:

node scripts/scaffold.mjs ../mcp-router --theme

That writes four files, overwriting whatever was there:

  • site/src/css/cubesite.css — the shared theme
  • site/src/_includes/mark.njk — the inline mark
  • site/src/assets/favicon.svg and logo.svg

Then, by hand:

  • Load cubesite.css before your own stylesheet, and cut from yours everything the theme now covers — what is left is the project's own, and it should be short.
  • Replace the emoji in the header with {% include "mark.njk" %}, and give the wordmark the markup the theme expects — see template/src/_includes/base.njk.
  • Swap your pages.yml for the canonical one if yours has drifted from it.

What a project site is

One page, usually: the name, the one-line pitch, what it does, how to run it, and links out. Anything longer belongs in the README — the site points at the README, not the other way round. Repos with genuinely more to say (mcp-router, mcp-skills-manager) add get-started and docs pages on the same layout. That is the ceiling, not the floor.

The floor is worth stating plainly, because it is the whole point: a library with three sentences of description and an install line still gets a site. It costs one file and it is the difference between a link that shows someone what this is and a link that shows them a repo.