docs: Improve readme

README.md

@@ -1,5 +1,7 @@
 # helmfile-nix
 
+![last-commit](https://img.shields.io/github/last-commit/reMarkable/helmfile-nix)
+
 A small wrapper around helmfile to allow writing helmfile.yaml in Nix.
 
 ## Basic usage
@@ -8,7 +10,7 @@ A small wrapper around helmfile to allow writing helmfile.yaml in Nix.
 helmfile-nix render
 ```
 
-Looks for helmfile.nix in the current directory and renders it to helmfile.yaml.
+Looks for `helmfile.nix` in the current directory and renders it to a `helmfile.yaml` to stdout.
 
 ```sh
 helmfile-nix -f foo/helmfile.nix -e stage diff
@@ -18,7 +20,7 @@ Renders the helmfile in stage and passes it on to helmfile diff.
 
 For convenience we default to 'dev' if env is not set.
 
-## Structure of your helmfile.nix
+## Structure of your `helmfile.nix`
 
 ```nix
 { ... }: [
@@ -36,15 +38,34 @@ For convenience we default to 'dev' if env is not set.
 ]
 ```
 
-Note that we expect an array of yaml documents, typically the first document is the environment
-configuration and any defaults. The follow optional attributes are supported:
+Note that we expect an array of YAML documents, typically the first document is the environment
+configuration and any defaults. The follow optional attributes can be imported in your helmfile.nix:
+
+| Attribute  | Description                                                                        |
+| ---------- | ---------------------------------------------------------------------------------- |
+| lib        | nixpkgs stdlib                                                                     |
+| vals       | A function to render secrets in your helmfile. See fetchSecretValue for more info. |
+| var        | This will contain your environment variables, as well as the environment name.     |
+|            | Follows the same structure as helmfile (var.environment.name / var.values.foo).    |
+| escape_var | A function to escape a string for use in a helmfile template.                      |
+
+## Options
+
+helmfile-nix support [all the helmfile options](), in addition to:
 
-- lib: nixpkgs stdlib
-- vals: A function to render secrets in your helmfile. See fetchSecretValue for more info.
-- var: This will contain your environment variables, as well as the environment name. Follows the same structure as
-  helmfile (var.environment.name / var.values.foo).
+| Option          | Description                                                                      |
+| --------------- | -------------------------------------------------------------------------------- |
+| --show-trace    | Show a stack trace on error. This is passed to nix for the rendering and is      |
+|                 | meant to be used when you see an error during render. In most cases the          |
+|                 | error will point you to the right place though.                                  |
+| --StateValueSet | helmfile-nix will use this to override values, but it is also                    |
+|                 | passed on to helmfile. This is useful if you want to override a state value      |
+|                 | at runtime. For example, if you want to override the image of a pod temporarily. |
+| -e env          | The environment to use. Defaults to 'dev'.                                       |
+| -f file         | The helmfile.nix to use. Defaults to looking in the current directory.           |
 
 ## Caveats
 
-- We expect a env structure with a env/ directory in the same directory as the helmfile.nix
-  file containing default.yaml and a $env.yaml file for each environment.
+- We expect a env structure with a `env/`` directory in the same directory as the helmfile.nix
+file containing a `default.yaml` and a $env.yaml file for each environment.
+- Even if your helmfile gets further values, they can not be processed by nix.