From cfb692688cc4e592a535cfaa398f56a2cd5024ca Mon Sep 17 00:00:00 2001 From: RGBCube Date: Mon, 4 Mar 2024 12:27:17 +0300 Subject: [PATCH] Document some more --- README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/README.md b/README.md index fc48b31..edd87e5 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,30 @@ You might be wondering, _How?_ If you are, go read my [blog post](https://rgbcu.be/blog/htmnix)! +## Provided Functions + +These are the functions and variables provided by HTMNIX +which will be available in every HTMNIX file and the HTMNIX REPL +(You can enter it by running `nix repl github:RGBCube/HTMNIX`!). + +- `lib`: Just the nixpkgs lib. Pretty useful to have. + +- `raw`: Used for a string to be included in the HTML without escaping. + Just pass the string into this and it will not be escaped. + +- `call`: Calls another HTMNIX file and brings this list of provided + variables into its scope before evaulation. Basically the same as `import` + if you disregard the bringing-into-scope it does. + +- `DOCTYPE`: Equivalent to a `` tag, this exists because you can't + express it in Nix syntax and have to resort to calling `__findFile` with the + string you want instead. + +- `__findFile`: Where the magic happens. This overrides the default `__findFile` + allowing for us to return magic functor sets for `` expressions. + The `` expression however is propagated into the builtin one so it does + not interfere with your workflow. + ## More Examples > All of the examples here can be rendered with the following @@ -30,6 +54,15 @@ If you are, go read my [blog post](https://rgbcu.be/blog/htmnix)! > TARGET_FILE=$(realpath html.nix) nix eval github:RGBCube/HTMNIX#result --raw --impure > ``` +> Also keep in mind that everything is passed as an argument to the +> first HTML tag's functor. So you will need to surrond some things with +> parens for it to evaulate properly. +> +> Some notable things that require parens include: +> - Function calls. +> - `let in`'s. +> - Expressions that have spaces in them. + Create a directory listing: ```nix @@ -65,6 +98,47 @@ in <.div> ``` +Insert a raw unescaped string into your HTML: + +```nix + + "Look ma! So unsafe!"<.title> +<.head> +<body>(raw '' + <blink>Please don't do this at home...</blink> +'')<.body> +``` + +Call another Nix file as a HTMNIX file, with all the magic: + +```nix +# -- inside customer.nix -- +{ name, comment }: + +<div>{class="review";} + <figcaption> + <img.>{src="/assets/${lib.replaceStrings [ " " ] [ "-" ] name}-headshot.webp";} + <h2>name<.h2> + <.figcaption> + + <p>comment<.p> +<.div> + +# -- inside index.nix -- +let + comments = [ + { name = "John Doe"; comment = "Very nice service, reversed my hair loss!"; } + { name = "Joe"; comment = "Didn't work for me. 0/10."; } + { name = "Skid"; comment = "<script>alert('Got you!')</script>"; } # Does not work as all strings are escaped by default. + ]; +in +<ul> + (map + (comment: <li>(call ./comment.nix comment)<.li>) + comments) +<.ul> +``` + ## License ```