🐑 - refsheep

refsheep is a character reference page and gallery generator intended to make life easier when commissioning artists.

You can see this repo in action at refs.eedq.org

or what it's based on at refs.videah.net/videah

It is built on top of Nodejs, Zola, Vite, and Tailwind, with python as a glue for the build. It is arguably overengineered. It is meant to serve my own purposes and if other people find use out of it that's just a nice bonus.

Features

• Automatic color pallete indicator buttons that highlight parts of ref sheets
• Fully responsive and automatic mosiac card layout
• 3D model turntables powered by <model-viewer>
• Automated image gallery with artist credit links
• Automatically resizes images for smaller filesizes
• NSFW content toggle, can be hidden behind URL parameters
• Refsheet toggle between two (or more) Reference sheet versions, Can default to a secondary sheet with URL parameter.
  • sheet=nude, sheet=nsfw, sheet=secondary, and sheet=2 all work for this.
• This repo is set up to be used with Cloudflare's Pages framework and R2 (an S3 compatible storage system). Zip files are stored on R2 due to size limitation on cloudflare pages

Usage

Prerequisites: NodeJS, npm with corepack enabled, python 3.11+, Zola

This repo is tested to run on Manjaro Linux (as of Jan 2026) and Cloudflare's Ubuntu based Pages agents on platform 3.0. Running on cloudflare pages v2/v3 requires using the undocumented env variable: UNSTABLE_PRE_BUILD="asdf plugin add zola https://github.com/salasrod/asdf-zola && asdf install zola latest && asdf global zola latest"

Assuming the prereq's are installed the following should get you rolling:

# Install necessary dependencies
# you may need to specify --pure-lockfile
yarn install

pip install -r requirements.txt

# Serve refsheep locally and hot-reload any changes made
./watch.sh

# Build and bundle everything into a production ready package
yarn build

# Build and upload relevant zips to s3 compatible host (tested with Cloudflare R2)
# Tested to run on Cloudflare's build agent for pages. This is what powers refs.eedq.org
./build.sh 

# Build a Caddy web server docker image with refsheep embeded inside
# This is what powers refs.videah.net
docker build

Structure

Characters can be added by creating a directory in content named after your character and an index.md file. The name of the directory is what your character's URL will be (i.e example.com/character-name).

The markdown file defines the character's page structure and content. This is done through a cursed combination of TOML, Markdown, and HTML. You can see an example of what this looks like in the included characters otter or videah's characters from his repo: videah and dad.

The beginning of the file requires a TOML section in between +++'s that sets a few variables for the pages generation.

+++

# These appear on the landing page and at the top of the specific characters page
# Display name of the character.
title = "Videah"
# Description of the character.
description = "Nerdy gay werewolf"

[extra]
# Emoji that's used in the browser tab title
emoji = "🐺"
# These are colors that are used in the color pallete below the reference sheet.
colors = ["#2d1413", "#5a292d", "#6c383c", "#f9d670", "#915856", "#b73341", "#6baac5", "#f6cfc9"]
# Tolerances of the colors specificed above in the same order.
# Used to highlight colors that are close but not quite an exact match.
color_tolerances = [10, 10, 5, 30, 10, 20, 35, 20]
# By default a NSFW toggle will appear if you have NSFW content.
# This option makes it so ?nsfw=true is needed at the end of your URL for that to appear.
require_nsfw_in_url = true

+++

Shortcodes

This project makes heavy use of Zola shortcodes.

These can be found in templates/shortcodes