1
Fork 0
mirror of https://github.com/RGBCube/HTMNIX synced 2025-07-25 15:07:44 +00:00

Document some more

This commit is contained in:
RGBCube 2024-03-04 12:27:17 +03:00
parent 1b86b359e2
commit cfb692688c
No known key found for this signature in database

View file

@ -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 `<!DOCTYPE html>` 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 `<whatever.here>` expressions.
The `<nixpkgs>` 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
<head>
<title>"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
```