eleventy-plugin-scad

A plugin for Eleventy to showcase your SCAD files.

Purpose

Use Eleventy to generate a site to showcase your OpenSCAD models. This plugin adds .scad as a template and will use your OpenSCAD to render the file into an .stl. Along with the model, a Three.js model view page is gererated as well.

Check out a demo site generated from the examples that come with OpenSCAD

Install into Project

npm install eleventy-plugin-scad

Plugin Options

• launchPath (string): Location of the OpenSCAD executable (required)
  • auto - Attempts to use process.platform to find OpenSCAD in the default install locations
  • nightly - Works the same as above for the nightly version of OpenSCAD
  • docker - Download and use containerized OpenSCAD. Defaults to trixie
    • docker:TAG - You can append a container tag to use a specific version.
  • C:/openscad.exe - Absolute paths work too
  • openscad - or in a bin folder and available on your $PATH
  • Can also be set with the environment variable ELEVENTY_SCAD_LAUNCH_PATH
• theme: Use one of the W3C Core Styles as a theme
  • Options: Traditional, Modernist, Midnight, Chocolate, Oldstyle, Steely, Swiss, Ultramarine
  • Preview the themes with the W3C Core Style Sampler
  • Can also be set with the environment variable ELEVENTY_SCAD_THEME
• layout: Use a custom layout for the scad files
  • This is an escape hatch to make and use your own STL viewer layout. (needs docs)
  • Can also be set with the environment variable ELEVENTY_SCAD_LAYOUT
• collectionPage (default: true): Set false to disable the generation of a listing page with links from the scad tagged files (uses Collections API)
  • Can also be set with the environment variable ELEVENTY_SCAD_COLLECTION_PAGE
• collectionPageTitle (default: SCAD Collection): Set to a string for the title of the collection page.
  • Can also be set with the environment variable ELEVENTY_SCAD_COLLECTION_PAGE_TITLE
• verbose (default: false): Set true to view the compilation output from OpenSCAD
  • If your model uses echo() this is how to see the output
  • Can also be set with the environment variable ELEVENTY_SCAD_VERBOSE
• silent (default: false): Set true to disable all logging from the plugin
  • Can also be set with the environment variable ELEVENTY_SCAD_SILENT
• noSTL (default: false): Set true to skip generating STLs
  • Useful when models do not change frequently. Generate once, then disable STLs.
  • Can also be set with the environment variable ELEVENTY_SCAD_NO_STL
• resolveLaunchPath (default: true): Set false to disable internally resolving launchPath
  • This was added to disable trying to verify if the passed launchPath exists and/or is callable.
  • Whatever is set to launchPath will be passed to spawn(launchPath, ["--o", STL_OUT_FILE, SCAD_INPUT]);
  • Can also be set with the environment variable ELEVENTY_SCAD_RESOLVE_LAUNCH_PATH
• thumbnailColorScheme (default: Cornfield): Set to change the model thumbnail colors on the collection page.
  • Options: Cornfield, Metallic, Sunset, Starnight, BeforeDawn, Nature, Daylight Gem, Nocturnal Gem, DeepOcean, Solarized, Tomorrow, Tomorrow Night, ClearSky, Monotone
  • Can also be set with the environment variable ELEVENTY_SCAD_THUMBNAIL_COLOR_SCHEME

Add Plugin to Eleventy

There are two methods to add the plugin to Eleventy.

Method 1

Using a helper function bound to the plugin, we can pass in the eleventyConfig and get type-hints for the plugin's options. The helper calls addPlugin() with the options applied.

import { addOpenSCADPlugin } from "eleventy-plugin-scad";

/** @param {import("@11ty/eleventy/UserConfig").default} eleventyConfig */
export default function (eleventyConfig) {
  addOpenSCADPlugin(eleventyConfig, {
    launchPath: "auto",
    verbose: true,
  });
}

Method 2

This is the canonical way to install plugins according to the Eleventy documentation. There is no type-hinting with this method.

import { EleventyPluginOpenSCAD } from "eleventy-plugin-scad";

/** @param {import("@11ty/eleventy/UserConfig").default} eleventyConfig */
export default function (eleventyConfig) {
  eleventyConfig.addPlugin(EleventyPluginOpenSCAD, {
    launchPath: "auto",
    verbose: true,
  });
}

Launch Path Tips

If you are on a Mac and installed OpenSCAD into ~/Applications instead of the default location, here is a handy way to reference it for the launchPath.

import { homedir } from "node:os";
import { join } from "node:path";
import { addOpenSCADPlugin, SCAD_BINS } from "eleventy-plugin-scad";

/** @param {import("@11ty/eleventy/UserConfig").default} eleventyConfig */
export default (eleventyConfig) => {
  addOpenSCADPlugin(eleventyConfig, {
    // SCAD_BINS.MACOS => "/Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD"
    launchPath: join(homedir(), SCAD_BINS.MACOS),
  });
};

On my linux machine, I use this instead

import { addOpenSCADPlugin } from "eleventy-plugin-scad";

/** @param {import("@11ty/eleventy/UserConfig").default} eleventyConfig */
export default (eleventyConfig) => {
  addOpenSCADPlugin(eleventyConfig, {
    launchPath: "nightly", // this will find "/usr/bin/openscad-nightly" on my path
  });
};

On any machine with Docker

import { addOpenSCADPlugin } from "eleventy-plugin-scad";

/** @param {import("@11ty/eleventy/UserConfig").default} eleventyConfig */
export default (eleventyConfig) => {
  addOpenSCADPlugin(eleventyConfig, {
    launchPath: "docker:bookworm", // use the latest Debian 12 container
  });
};

Collection Page

As of version 0.9.0 the default collection page shows a grid of cards instead of a list of links.

Renderer

Each scad file is rendered and exported as an STL for inspection

Color Schemes

OpenSCAD has built-in color schemes which can be set before export.

NOTE: This only affects the output of the thumbnails.

import { addOpenSCADPlugin } from "eleventy-plugin-scad";

/** @param {import("@11ty/eleventy/UserConfig").default} eleventyConfig */
export default (eleventyConfig) => {
  addOpenSCADPlugin(eleventyConfig, {
    thumbnailColorScheme: "Cornfield",
    // or try...
    // Metallic, Sunset, Starnight, BeforeDawn
    // Nature, Daylight Gem, Nocturnal Gem, DeepOcean
    // Solarized, Tomorrow, Tomorrow Night, ClearSky, Monotone
  });
};

The model in the examples below is a Turner's Cube and the scad code for it is here if you want to make one too.

ColorScheme	Thumbnail
Cornfield
Metallic
Sunset
Starnight
BeforeDawn
Nature
Daylight Gem
Nocturnal Gem
DeepOcean
Solarized
Tomorrow
Tomorrow Night
ClearSky
Monotone