# typst-nix -- typst compilation in a nix derivation

Before you use this flake, please go check out [Typix](https://loqusion.github.io/typix/) 
-- a more mature project that does basically the same thing. I am building this package, 
because I believe Typix to be not abstract enough, while lacking the ability to 
automatically resolve all the dependencies.

## How to use

1. *Add to your flake inputs*:
```nix
inputs.typst-nix.url = "https://git.dzuchun.ing/dzu/typst-nix.git";
```

2. *Run `typst-lock` against your typst document*.

This flake exposes it at `apps.<system>.default`, or you may do
```sh
cargo install --git https://git.dzuchun.ing/dzu/typst-nix.git
```

Help text:
```
Statically resolve and lock `@preview` packages for a Typst project

Usage: typst-lock [OPTIONS] [ENTRYPOINT]

Arguments:
  [ENTRYPOINT]
          `.typ` file to start with, relative to `<ROOT>`

          Defaults to `main.typ`

Options:
      --root <ROOT>
          Project root

          Defaults to CWD

      --lockfile <LOCKFILE>
          Path of the lockfile to write.

          Defaults to `<ROOT>/typst.lock`

      --force
          Even if the lockfile is present at the output location, ignore it and resolve everything from scratch

      --prefetch-url-path <PREFETCH_URL_PATH>
          Path to the `nix-prefetch-url` binary

          Defaults to whatever is first in `PATH`

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version
```

This tool produces a special file at `typst.lock` (or whatever you pass into 
`--lockfile`), that you can commit -- this is a direct Typst equivalent to `flake.lock` 
and `Cargo.lock`.

3. *Call into the nix function*.

The main function is located at `.lib.compileTypst`. You may use aliases at 
`.lib.<system>.compileTypst`, if you don't care where `pkgs` come from.

Signature:
```
compileTypst :: {
    pkgs,
    # package to take the typst binary from
    typstPackage ? pkgs.typst,
    # possible values: pdf, png, svg, html, bundle
    format ? "pdf",
    # root of the typst project
    rootDir,
    # main typst file
    entrypoint ? "${rootDir}/main.typ",
    # lockfile, representing the dependencies
    lockfile ? "${rootDir}/typst.lock",
    # exposed in Typst as `sys.inputs`. must be an attrset of strings
    inputs ? { },
    # exposed in Typst as `sys.inputs`. must be an attrset of paths
    inputFiles ? { },
    # paths to fonts
    fontPaths ? [ ],
    # if set, Typst's own embedded fonts will be ignored
    ignoreEmbeddedFonts ? false,
    # UNIX timestamp exposed by datetime functions
    creationTimestamp ? 0,
    # pretty-format the output
    pretty ? false,
    pages ? null,
    # see typst c --help
    noPdfTags ? false,
    # see typst c --help
    ppi ? 144,
    features ? [ ],
    ...
} -> Derivation
```

Output of the produced derivation is your PDF or HTML respectively.

## Known limitations

- First version only supports packages from typst universe. There is a code in place to 
support custom (incl. local) repositories, but this is deferred.
- Tool operates on the "fail open" strategy: non-existent or unresolvable packages are 
skipped with a warning, while errors in your entrypoint are fatal.
- If the package traversal fails in any way, it will remain in the manifest, but without 
its dependencies. You will also see an explicit message about this hard failure.
- Tool only understands `import`s and `include`s with literal string sources. This may or 
may not be relaxed to "pure+local eval values" in the future.
- All the resolutions and downloads are naive and never retried. If one of the packages 
you are sure to exist fails, please rerun.
- Power loss durability is not a goal. If you think that the lockfile is corrupted, just 
regenerate it.