#stagnant

!!! Experimental !!!

A pipeline based static "site" generator focused on allowing flexible generation. Fundamentally, this project is simple and only enforces a simple set of rules, filesystem structures, and a small subset of exposed environment variables.

#Reasoning

I write my entire life in markdown, and things that aren't in markdown get generators to turn them into markdown for my own consumption. While some static site generators have a common markdown backend I found that often the generated code was hard to pipeline into other outputs, such as Gopher.

Additionally, my CI of choice is Laminar-CI which takes the opinionated stance of "just use job shell scripts". I found this rather freeing from implementation specific DSLs or janky non-reproducible web interface configuration management.

I wanted something that allowed me to write a simple step-by-step sychronous pipeline using POSIX.1-2008 shell scripts and allow me to write the pipeline steps in any language I felt like programming in.

#Versions

stagnant contains 2 supported versions:

• stagnant.sh - A POSIX.1-2008 shell script that contains all the logic for building a site
• stagnant.go - The Go implementation that is used for more programmatic logic, will eventually contain an extention to load Go plugins

#Example Structure

The only directories that are fundamental to the creation of a "site" is the site directory which contains the initial format of the site and the functions (stages) directory that contains the staged pipeline pieces of code. It is also highly suggested to create a util directory that contains executables or scripts used during pipelining.

My personal project root looks like this (directories marked with < are required for the generator to work by default):

.
|-- README.md
|-- build/
|-- stages/	<
|-- gen.sh*
|-- prod/
|-- site/	<
|-- tmpl/
`-- util/	<

.
|-- build/
|   |-- 1581996075/
|   |-- 1581996127/
|   |-- 1581996133/
|   `-- latest@ -> 1581996133
|-- stages/
|   |-- 00-depends.sh*
|   |-- 01-slides.sh*
|   |-- 02-http.sh*
|   |-- 03-removemd.sh*
|   |-- 04-minify.sh*
|   `-- scripts/
|       |-- clean.sh*
|       `-- deploy.sh*
|-- gen.sh*
|-- prod/
|   |-- 403.html
|   |-- 404.html
|   |-- 50x.html
|   |-- a/
|   |-- d/
|   |-- e/
|   |-- f/
|   |-- favicon.ico
|   |-- favicon.png
|   |-- i/
|   |-- id.html
|   |-- index.html
|   |-- keybase.txt
|   |-- keys.txt
|   |-- n/
|   |-- p/
|   |-- pub.key
|   |-- resume.pdf
|   |-- rss.xml
|   |-- style.css
|   |-- t/
|   `-- talks.html
|-- site/
|   |-- 403.md
|   |-- 404.md
|   |-- 50x.md
|   |-- f/
|   |-- favicon.ico
|   |-- favicon.png
|   |-- i/
|   |-- id.md
|   |-- index.md
|   |-- keys.txt
|   |-- p/
|   |-- pub.key
|   |-- rss.xml
|   |-- t/
|   `-- talks.md
|-- tmpl/
|   |-- footer.html
|   |-- header.html
|   |-- meta.html
|   |-- rss.xml
|   |-- rss_item.xml
|   |-- style.css
|   `-- template.html
`-- util/
    |-- hdev*
    |-- hmdtohtml*
    |-- hosakahashi*
    `-- minify*

#Exposed Variables

The following variables are exposed to all running stage executables/scripts and to any generator scripts:

• _ORIGIN - The origin directory that is pwd
• _SITEDIR - Contains all the site files. In my case I use a bunch of .md files and assets that get built
• _BUILDROOT - The build directory that contains all the build runs and a symlink ($_BUILDROOT/latest) to the last build
• _BUILDID - The current running build ID, by default uses UNIX timestamps
• _BUILDDIR - The current running build and build ID in absolute path form
• _STAGEDIR - Directory containing the stage scripts or executables
• _SCRIPTDIR - Directory containing scripts that are used for "out-of-build" site management (for example, clean.sh cleans my build dirs)
• _UTILDIR - Utilities that are required for building are expected to be built into this directory
• _PRODDIR - The current "production" build. The idea is that this can contain the code that is committed to CI and all tests and deployments can be run without pulling in all the stagnant repo

#Demo

The demo that is in the default repository requires two projects to either be in $PATH or to be in the util directory:

• https://github.com/gomarkdown/mdtohtml
• https://github.com/tdewolff/minify

Once those binaries are setup simply:

go run stagnant.go

and check build/latest