commit ac7af67cc540eb8e4750b6b8b0404c9510cd0dc3
parent 548e0f401f35637932f845948d6b4fd789cb652d
Author: Johann150 <johann.galle@protonmail.com>
Date: Thu, 4 Feb 2021 17:53:32 +0100
reformat configuration README
Diffstat:
| M | README.md | | | 39 | ++++++++++++++++++++++++++++++++------- |
1 file changed, 32 insertions(+), 7 deletions(-)
diff --git a/README.md b/README.md
@@ -41,18 +41,43 @@ agate --content path/to/content/ \
All of the command-line arguments are optional. Run `agate --help` to see the default values used when arguments are omitted.
-When a client requests the URL `gemini://example.com/foo/bar`, Agate will respond with the file at `path/to/content/foo/bar`. If any segment of the requested path starts with a dot, agate will respond with a status code 52, even if the file does not exist (this behaviour can be disabled with `--serve-secret`). If there is a directory at that path, Agate will look for a file named `index.gmi` inside that directory. If there is no such file, but a file named `.directory-listing-ok` exists inside that directory, a basic directory listing is displayed. Files or directories whose name starts with a dot (e.g. the `.directory-listing-ok` file itself) are omitted from the list.
+When a client requests the URL `gemini://example.com/foo/bar`, Agate will respond with the file at `path/to/content/foo/bar`. If any segment of the requested path starts with a dot, agate will respond with a status code 52, wether the file exists or not (this behaviour can be disabled with `--serve-secret`). If there is a directory at that path, Agate will look for a file named `index.gmi` inside that directory.
-Agate will look for a file called `.mime` in the same directory as the file currently being served. If this file exists and has an entry for the current file, the respective data will be used to formulate the response header.
-The lines of the file should have this format:
+## Configuration
+### Directory listing
+
+You can enable a basic directory listing for a directory by putting a file called `.directory-listing-ok` in that directory. This does not have an effect on subdirectories.
+The directory listing will hide files and directories whose name starts with a dot (e.g. the `.directory-listing-ok` file itself or also the `.meta` configuration file).
+
+A file called `index.gmi` will always take precedence over a directory listing.
+
+### Meta-Presets
+
+You can put a file called `.meta` in a directory that stores some metadata about these files which Agate will use when serving these files. The file should be UTF-8 encoded. Like the `.directory-listing-ok` file, this file does not have an effect on subdirectories.
+Lines starting with a `#` are comments and will be ignored like empty lines. All other lines must start with a file name (not a path), followed by a colon and then the metadata.
+
+The metadata can take one of four possible forms:
+1. empty
+ Agate will not send a default language parameter, even if it was specified on the command line.
+2. starting with a semicolon followed by MIME parameters
+ Agate will append the specified string onto the MIME type, if the file is found.
+3. starting with a gemini status code (i.e. a digit 1-6 inclusive followed by another digit) and a space
+ Agate will send the metadata wether the file exists or not. The file will not be sent or accessed.
+4. a MIME type, may include parameters
+ Agate will use this MIME type instead of what it would guess, if the file is found.
+ The default language parameter will not be used, even if it was specified on the command line.
+
+If a line violates the format or looks like case 3, but is incorrect, it might be ignored. You should check your logs. Please know that this configuration file is first read when a file from the respective directory is accessed. So no log messages after startup does not mean the `.meta` file is okay.
+
+Such a configuration file might look like this:
```text
-<filename>:<metadata>
+# This line will be ignored.
+index.gmi:;lang=en-UK
+LICENSE:text/plain;charset=UTF-8
+gone.gmi:52 This file is no longer here, sorry.
```
-Where `<filename>` is just a filename (not a path) of a file in the same directory, and `<metadata>` is the MIME type to be stored. If `<metadata>` starts with a semicolon, agate will use the usual mechanism to determine the mime type of the file and append the specified parameters.
-Lines that start with optional whitespace and `#` are ignored, as are lines that do not contain a `:`. Both parts are stripped of any leading and/or trailing whitespace.
-
[Gemini]: https://gemini.circumlunar.space/
[Rust]: https://www.rust-lang.org/
[home]: gemini://gem.limpet.net/agate/
