docs: write docs & improve tooling

Squashed commit of the following:

commit 86eadd3ec42b7bce0dc5716d65798af95d0d8cbc
Author: technofab <admin@technofab.de>
Date:   Fri May 2 17:10:33 2025 +0200

docs(README): fix built with nix badge

commit f50057da69e89974f17bc37b5e140b2ef9f817f6
Author: technofab <admin@technofab.de>
Date:   Fri May 2 16:09:00 2025 +0200

ci: change back rule so docs only get deployed on main

commit ce02b043f4bd83c36285e5620e71701fc3bcc998
Author: technofab <admin@technofab.de>
Date:   Fri May 2 16:08:10 2025 +0200

docs: write docs and improve formatter etc.

commit e996b23cf877d8021759b782aa5996f5e2bf12ac
Author: technofab <admin@technofab.de>
Date:   Fri May 2 16:07:56 2025 +0200

docs: update README

commit 650f97b5608c32cf6cf66cc3fdd0965dc42e4860
Author: technofab <admin@technofab.de>
Date:   Wed Apr 23 21:05:14 2025 +0200

docs: add favicon

commit 67e1bfecbcaf0b8f7dad2eecfaccf774cc560874
Author: technofab <admin@technofab.de>
Date:   Wed Apr 23 20:53:44 2025 +0200

docs: initial setup

docs/setup.md

@@ -0,0 +1,75 @@
+# Setup
+
+To integrate Nix GitLab CI into your project, you need to make two main changes:
+
+1. Add the `nix-gitlab-ci` flake module to your `flake.nix`.
+1. Include the necessary component in your `.gitlab-ci.yml`.
+
+## Adding to `flake.nix`
+
+In your project's `flake.nix`, add `nix-gitlab-ci` as an input and import its
+flake module within your `flake-parts` configuration.
+
+```nix title="flake.nix"
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; # Or your preferred nixpkgs branch/version
+    flake-parts.url = "github:hercules-ci/flake-parts";
+
+    # Add nix-gitlab-ci as an input
+    # recommendation: pin to a specific release/version
+    nix-gitlab-ci.url = "gitlab:TECHNOFAB/nix-gitlab-ci/<version>?dir=lib";
+  };
+
+  outputs = { nixpkgs, flake-parts, ... }@inputs:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [
+        # Import the nix-gitlab-ci flake module
+        inputs.nix-gitlab-ci.flakeModule
+      ];
+
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        # Add other systems you need
+      ];
+
+      perSystem = { pkgs, ... }: {
+        # define your CI pipelines
+        # ci = { ... };
+        # pipelines."merge_request_event" = { ... };
+      };
+    };
+}
+```
+
+Replace `<version>` with the specific version or commit hash of `nix-gitlab-ci`
+you wish to use. Pinning to a specific version is highly recommended for
+reproducibility and compatibility.
+
+!!! warning
+
+    While the flake input is locked through `flake.lock`, the CI/CD component
+    will always use the latest commit of the reference. This means that by using
+    a branch like `main` as version for both, the CI/CD component will always use
+    the latest commit while your flake uses a fixed one.
+    This could result in drift between both, potentially breaking stuff.
+
+## Including in `.gitlab-ci.yml`
+
+Your `.gitlab-ci.yml` file will be minimal. Its primary role is to include the
+`nix-gitlab-ci` component, which will then generate the full CI configuration
+based on your Nix code.
+
+```yaml title=".gitlab-ci.yml"
+include:
+  - component: gitlab.com/TECHNOFAB/nix-gitlab-ci/nix-gitlab-ci@<version>
+    inputs:
+      # This input sets the Docker image tag used for the CI jobs.
+      # Use the same version as you pinned in your flake.nix for consistency.
+      version: <version>
+```
+
+Again, ensure `<version>` matches the version used in your `flake.nix`.
+This component includes a job (`build:nix-ci`) that will evaluate your Nix
+configuration and generate the `.gitlab-ci.yml` used for the pipeline run.