# `Typst`
[🔗](https://github.com/Hermanverschooten/typst/blob/main/lib/typst.ex#L1)

This module provides the core functions for interacting with
the `typst` markup language compiler.

Note that when using the formatting directives, they are exactly the same as
`EEx`, so all of its constructs are supported.

See [Typst's documentation](https://typst.app/docs) for a quickstart.

# `formattable`

```elixir
@type formattable() :: {atom(), any()}
```

# `typst_opt`

```elixir
@type typst_opt() ::
  {:extra_fonts, [String.t()]}
  | {:root_dir, String.t()}
  | {:pixels_per_pt, number()}
  | {:assets, Keyword.t() | map() | [{String.t(), binary()}]}
  | {:trim, boolean()}
  | {:cache_fonts, boolean()}
  | {:pdf_standards, [String.t()]}
```

# `render_to_pdf`

```elixir
@spec render_to_pdf(String.t(), [formattable()], [typst_opt()]) ::
  {:ok, binary()} | {:error, String.t()}
```

Converts a given piece of typst markup to a PDF binary.

## Options

This function takes the following options:

  * `:extra_fonts` - a list of directories to search for fonts

  * `:root_dir` - the root directory for typst, where all filepaths are resolved from. defaults to the current directory

  * `:assets` - a list of `{"name", binary()}` or enumerable to store blobs in the typst virtual file system

  * `:trim` - when `true`, trims blank lines left by EEx tags. Defaults to `false`.

  * `:cache_fonts` - when `true`, caches scanned fonts across calls. Defaults to `true`.

  * `:pdf_standards` - a list of PDF standard strings to comply with. Supported values:
    `"a-1a"`, `"a-1b"`, `"a-2a"`, `"a-2b"`, `"a-2u"`, `"a-3a"`, `"a-3b"`, `"a-3u"`,
    `"a-4"`, `"a-4e"`, `"a-4f"`. Defaults to `[]` (no specific standard).
    An unknown value returns `{:error, "unknown PDF standard: ..."}`.

## Examples

    iex> {:ok, pdf} = Typst.render_to_pdf("= test\n<%= name %>", name: "John")
    iex> is_binary(pdf)
    true

    iex> svg = ~S|<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m19.5 8.25-7.5 7.5-7.5-7.5" /></svg>|
    iex> {:ok, pdf} = Typst.render_to_pdf(~S|#image(read("logo", encoding: none), width: 6cm)|, [], assets: [logo: svg])
    iex> is_binary(pdf)
    true

# `render_to_pdf!`

```elixir
@spec render_to_pdf!(String.t(), [formattable()], [typst_opt()]) :: binary()
```

Same as `render_to_pdf/3`, but raises if the rendering fails.

# `render_to_png`

```elixir
@spec render_to_png(String.t(), [formattable()], [typst_opt()]) ::
  {:ok, [binary()]} | {:error, String.t()}
```

Converts a given piece of typst markup to a PNG binary, one per each page.
#
## Options

This function takes the following options:

  * `:extra_fonts` - a list of directories to search for fonts

  * `:root_dir` - the root directory for typst, where all filepaths are resolved from. defaults to the current directory

  * `:pixels_per_pt` - specifies how many pixels represent one pt unit

  * `:assets` - a list of `{"name", binary()}` or enumerable to store blobs in the typst virtual file system

  * `:trim` - when `true`, trims blank lines left by EEx tags. Defaults to `false`.

  * `:cache_fonts` - when `true`, caches scanned fonts across calls. Defaults to `true`.

## Examples

    iex> {:ok, pngs} = Typst.render_to_png("= test\n<%= name %>", name: "John")
    iex> is_list(pngs)
    true

# `render_to_png!`

```elixir
@spec render_to_png!(String.t(), [formattable()], [typst_opt()]) :: [binary()]
```

Same as `render_to_png/3`, but raises if the rendering fails.

# `render_to_string`

```elixir
@spec render_to_string(String.t(), [formattable()], [{:trim, boolean()}]) ::
  String.t()
```

Formats the given markup template with the given bindings, mostly
useful for inspecting and debugging.

## Options

  * `:trim` - when `true`, trims blank lines left by EEx tags. Defaults to `false`.

## Examples

    iex> Typst.render_to_string("= Hey <%= name %>!", name: "Jude")
    "= Hey Jude!"

# `render_to_svg`

```elixir
@spec render_to_svg(String.t(), [formattable()], [typst_opt()]) ::
  {:ok, [String.t()]} | {:error, String.t()}
```

Converts a given piece of typst markup to SVG strings, one per each page.

## Options

This function takes the following options:

  * `:extra_fonts` - a list of directories to search for fonts

  * `:root_dir` - the root directory for typst, where all filepaths are resolved from. defaults to the current directory

  * `:assets` - a list of `{"name", binary()}` or enumerable to store blobs in the typst virtual file system

  * `:trim` - when `true`, trims blank lines left by EEx tags. Defaults to `false`.

  * `:cache_fonts` - when `true`, caches scanned fonts across calls. Defaults to `true`.

## Examples

    iex> {:ok, svgs} = Typst.render_to_svg("= test\n<%= name %>", name: "John")
    iex> is_list(svgs)
    true

# `render_to_svg!`

```elixir
@spec render_to_svg!(String.t(), [formattable()], [typst_opt()]) :: [String.t()]
```

Same as `render_to_svg/3`, but raises if the rendering fails.

---

*Consult [api-reference.md](api-reference.md) for complete listing*