Ship (Simple HTML Interpolated Partials)

Summary

Ship is a minimal static site generator to be used as a CLI tool. All it does is interpolate partials and spit out the end result.

It can take in any utf8 text file format (mostly intended for HTML though), and has only one syntax to remember:

{{ partial "relative/or/absolute/path/to/partial/file" }}

This will grab the content of that file and replace that syntax in the output wherever it's found.

Install

npm install -g ship-ssg

Run

npx ship-ssg path/to/project/root --output path/to/output/folder --watch

Defaults to src and dist in current working directory for input and output folders if you just run npx ship-ssg or npx ship-ssg --watch

Nested Partials

It works with nested partials, so if you have a partial that has a partial, that has a partial, etc., it should just work.

If you add partials in a circular manner, it should warn you and stop at max 10k recursions. You'll need to remove that circular partial dependency to continue.

Example of circular partials: file 1 contains partial 2, which calls file 1 as a partial, causing an infinite loop.

Flags/Params

By default it assumes your input folder is src in your current working directory, and that your output folder is dist.

You can change that:

• Set input folder using npx ship path/to/input/folder
• Set output folder using npx ship --output path/to/output/folder
• Set it to watch for any changes in your input folder using ship --watch
• Combine them all like this npx ship path/to/input/folder --output path/to/output/folder --watch

Folder Structure

Inside of your input folder (defaults to src in your current working directory), there is only one special folder: _partials

Anything in _partials will not be directly output to the output folder. It's a way of excluding files that are only to be used as partials for other files.

What is a partial?

Any utf8 file you want anywhere in your project folder. Use at your own discretion, you know what you're doing.

Examples of ways you can use partials:

• index.html calls _partials/header.html -> outputs an index.html to dist with the header interpolated
• index.html calls /_partials/some_folder/some_partial.html -> outputs an index.html with that file interpolated
• index.html calls about.html -> outputs an index.html with the entire about page interpolated, and also outputs the about.html page to dist

Assets and other files

Any file that is not text (e.g. binaries like images, media, PDFs, etc) will just be copied as they are to the output folder.

Using with other CLI tools

If you want to use this with other CLI tools, like say tailwind, you probably just want to run them on changes to the output folder.

Example: npx ship --output some/output/folder & npx tailwindcss -i ./some/output/folder/input.css -o ./some/output/folder/output.css --watch

Or you could just run them in different terminals. However you want to run multiple long running CLI processes.

Why don't you have X? You should really add X.

Ship hears you. Ship don't care.

The idea here is simplicity rather than a sophisticated CMS. There's plenty of those out there already with Hugo, Astro, etc.

I mean, unless your idea is really good. Never say never.