chore: move options docs to doc/options.md

.gitignore

@@ -1,4 +1,2 @@
-/dist
 /node_modules
-/test/static
-/types
+/*.tgz

README.md → doc/options.md

@@ -1,39 +1,18 @@
-# servitsy
+# servitsy options
 
-Local HTTP server for static files, coming in a small package.
+`servitsy` supports the following command-line options:
 
-- **Small:** no dependencies, 27 kilobytes gzipped.
-- **Static:** serves static files and directory listings.
-- **Local:** designed for single-user local workflows, not for production.
+- [`--cors`](#cors): send CORS HTTP headers in responses
+- [`--dir-file`](#dirfile): directory index file(s)
+- [`--dir-list`](#dirlist): allow listing directory contents
+- [`--exclude`](#exclude)
+- [`--ext`](#ext): extensions which can be omitted in URLs
+- [`--gzip`](#gzip): use gzip compression for text files
+- [`--header`](#header): add custom HTTP header(s) to responses
+- [`--host`](#host): bind to a specific host
+- [`--port`](#port): bind to a specific port or ports
 
-## Usage
-
-```sh
-npx servitsy [directory] [options]
-```
-
-By default, `servitsy` will:
-
-- serve the current directory at `http://localhost:8080` (listening on hostname `0.0.0.0`);
-- try the next port numbers if `8080` is not available;
-- serve `index.html` files for folders, and `.html` files when the extension was omitted in the URL;
-- list directory contents (for folders without an index file).
-
-You can configure this behavior [with options](#options). Here are a couple examples:
-
-```sh
-# serve current folder on port 3000, with CORS headers
-npx servitsy -p 3000 --cors
-
-# serve 'dist' folder and disable directory listings
-npx servitsy dist --dir-list false
-```
-
-## Options
-
-See `npx servitsy --help` for an overview of available options.
-
-### `cors`
+## `cors`
 
 Adds [Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) headers to responses. Defaults to `false`.
 
@@ -48,7 +27,7 @@ servitsy --cors true
 servitsy --cors false
 ```
 
-### `dirFile`
+## `dirFile`
 
 File names to look up when a request matches a directory. Defaults to `index.html`.
 
@@ -57,7 +36,7 @@ servitsy --dir-file 'index.html'
 servitsy --dir-file 'page.html,page.htm'
 ```
 
-### `dirList`
+## `dirList`
 
 Whether to list directory contents when a request matches a directory and no `dirFile` is found. Defaults to `true`.
 
@@ -70,7 +49,7 @@ servitsy --dir-list true
 servitsy --dir-list false
 ```
 
-### `exclude`
+## `exclude`
 
 Block access to files and folders matched by the provided pattern(s). Patterns may use the wildcard character `*`, but not slashes or colons (`/`, `\` or `:`). Use a pattern starting with `!` to negate an exclusion rule.
 
@@ -86,27 +65,27 @@ Patterns can also be provided as comma-separated values:
 servitsy --exclude '.*,!.well-known'
 ```
 
-Blocked requests will result in a 404 error. A request will be block if any file or folder name in the requested file's path matches an exclusion rule (while not matching a negative exclusion rule).
+Blocked requests will result in a 404 error. Requests will be blocked if any file or folder name in the requested path matches an exclusion rule (and does not also match a negative exclusion rule).
 
 For example, if a request resolves to a readable file at `<root_dir>/subfolder/data.json`, access will be:
 
 - blocked with `--exclude 'sub*'` (fully matches `subfolder`);
 - blocked with `--exclude '*.js*'` (fully matches `data.json`);
 - _allowed_ for `--exclude '.json'` (does _not_ fully match `data.json`).
 
-### `ext`
+## `ext`
 
 File extensions to look for when resolving a request. Defaults to `.html`.
 
-Typically, this allows serving a `page-name.html` file for a request URL path of `/page-name`.
+Typically, this allows serving a `<root_dir>/page-name.html` file for a request URL path of `/page-name`.
 
 ```sh
 servitsy --ext '' # disable
 servitsy --ext '.html' # default
 servitsy --ext '.xhtml' --ext '.html'
 ```
 
-### `gzip`
+## `gzip`
 
 Enables gzip compression for text files. Defaults to `true`.
 
@@ -119,7 +98,7 @@ servitsy --gzip true
 servitsy --gzip false
 ```
 
-### `header`
+## `header`
 
 Add custom HTTP headers to responses, for all files or specific file patterns. Headers can be provided using a `header:value` syntax, or as a JSON string:
 
@@ -143,7 +122,7 @@ servitsy --header '*.rst {"content-type": "text/x-rst"}'
 
 See the [`exclude` option](#exclude) for more information about file matching patterns.
 
-### `host`
+## `host`
 
 Host address that the server will listen on. May be a domain name or an IP address.
 
@@ -154,7 +133,7 @@ servitsy --host localhost
 servitsy --host mysite.local
 ```
 
-### `port`
+## `port`
 
 Port number to use for the server. Three formats are supported:
 
@@ -169,30 +148,3 @@ servitsy --port 8080-8099
 - `<number>-<number>`: a range of port numbers to try (from first to last).
 
 Defaults to `8080+`.
-
-## Alternatives
-
-> __🚨 Reminder: `servitsy` is not designed for production.__ There are safer and faster tools to serve a folder of static HTML to the public. See Apache, Nginx, [@fastify/static], etc.
-
-For local testing, here are a few established alternatives you may prefer, with their respective size:
-
-| Package       | Version | Dependencies | Size on disk† |
-| ------------- | ------- | ------------ | ------------- |
-| [servitsy]    | 0.3.0   | 0            | 128 kB        |
-| [servor]      | 4.0.2   | 0            | 144 kB        |
-| [sirv-cli]    | 2.0.2   | 12           | 392 kB        |
-| [serve]       | 14.2.3  | 89           | 7.6 MB        |
-| [http-server] | 14.1.1  | 45           | 8.9 MB        |
-
-If size and dependency count is not a concern and you want something stable and battle-tested, I recommend [serve] and [http-server].
-
-Otherwise, [servor], [sirv-cli] or [servitsy] might work for you.
-
-_† Size on disk is the uncompressed size of the package and its dependencies (as reported by `du` on macOS; exact size may depend on the OS and/or filesystem)._
-
-[@fastify/static]: https://www.npmjs.com/package/@fastify/static
-[http-server]: https://www.npmjs.com/package/http-server
-[serve]: https://www.npmjs.com/package/serve
-[servitsy]: https://www.npmjs.com/package/servitsy
-[servor]: https://www.npmjs.com/package/servor
-[sirv-cli]: https://www.npmjs.com/package/sirv-cli

package.json

@@ -2,7 +2,7 @@
 	"name": "servitsy",
 	"version": "0.3.0",
 	"license": "MIT",
-	"description": "Local HTTP server for static files. Small.",
+	"description": "Small, local HTTP server for static files",
 	"keywords": [
 		"cli",
 		"http",

readme.md

@@ -0,0 +1,79 @@
+# servitsy
+
+Small, local HTTP server for static files.
+
+- **Small:** no dependencies, 27 kilobytes gzipped.
+- **Local:** designed for local development workflows.
+- **Static:** serves files and directory listings.
+
+<img alt="Web browser screenshot of a directory listing for the servitsy source code, served by servitsy on localhost:8080" src="https://raw.githubusercontent.com/fvsch/servitsy/refs/heads/main/doc/example.png" width="820">
+
+## Installation
+
+Use `servitsy` directly with `npx servitsy`, or install it globally with `npm install -g servitsy`.
+
+> ![NOTE]
+> `servitsy` is a command-line tool published as a npm package; it requires Node.js 18 or higher.
+
+## Usage
+
+```sh
+npx servitsy [directory] [options]
+```
+
+By default, `servitsy` will:
+
+- serve the current directory at `http://localhost:8080` (listening on hostname `0.0.0.0`);
+- try the next port numbers if `8080` is not available;
+- serve `index.html` files for folders, and `.html` files when the extension was omitted in the URL;
+- list directory contents (for folders without an index file).
+
+## Options
+
+You can configure the behavior of `servitsy` [with options](https://github.com/fvsch/servitsy/blob/main/doc/options.md). Here are a couple examples:
+
+```sh
+# serve current folder on port 3000, with CORS headers
+npx servitsy -p 3000 --cors
+
+# serve 'dist' folder and disable directory listings
+npx servitsy dist --dir-list false
+```
+
+- Use `npx servitsy --help` for an overview of available options.
+- Read [doc/options.md](https://github.com/fvsch/servitsy/blob/main/doc/options.md) for details and examples.
+
+## Changelog
+
+See [doc/changelog.md](https://github.com/fvsch/servitsy/blob/main/doc/changelog.md) for the release history.
+
+## License
+
+This package is licensed under [the MIT license](./license).
+
+## Alternatives
+
+> __🚨 Reminder: `servitsy` is not designed for production.__ There are safer and faster tools to serve a folder of static HTML to the public. See Apache, Nginx, [@fastify/static], etc.
+
+For local testing, here are a few established alternatives you may prefer, with their respective size:
+
+| Package       | Version | Dependencies | Size on disk† |
+| ------------- | ------- | ------------ | ------------- |
+| [servitsy]    | 0.3.0   | 0            | 128 kB        |
+| [servor]      | 4.0.2   | 0            | 144 kB        |
+| [sirv-cli]    | 2.0.2   | 12           | 392 kB        |
+| [serve]       | 14.2.3  | 89           | 7.6 MB        |
+| [http-server] | 14.1.1  | 45           | 8.9 MB        |
+
+If size and dependency count is not a concern and you want something stable and battle-tested, I recommend [serve] and [http-server].
+
+Otherwise, [servor], [sirv-cli] or [servitsy] might work for you.
+
+_† Size on disk is the uncompressed size of the package and its dependencies (as reported by `du` on macOS; exact size may depend on the OS and/or filesystem)._
+
+[@fastify/static]: https://www.npmjs.com/package/@fastify/static
+[http-server]: https://www.npmjs.com/package/http-server
+[serve]: https://www.npmjs.com/package/serve
+[servitsy]: https://www.npmjs.com/package/servitsy
+[servor]: https://www.npmjs.com/package/servor
+[sirv-cli]: https://www.npmjs.com/package/sirv-cli

test/content-type.test.js

@@ -31,13 +31,18 @@ suite('getContentType', () => {
 		strictEqual(await fromFileName('myfont.woff2'), 'font/woff2');
 	});
 
-	test('sniffs text files from file handle', async () => {
-		const thisFile = await open(join(cwd(), 'test/content-type.test.js'));
-		const otherFile = await open(join(cwd(), 'CHANGELOG.md'));
-		strictEqual(await fromFileHandle(thisFile), 'text/plain; charset=UTF-8');
-		strictEqual(await fromFileHandle(otherFile), 'text/plain; charset=UTF-8');
-		await thisFile.close();
-		await otherFile.close();
+	test('sniffs text or bin type from file handle', async () => {
+		const testCases = [
+			{ file: 'test/content-type.test.js', expected: 'text/plain; charset=UTF-8' },
+			{ file: 'doc/changelog.md', expected: 'text/plain; charset=UTF-8' },
+			{ file: 'doc/example.png', expected: 'application/octet-stream' },
+		];
+		for (const { file, expected } of testCases) {
+			const handle = await open(join(cwd(), file));
+			const result = await fromFileHandle(handle);
+			strictEqual(result, expected);
+			await handle.close();
+		}
 	});
 });