Crackpot

Crackpot is an aggressively old-fashioned 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 20 or later
• A directory with some files you want to serve

Features

• Automatically renders common text file formats as HTML:
  • Markdown
  • Plain text
  • Gemini GemText
  • Emacs Org-mode (via Pandoc, if it's installed on your system)
• 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

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

Images served by Crackpot are automatically resized to fit within 300x300 pixels. Smaller images will not be resized.

If you want to include an image with different dimensions, you can add a query string argument to the image path, for example:

![Some Alt Text](./my-image.jpg?s=640x480)

Other media

All-other files are served as-is with MIME type as a best-guess based on their extensions.

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. If not provided, it will be calculated from bind and port, and use an http:// prefix.
  -n, --site-name <name>                 The name of your website (default: "ludwig")
  -sd, --site-description <description>  A brief description of your website
  -f, --fediverse-profile <url>          Add a verification link to your fediverse profile
  -s, --image-size <size>                The default width and height that images will be resized to, in the format '[width]x[height]' (default: "300x300")
  -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, occasionally broken, and likely to change. Use at your own risk.