@mysteryhouse/crackpot v0.4.0

Crackpot

Crackpot is an aggressively lightweight hypertext document server that aims to capture the spirit of the early web while avoiding many of its headaches.

You may like Crackpot if:

• You are old enough to remember how exciting, intuitive, and flexible it was to be able to just upload a text file to a server and have it be immediately viewable by anyone on the internet
• You are also old enough to remember what a pain in the neck it is manage more than a handful of hand-coded HTML files
• You tell yourself that you'd update your web site more often if you didn't have to completely relearn some SSG every few months

Requirements

• Node.js 18 or later
• A directory with some files you want to serve

Features

• Automatically renders Markdown and text files as HTML
• Automatically generates primary navigation and secondary navigation
• Automatically generates directory indexes
• Automatically generates an RSS feed
• Automatically resizes images

Quick Start

Open a terminal and run:

npx crackpot -d /path/to/your/files

Or, if you're already in the directory you want to serve, you can just run:

npx @mysteryhouse/crackpot

Once Crackpot starts you should be able to open a browser and navigate to http://localhost:1996.

You can also install Crackpot globally with your preferred package manager:

| npm | npm install -g @mysteryhouse/crackpot | | pnpm | pnpm install -g @mysteryhouse/crackpot | | yarn | yarn global add @mysteryhouse/crackpot |

...after which you should be able to run it by typing crackpot.

Unlisted and Hidden Files

• Files whose names start with a single underscore (_) can be accessed directly, but will not be included in navigation, auto-generated indexes, or the RSS feed.
• Files whose names start with a dot (.) or double underscore (__) will be treated as hidden, and will not be accessible via the browser.

Needless to say, you should never ever put any truly sensitive information in any web server's document root, but being able to hide documents while you work on them is handy.

Images

As currently implemented, all images served by Crackpot are automatically resized to fit within 200x200 pixels, and EXIF data is removed. (This is obviously quite inflexible; one of the next priorities is to add support for some image manipulations, including size, via the query string.)

Other media

All-other files are currently loaded and served as-is, which probably won't work well if you're trying to serve 4KUHD video. Larger files will be streamed in a near-future release.

Configuration

To see a list of startup options, run npx @mysteryhouse/crackpot --help:

Options:
  -V, --version                          output the version number
  -d, --docroot <path>                   The directory to serve files from (default: ".")
  -p, --port <port>                      The port to listen on (default: "1996")
  -b, --bind <address>                   The address to bind to (default: "0.0.0.0")
  -u, --baseUrl <url>                    The base URL that should be used for RSS and other permalinks
  -n, --site-name <name>                 The name of your website (default: "My Crackpot Site")
  -sd, --site-description <description>  A brief description of your website
  -f, --fediverse-profile <url>          Add a verification link to your fediverse profile
  -h, --help                             display help for command

Styling

Crackpot provides a default stylesheet at /style.css, but you can override it by placing your own styles.css file in your document root.

Caveat

This is a very early release; features are half-baked and likely to change. Use at your own risk.