diff options
| -rw-r--r-- | sticks/LICENSE | 12 | ||||
| -rw-r--r-- | sticks/README.md | 36 | ||||
| -rwxr-xr-x | sticks/sticks | 98 |
3 files changed, 146 insertions, 0 deletions
diff --git a/sticks/LICENSE b/sticks/LICENSE new file mode 100644 index 0000000..339be5a --- /dev/null +++ b/sticks/LICENSE @@ -0,0 +1,12 @@ +Copyright (C) 2023 JJ <https://apropos.codes> + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH +REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, +INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR +OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +PERFORMANCE OF THIS SOFTWARE. diff --git a/sticks/README.md b/sticks/README.md new file mode 100644 index 0000000..ac1a7a0 --- /dev/null +++ b/sticks/README.md @@ -0,0 +1,36 @@ +# sticks: a simple static site generator + +`sticks` is a tiny and customizable static site generator. +it leverages `pandoc` to great extent, and so consists only of a single bash script. + +<!-- : yet manages to provide nigh-total the features of jekyll, and more. this powers both my [website](https://apropos.codes) and my [wiki](https://wiki.apropos.codes). --> + +don't use this! use [hakyll](https://jaspervdj.be/hakyll/) instead. it's a library for constructing static site generators: hooking directly into pandoc's haskell library and providing much more reasonable constructs for accomplishing such a task. i just wanted an excuse to learn pandoc proper. + +### feature list +- html templating: directly through pandoc. +- support for markdown, restructured text, asciidoc, org-mode... +- renders latex and typst directly to pdfs +- pandoc flavoured markdown, including: + - lists with preserved order (numbers mean something) + - line blocks and nested quotes + - code blocks and syntax highlighting + - a wide variety of tables + - inline latex via katex+mathml + - yaml metadata blocks (!!!) + +### usage +pandoc (and by extension sticks) operates on **templates** containing *variables* and *expressions*, and **files** containing *metadata* and *content*. + +templates are simply an html, or pdf, or etc file containing the content needed (ex. header and footer material) for a free-standing document. they contain the special `$body$` variable somewhere for file injection. files may be prefixed with a YAML metadata block declaring variables (ex. title, subtitle, author...) for use by templates, and a special `template: ` variable to denote the template to be used. + +every project must have a `_templates` folder (configurable location, see `--templates`) containing a `default.html`. this is the template that will be used by files lacking an explicit template. templates are for the *output type*, which in sticks' case is HTML and PDF. + +the aforementioned YAML metadata blocks may be placed before files of any type. they look like the following: +```yaml +--- +template: default +title: a really cool document +subtitle: https://www.youtube.com/watch?v=dQw4w9WgXcQ +--- +``` diff --git a/sticks/sticks b/sticks/sticks new file mode 100755 index 0000000..a493a56 --- /dev/null +++ b/sticks/sticks @@ -0,0 +1,98 @@ +#!/usr/bin/env bash + +shopt -s extglob +shopt -s globstar + +SITE_DIR="_site/" +TEMPLATE_DIR="_templates/" +OUTPUT_DIR=".site/" +CONFIG_DIR=".data/" + +# parse parameters +while test $# -gt 0; do + case $1 in + -w|--wiki) + MODE="wiki" + shift;; + -s|--site) + MODE="site" + shift;; + -j|--jekyll) # jekyll mode is entirely unimplemented + MODE="jekyll" + shift;; + -o|--output) + shift + OUTPUT_DIR="$1" + shift;; + -t|--templates) + shift + TEMPLATE_DIR="$1" + shift;; + -h|--help) + echo "usage: sticks [flags]" + echo " -s, --site: run sticks in site mode (default)" + echo " -w, --wiki: run sticks in wiki mode (file hierarchies are compressed)" + echo " -j, --jekyll: run sticks in jekyll mode (unimplemented)" + echo " -o <arg>, --output <arg>: specify the output directory. default: _site" + echo " -t <arg>, --templates <arg>: specify where sticks should look for templates. default: _templates" + exit 0;; + *) + echo "$0: unknown argument $1" + exit 1;; + esac +done + +# force a default template +if [ ! -f "$TEMPLATE_DIR/default.html" ]; then + echo "sticks requires a template directory containing at least default.html" + exit 1 +fi + +# prep _ folders +rm -rf "$SITE_DIR" "$OUTPUT_DIR" "$CONFIG_DIR" +mkdir "$CONFIG_DIR" +mv "$TEMPLATE_DIR" "$CONFIG_DIR/templates" +mv "$CONFIG_DIR/templates/default.html" "$CONFIG_DIR/templates/default.html5" + +# pandoc will not automatically create directories for its output +for dir in **/*/; do + mkdir -p "$OUTPUT_DIR/$dir" +done + +# convert supported files to html/pdf +for file in **/*.@(html|md|rst|org|adoc|tex|latex|typ); do + filename="$file" + if [ "$MODE" = "wiki" ]; then + filename="$(basename "$file")" + fi + if [ -f "$OUTPUT_DIR/${filename%.*}.html" ]; then + echo "warning: multiple conflicting entries ${filename%.*}" + fi + case ${file##*.} in + tex|latex|typ) + pandoc --standalone --quiet --data-dir "$CONFIG_DIR" \ + --output "$OUTPUT_DIR/${filename%.*}.pdf" "$file" + ;; + *) + template="$(sed -ne '/^template:/{s/^template: *//p;q}' "$file")" + if [ -z "$template" ]; then + template="default.html5" + fi + pandoc --standalone --quiet --data-dir "$CONFIG_DIR" --template "$template" \ + --output "$OUTPUT_DIR/${filename%.*}.html" "$file" + ;; + esac +done + +# copy unprocessed files directly (incl. css & latex) +for file in **/!(*.@(html|md|rst|org|adoc)); do + if [ -f "$file" ]; then + cp "$file" "$OUTPUT_DIR/$file" + fi +done + +# clear cache & update site +mv "$OUTPUT_DIR" "$SITE_DIR" +mv "$CONFIG_DIR/templates/default.html5" "$CONFIG_DIR/templates/default.html" +mv "$CONFIG_DIR/templates" "$TEMPLATE_DIR" +rm -rf "$OUTPUT_DIR" "$CONFIG_DIR" |