feat: add configurable hash location routing (#360)

Co-authored-by: Pi/GPT-5.6-Luna <gpt-5.6-luna@pi.local>

Author: bitbloxhub

README.md

@@ -15,15 +15,16 @@ There are two functions exposeed to build the directory containing the static se
 
 | Name | Description | Available Options |
 |---|---|---|
-| `mkMultiSearch` | to build a search with multiple scopes (modules). | `baseHref`, `title` and `scopes` |
-| `mkSearch` | is a thin wrapper around `mkMultiSearch` to only use one scope (module). | `modules`, `optionsJSON`, `optionsPrefix`, `urlPrefix`, `baseHref` and `title` |
+| `mkMultiSearch` | to build a search with multiple scopes (modules). | `baseHref`, `title`, `hashLocation` and `scopes` |
+| `mkSearch` | is a thin wrapper around `mkMultiSearch` to only use one scope (module). | `modules`, `optionsJSON`, `optionsPrefix`, `urlPrefix`, `baseHref`, `title` and `hashLocation` |
 
 ### Explanation of options
 
 | Name | Description |
 |---|---|
 | `baseHref` | The directory to where the search is going to be deployed relative to the domain. Defaults to `/`. |
 | `title` | The title on the top left. Defaults to `NüschtOS Search`. |
+| `hashLocation` | Use hash-based routing (`/#/...`) instead of path-based routing. Defaults to `false` and should be enabled when the web server or page provider does not automatically fall back to `index.html` or `404.html`. <br> For example, this can occur when embedding NüschtOS Search into a larger documentation site hosted on a static server that only serves the root `404.html`. Hash-based routing encodes URL path information in the URL hash instead, so the browser always requests `index.html`, regardless of the current page. |
 | `modules` | A list of NixOS modules as an attrset or file similar to the `nixosSystem` function. Exclusive with `optionsJSON`. |
 | `optionsJSON` | Path to a pre-generated `options.json` file. Exclusive with `modules`. |
 | `optionsPrefix` | A static prefix to append to all options. An extra `dot` is always appended. Defaults to being empty. |

nix/frontend.nix

@@ -62,8 +62,10 @@ stdenv.mkDerivation (finalAttrs: {
     mkdir -p $out
     cp -rL ./dist/browser/* $out/
     cp ./dist/3rdpartylicenses.txt $out
-    # support for GitHub Pages
-    cp $out/index.html $out/404.html
+    ${lib.optionalString (!config.hashLocation) ''
+      # support for GitHub Pages and other 404.html-respecting static hosts
+      cp $out/index.html $out/404.html
+    ''}
     runHook postInstall
   '';
 

nix/wrapper.nix

@@ -134,15 +134,15 @@ rec {
       '');
 
   # also update README examples
-  mkMultiSearch = { scopes, baseHref ? "/", title ? "NüschtOS Search" }@args:
+  mkMultiSearch = { scopes, baseHref ? "/", title ? "NüschtOS Search", hashLocation ? false }@args:
     let
       chunkSize = 300;
       drv = nuscht-search {
         config =
         assert lib.assertMsg (lib.hasSuffix "/" baseHref) "baseHref needs a trailing slash";
         assert lib.assertMsg (lib.hasPrefix "/" baseHref) "baseHref needs to start with a slash";
         {
-          inherit baseHref title chunkSize;
+          inherit baseHref title hashLocation chunkSize;
           dataBase = "${baseHref}data/";
           scopes = map (scope: {
             inherit (scope) name;
@@ -158,11 +158,11 @@ rec {
       };
 
   # also update README examples
-  mkSearch = { baseHref ? "/", title ? "NüschtOS Search", ... }@args:
+  mkSearch = { baseHref ? "/", title ? "NüschtOS Search", hashLocation ? false, ... }@args:
     let
       drv = mkMultiSearch {
-        inherit baseHref title;
-        scopes = [ ({ name = ""; } // (lib.removeAttrs args [ "baseHref" "title" ])) ];
+        inherit baseHref title hashLocation;
+        scopes = [ ({ name = ""; } // (lib.removeAttrs args [ "baseHref" "title" "hashLocation" ])) ];
       };
     in
       drv // {

src/app/app.config.ts

@@ -1,14 +1,15 @@
 import { ApplicationConfig, provideBrowserGlobalErrorListeners, provideZoneChangeDetection } from '@angular/core';
-import { provideRouter } from '@angular/router';
+import { provideRouter, withHashLocation } from '@angular/router';
 
 import { routes } from './app.routes';
+import { CONFIG } from './core/config.domain';
 import { provideHttpClient, withFetch } from '@angular/common/http';
 
 export const appConfig: ApplicationConfig = {
   providers: [
     provideBrowserGlobalErrorListeners(),
     provideZoneChangeDetection({ eventCoalescing: true }),
-    provideRouter(routes),
+    provideRouter(routes, ...(CONFIG.hashLocation ? [withHashLocation()] : [])),
     provideHttpClient(withFetch()),
   ]
 };