write the docs

cgsdev0 · cgsdev0 · commit 1747c6518f7a · 2023-08-19T02:07:12.000-07:00
diff --git a/core.sh b/core.sh
@@ -367,7 +367,7 @@ writeHttpResponse() {
     end_headers
     output() {
       while true; do
-        inotifywait -e MODIFY -r pages &> /dev/null
+        inotifywait -e MODIFY -r pages static &> /dev/null
         event "reload"
       done
     }
diff --git a/examples/docs/data/0-index.md b/examples/docs/data/0-index.md
@@ -5,17 +5,31 @@ lang: en-US
 
 ## Quick Start
 
-Create a new bash stack app:
+create a new bash stack app:
 ```
 curl -SsL create.bashsta.cc | bash
 ```
 
-## How?
+## Dependencies
 
-well, there are a few dependencies:
+there are a few dependencies:
 
 - bash 4.0+
 - [tcpserver](http://cr.yp.to/ucspi-tcp/tcpserver.html) (from ucspi-tcp package)
-- coreutils (tested mostly with gnu so far)
+- gnu coreutils
 
-check out the examples folder for.. examples
+optionally...
+
+- nodejs (for [tailwind](https://tailwindcss.com/) support)
+- docker (for deployment)
+
+## Overview
+
+Bash Stack uses **file-based routing**. All of the application routes should exist as
+`.sh` files in the `pages/` folder of the project.
+
+Whenever an HTTP request is made, the framework will locate the corresponding script
+and execute it. Anything written to `stdout` by the script will be written to the HTTP response body.
+
+Bash Stack also pairs well with [htmx](https://htmx.org/), which is included by default.
+We strongly recommend familizarizing yourself with [their examples](https://htmx.org/examples/) before proceeding.
diff --git a/examples/docs/data/1-configuration.md b/examples/docs/data/1-configuration.md
@@ -0,0 +1,19 @@
+---
+title: Configuration
+lang: en-US
+...
+
+## General Options
+
+You can define any environment variables you want in `config.sh`. There are a few that the framework
+will check:
+
+- `HIDE_LOGO` - if this is set, the "powered by bash" logo will be hidden
+- `NO_STYLES` - if this is set, no CSS will be linked in the `<head>`
+
+## Tailwind
+
+In order to enable the tailwind support, the environment variable `TAILWIND` must be set (this will
+be set by default in `config.sh` if you use the tailwind starter template)
+
+There is also an [example tailwind-enabled project](https://github.com/cgsdev0/bash-stack/tree/main/examples/tailwind) available.
diff --git a/examples/docs/data/2-routing.md b/examples/docs/data/2-routing.md
@@ -0,0 +1,71 @@
+---
+title: Routing
+lang: en-US
+...
+
+## Matching
+
+Routes are matched with the following priority (highest at the top):
+
+- Simple routes
+- Dynamic routes
+- Catch-all routes
+
+For a more thorough example, please check out the [example router project](https://github.com/cgsdev0/bash-stack/tree/main/examples/router).
+
+## Simple Routes
+
+Simple routes are routes with no variables. For example:
+
+```
+    pages
+    ├── index.sh
+    └── list.sh
+```
+
+Both of these are simple routes, matching requests to `/` and `/list`.
+
+## Dynamic Routes
+
+Dynamic routes have one or more variables, represented by files with square brackets.
+
+```
+    pages
+    ├── multiple
+    │   └── [variables]
+    │       └── [route].sh
+```
+
+As an example, both requests to `/multiple/a/b` and `/multiple/1/2` would match this route.
+
+## Catch-All Routes
+
+Catch-all routes have match one or more route segments.
+
+```
+    pages
+    ├── catchall
+    │   └── [...example].sh
+```
+
+As an example, both requests to `/catchall/a` and `/catchall/a/b` would match this route.
+
+You can also make a catch-all segment **optional** to match 0 or more segments, like so:
+
+```
+    pages
+    ├── catchall
+    │   └── [[...example]].sh
+```
+
+This route would match all of the following request paths:
+
+- `/catchall`
+- `/catchall/`
+- `/catchall/a`
+- `/catchall/a/b/c`
+
+## Static Files
+
+By default, bash stack will server files in the `static/` folder. These files are available by making
+`GET` requests to `/static/{filename}`.
diff --git a/examples/docs/data/3-environment.md b/examples/docs/data/3-environment.md
@@ -0,0 +1,38 @@
+---
+title: API Reference
+lang: en-US
+...
+
+## Directives
+
+The first line of each route script is checked for a "directive". These are special
+comments that let you override the way a route is handled internally.
+
+These are the directives that currently exist:
+
+- `# sse` - this route will be used for [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) [(example)](https://github.com/cgsdev0/bash-stack/blob/main/examples/jeopardy-buzzer/pages/sse/%5Busertype%5D/%5Broom%5D.sh)
+- `# allow-uploads` - this route will allow file uploads via a multipart encoded form. [(example)](https://github.com/cgsdev0/bash-stack/blob/main/examples/file-upload/pages/upload.sh)
+- `# headers` - this route will be responsible for writing its own headers section, in addition to the response body. [(example)](https://github.com/cgsdev0/bash-stack/blob/main/examples/jeopardy-buzzer/pages/login.sh)
+
+
+## Request Variables
+
+The following variables are available in all route handlers:
+
+- `REQUEST_METHOD` - the HTTP verb used
+- `REQUEST_PATH` - the relative path of the request
+- `REQUEST_QUERY` - the raw (unparsed) query string
+
+The framework will automatically parse the request and populate the following associative arrays:
+
+- `HTTP_HEADERS` - The parsed request headers
+- `QUERY_PARAMS` - The parsed query parameter string
+- `FORM_DATA` - The parsed form data (if applicable)
+- `PATH_VARS` - The parsed variable names for dynamic and catch-all routes
+- `COOKIES` - The parsed cookies from the request headers
+
+The following are only used if you are writing an upload handler:
+
+- `FILE_UPLOADS` - A mapping of input names -> tmp files
+- `FILE_UPLOAD_TYPES` - A mapping of input names -> file upload types  (according to the request)
+- `FILE_UPLOAD_NAMES` - A mapping of input names -> original filenames
diff --git a/examples/docs/pages/[[...route]].sh b/examples/docs/pages/[[...route]].sh
@@ -10,22 +10,18 @@ if [[ ! -f "$MARKDOWN_FILE" ]]; then
   return $(status_code 404)
 fi
 
-TOC=""
-if [[ "$STRIPPED" != "$INDEX" ]]; then
-  TOC="--toc"
-else
   if [[ ! -f cache/global_toc ]] || [[ ! -z "$NO_CACHE" ]]; then
-    GLOBAL_TOC="<ul>"
+    GLOBAL_TOC="<div id='sidebar'><ul>"
     for FILE in data/*.md; do
       FNAME="$(basename $FILE)"
       FNAME="${FNAME%.md}"
       GENERATED="$(pandoc --from markdown --to html --standalone --wrap=preserve --highlight-style=breezeDark $FILE --toc)"
       GLOBAL_TOC+="<li>"
-      GLOBAL_TOC+="<a href='#'>$(echo "$GENERATED" | xmllint --html --xpath '//*[@id="title-block-header"]/h1/text()' - 2> /dev/null)</a>"
+      GLOBAL_TOC+="<a href='/$FNAME'>$(echo "$GENERATED" | xmllint --html --xpath '//*[@id="title-block-header"]/h1/text()' - 2> /dev/null)</a>"
       GLOBAL_TOC+="$(echo "$GENERATED" | xmllint --html --xpath '//*[@id="TOC"]/ul' - 2> /dev/null | sed 's@href="@href="/'$FNAME'@g')"
       GLOBAL_TOC+="</li>"
     done
-    GLOBAL_TOC+="</ul>"
+    GLOBAL_TOC+="</ul></div>"
     GLOBAL_TOC="$(echo "$GLOBAL_TOC" | tr -d '\n')"
 
     # save to cache
@@ -37,8 +33,8 @@ else
     debug "cache hit"
     GLOBAL_TOC="$(cat cache/global_toc)"
   fi
-fi
+
 htmx_page << EOF
-  $(pandoc --from markdown --to html --standalone --wrap=preserve --highlight-style=breezeDark $MARKDOWN_FILE $TOC \
+  $(pandoc --from markdown --to html --standalone --wrap=preserve --highlight-style=breezeDark $MARKDOWN_FILE \
   | sed "s@</header>@</header>$GLOBAL_TOC@")
 EOF

Original file line number	Diff line number	Diff line change
`@@ -367,7 +367,7 @@ writeHttpResponse() {`
`367`	`367`	`end_headers`
`368`	`368`	`output() {`
`369`	`369`	`while true; do`
`370`		`- inotifywait -e MODIFY -r pages &> /dev/null`
	`370`	`+ inotifywait -e MODIFY -r pages static &> /dev/null`
`371`	`371`	`event "reload"`
`372`	`372`	`done`
`373`	`373`	`}`