How to add a guide — ScriptKitty Badge Tutorials

// guides are contributed by pull request This site is open source. To add a guide, open a pull request against skickar/catbadge.online: fork the repo, add your files on a branch, and open the PR. A maintainer reviews it and merges — the guide goes live on the next build. You don't push straight to the site.

Copy the template

In your fork, cp _template.html my-slug.html and write it. All styling is already wired — use the callout, figure.shot, and ptable blocks shown in the template.

Add one JSON entry

Drop a single object into tutorials.json under tutorials (annotated below). This is what makes the card appear on the index.

Open a pull request

Commit my-slug.html and the tutorials.json change on a branch and open a PR. Once a maintainer merges it, the index shows the card on the next build.

// how it fits together The index page reads tutorials.json at load and builds the cards and filter chips from it. Your guide HTML is a page it links to. The JSON entry is what registers a guide; the HTML holds the content.

Step 2, up close: the JSON entry

Add this object to the tutorials array in tutorials.json. Newest-first ordering is automatic (by updated).

{
  "id": "wled-ear-effects",
  "title": "Drive the ear NeoPixels with WLEDkitty",
  "summary": "One-to-two sentence teaser shown on the index card.",
  "tags": ["badge", "wledkitty"],
  "difficulty": "beginner",
  "minutes": 10,
  "updated": "2026-08-02",
  "author": "Retia",
  "url": "wled-ear-effects.html"
}

id *Unique slug. Convention: match your filename (minus .html).

title *Shown as the card heading and the browser tab.

summary *The teaser under the title on the index card. One or two sentences.

tags *Array of tag ids that must exist in the tag registry (next section). These drive filtering and the cross-link to firmware.

difficultyFree text — e.g. beginner, intermediate. Shown in the card's right column.

minutesRough read/do time, shown as ~N min.

updated *YYYY-MM-DD. Sorts the list — newest first.

url *The guide's HTML filename, relative to tutorials/.

* required · the rest are optional but nice.

How tags link everything

Tags are the glue. Every tag you use must be declared once in the tags registry at the top of tutorials.json. A tag entry looks like this:

"bit-pirate": {
  "label": "Bit Pirate",     // text on the chip/pill
  "kind":  "project",       // hardware | project | topic (labeling only)
  "color": "#d6008f",       // pill color (see palette below)
  "firmware": "bitpirate",  // ← the cross-link: a firmware id, or null
  "section": null           // optional URL for a page section, or null
}

The firmware field is the important one. When a tag names a firmware id from the site's root manifest.json, the link becomes bidirectional automatically:

your guide Hack LoRa & read I2C…
tagged Bit Pirate

──▶tag "bit-pirate"

tag registry bit-pirate
firmware: "bitpirate"

──▶matches id

home firmware catalog ESP32 Bit Pirate row
grows a [guide] link →

Project / hardware tags (a firmware id set) add a [guide] link to that firmware's row on the home page, pointing at the index filtered to the tag. The guide shows the tag as a pill. You set the tag once and both links follow.
Topic tags (firmware: null — like lora, i2c, rf) are pure filters. Use them so readers can slice the list by subject.
Deep links: tutorials/?tag=lora opens the index pre-filtered. Share those anywhere.

Adding a new tag

If your guide needs a tag that doesn't exist yet, add it to the tags registry (pick a color from the palette), then use its id in the guide's tags array and in the header pills. If it should light up a firmware row, set firmware to that entry's id; otherwise null.

#00a35f green #d6008f magenta #c77d00 amber #2b8a9e teal #7a5ea8 violet

Three gotchas that trip people up

!! color has to match in two places The index reads a tag's color from tutorials.json, but the pills in a guide's <header> hardcode it inline (style="background:#d6008f"). If you change a tag color, change it both places or the pill and the chip won't match.

!! guide header pills link with ./?tag=, not ?tag= A bare ?tag=badge is relative to the guide's own URL, so it just reloads the guide. The leading ./ sends the reader to the index, filtered. (The template already does this right — keep it.)

// images Put screenshots/photos in tutorials/assets/ and reference them relatively (<img src="assets/shot.png">). Until you have the real image, leave the figure.shot placeholder frame — it renders as a labeled empty box so the layout is already correct and you can see exactly what to capture. Keep images web-sized (≤ ~300 KB).

Copy-paste starting point

The fastest path: duplicate the template and the entry below, rename, and fill in.

# in your fork, from the tutorials/ folder
git checkout -b tutorial-my-slug
cp _template.html my-slug.html
# edit my-slug.html, and add the JSON entry above to tutorials.json
git add my-slug.html tutorials.json
git commit -m "tutorial: my slug"
git push -u origin tutorial-my-slug
# then open a pull request against skickar/catbadge.online

// full reference This page is the visual tour; the complete written spec (every field, conventions, the tag registry schema) lives in CONTRIBUTING.md, and the starting HTML is _template.html.

← all tutorials open the template →