From 7fcc9653aaffcfc4c84acfbddc7b4d728daeb7eb Mon Sep 17 00:00:00 2001
From: Alan Pearce
Date: Wed, 22 May 2024 13:29:43 +0200
Subject: docs: expand readme, move dev docs to subfolder

---
 README.md                 | 59 +++++++++++++++++++++++++++++------------------
 docs/developing.md        | 33 ++++++++++++++++++++++++++
 nix/pre-commit-checks.nix |  5 +++-
 3 files changed, 74 insertions(+), 23 deletions(-)
 create mode 100644 docs/developing.md

diff --git a/README.md b/README.md
index f5965e5..97f9f8b 100644
--- a/README.md
+++ b/README.md
@@ -1,35 +1,50 @@
 # Searchix
 
-## Development
+A search tool to find options and packages in the NixOS ecosystem. Aims to be like [search.nixos.org](https://search.nixos.org/) with more sources:
 
-### Pre-requisites
+-   NixOS options
+-   Nix packages
+-   [Nix darwin](https://github.com/LnL7/nix-darwin) options
+-   [Home manager](https://github.com/nix-community/home-manager) options.
 
--   [Nix (the package manager)](https://nixos.org/download/)
--   Optional:
-    -   [cachix](https://docs.cachix.org/installation#installation)
-    -   [lorri](https://github.com/nix-community/lorri)
-    -   [direnv](https://direnv.net/)
+There is an instance running at [searchix.alanpearce.eu](https://searchix.alanpearce.eu/), which uses the following channels, with updates attempted daily:
 
-### Setup
+-   nixos-options: nixos-unstable
+-   nixpkgs: nixos-unstable
+-   darwin: master
+-   home-manager: master
 
-1. Optional: use cachix to avoid building some tools
+You can also [run it yourself](./docs/running.md), if you're feeling bold. It's very light-weight!
 
-    ```shell-session
-    cachix use pre-commit-hooks
-    ```
+## Status
 
-2. Start a nix shell (this will take some time)
+**Alpha**
 
-    ```shell-session
-    nix develop
-    ```
+Expect breakage. Search results are not expected to match the quality of [search.nixos.org](https://search.nixos.org/), the priority is more on having multiple sources in one location.
 
-3. Optional: install and set up lorri and use `lorri shell` instead of `nix develop`
+Feel free to report bugs at [sourcehut](https://todo.sr.ht/~alanpearce/searchix) or open a discussion either on the [mailing list](https://lists.sr.ht/~alanpearce/searchix-discuss) or on [NixOS community forum](https://discourse.nixos.org/).
 
-4. Optional: install direnv, integrate it with your shell and then run
+## Motivation
 
-    ```shell-session
-    ln -s .envrc.sample .envrc
-    ```
+I missed having a tool like [search.nixos.org](https://search.nixos.org/) but for [nix darwin](https://github.com/LnL7/nix-darwin) and [home manager](https://github.com/nix-community/home-manager)[^1].
 
-    Now `nix develop` or `lorri shell` will be run for you automatically when you `cd` into this directory.
+I wanted to contribute something to the nix community. 🩵
+
+Also, I wanted to learn Go!
+
+## Goals
+
+-   Lean/simple
+-   Responsive (i.e. low latency)
+-   Minimal JavaScript for progressive enhancement
+-   Quickly switch between (options) sources with the same query
+
+### Future
+
+-   [ ] `programs.git.enable` should be in the first few results for the query "git"
+
+## Developing
+
+See [docs/developing.md](./docs/developing.md)
+
+[^1]: It was only during development that I found [Home Manager Option Search](https://home-manager-options.extranix.com/)
diff --git a/docs/developing.md b/docs/developing.md
new file mode 100644
index 0000000..e1d66a5
--- /dev/null
+++ b/docs/developing.md
@@ -0,0 +1,33 @@
+# Development
+
+### Pre-requisites
+
+-   [Nix (the package manager)](https://nixos.org/download/) with [flakes enabled](https://nixos.wiki/wiki/flakes#Enable_flakes_temporarily)
+-   Optional:
+    -   [cachix](https://docs.cachix.org/installation#installation)
+    -   [lorri](https://github.com/nix-community/lorri)
+    -   [direnv](https://direnv.net/)
+
+### Setup
+
+1. Optional: use cachix to avoid building some tools
+
+    ```shell-session
+    cachix use pre-commit-hooks
+    ```
+
+2. Start a nix shell (this will take some time)
+
+    ```shell-session
+    nix develop
+    ```
+
+3. Optional: install and set up lorri and use `lorri shell` instead of `nix develop`
+
+4. Optional: install direnv, integrate it with your shell and then run
+
+    ```shell-session
+    ln -s .envrc.sample .envrc
+    ```
+
+    Now `nix develop` or `lorri shell` will be run for you automatically when you `cd` into this directory.
diff --git a/nix/pre-commit-checks.nix b/nix/pre-commit-checks.nix
index a1612ef..10f8ae5 100644
--- a/nix/pre-commit-checks.nix
+++ b/nix/pre-commit-checks.nix
@@ -55,7 +55,10 @@ rec {
 
     check-case-conflicts.enable = true;
     check-symlinks.enable = true;
-    editorconfig-checker.enable = true;
+    editorconfig-checker = {
+      enable = true;
+      excludes = [ "\.md$" ];
+    };
     prettier = {
       enable = true;
       types_or = [ "plain-text" "yaml" "gotmpl" "javascript" ];
-- 
cgit 1.4.1