{"id":16418966,"url":"https://github.com/maennchen/iona","last_synced_at":"2025-12-11T23:45:35.937Z","repository":{"id":48580646,"uuid":"41934385","full_name":"maennchen/iona","owner":"maennchen","description":"Document generation from Elixir, using LaTeX. (Alpha: Do not use in production yet.)","archived":false,"fork":false,"pushed_at":"2023-08-28T18:49:40.000Z","size":146,"stargazers_count":43,"open_issues_count":4,"forks_count":15,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-10-25T19:55:51.996Z","etag":null,"topics":["eex","elixir","latex"],"latest_commit_sha":null,"homepage":"https://hex.pm/packages/iona","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maennchen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-09-04T19:34:44.000Z","updated_at":"2025-09-14T20:59:17.000Z","dependencies_parsed_at":"2023-08-29T01:16:11.444Z","dependency_job_id":"50ace2d4-c312-495f-a27a-b3d79b6a7628","html_url":"https://github.com/maennchen/iona","commit_stats":null,"previous_names":["maennchen/iona","jshmrtn/iona"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/maennchen/iona","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maennchen%2Fiona","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maennchen%2Fiona/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maennchen%2Fiona/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maennchen%2Fiona/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maennchen","download_url":"https://codeload.github.com/maennchen/iona/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maennchen%2Fiona/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27672362,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-11T02:00:11.302Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eex","elixir","latex"],"created_at":"2024-10-11T07:15:29.992Z","updated_at":"2025-12-11T23:45:35.916Z","avatar_url":"https://github.com/maennchen.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"Iona\n====\n[![Build Status](https://travis-ci.com/maennchen/iona.svg?branch=master)](https://travis-ci.com/maennchen/iona)\n[![Hex.pm](https://img.shields.io/hexpm/v/iona)](https://hex.pm/packages/iona)\n[![Hex.pm](https://img.shields.io/hexpm/l/iona)](https://hex.pm/packages/iona)\n[![Hex.pm](https://img.shields.io/hexpm/dt/iona)](https://hex.pm/packages/iona)\n\nDocument generation from Elixir, using LaTeX.\n\n## Highlighted Features\n\n* Generate professional-quality typeset `.pdf` (and `.dvi`) documents using\n  [LaTeX](http://www.latex-project.org/), and support defining your own\n  TeX processors for different formats.\n* Built-in support for EEx templating with automatic escaping and a custom helpers\n* Preprocessing support (multiple runs for bibliographies, etc)\n* Optionally generating a prepared directory with a `build.sh` script for final\n  processing.\n\n## Prerequisites\n\nWhile features are on the roadmap to ease authorship of `.tex` documents,\nat the current time knowledge of LaTeX is assumed (or at least a basic\nwillingness to wade into that very deep topic).\n\nWe recommend you start your knowledge quest at the\n[LaTeX homepage](http://www.latex-project.org/).\n\n## Installation\n\nThe package can be installed by adding `iona` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:iona, \"~\u003e 0.4\"}\n  ]\nend\n```\n\nDocumentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)\nand published on [HexDocs](https://hexdocs.pm). The docs can be found at\n[https://hexdocs.pm/iona](https://hexdocs.pm/iona).\n\n## LaTeX\n\nOf course you need a TeX system installed, including `latex`, `pdflatex`,\nor any other variants you'd like to use to process your `.tex` source into final\ndocuments. (The default configuration assumes `pdflatex` is installed for PDF\ngeneration and `latex` is installed for DVI generation. See \"Configuration,\" below.)\n\nYou can download and install a TeX system at the\n[LaTeX Project website](https://latex-project.org/ftp.html) -- or using the\nthe package management system of your choice.\n\n## Examples\n\n### From TeX source\n\nGenerate a PDF from an existing `.tex` source:\n\n```elixir\nIona.source(path: \"simple.tex\")\n|\u003e Iona.write!(\"/path/to/document.pdf\")\n```\n\nYou can also use a binary string:\n\n```elixir\nIona.source(\"\\documentclass[12pt]{article} ...\")\n|\u003e Iona.write!(\"/path/to/simple.pdf\")\n```\n\nMore complex preprocessing needs for citations and bibliographies?\nDefine the prepocessing pipeline:\n\n```elixir\nIona.source(path: \"academic.tex\")\n|\u003e Iona.write!(\"/path/to/academic.pdf\",\n               preprocess: ~w(latex bibtex latex))\n```\n\nTo generate a directory with a build script that can be run\nto finalize the build, use `prepare`:\n\n```elixir\nIona.source(path: \"academic.tex\")\n|\u003e Iona.prepare!(\"/path/to/build/directory\", :pdf, preprocess: ~w(latex bibtex latex))\n```\n\nWant to get the raw document content as a binary? Use `to`:\n\n```elixir\nIona.source(path: \"fancy.tex\")\n|\u003e Iona.to(:pdf)\n|\u003e MyModule.do_something_with_pdf_string\n```\n\n### Complex preprocessors\n\nYou can provide functions in the preprocessing pipeline too. The function will\nbe invoked, given the temporary directory processing is occuring and the\nbasename of the original file (eg, `\"source.tex\"`):\n\n```elixir\nIona.source(path: \"source.tex\")\n|\u003e Iona.write!(\"/path/to/source.pdf\",\n               preprocess: [fn (directory, filename) -\u003e :ok end])\n```\n\nFunction preprocessors should return:\n\n* `:ok` if processing should continue\n* `{:shell, command}` to indicate a command should be run as a preprocessor (see example below)\n* `{:error, reason}` if processing should halt\n\nIf given `{:shell, command}`, Iona will execute that command as a preprocessor.\nThis is especially useful for interpolation, eg:\n\n```elixir\nknitr = fn (_, filename) -\u003e\n  {:shell, \"R -e 'library(knitr);knitr(\\\"#{filename}\\\");'\" }\nend\n\nIona.source(path: \"graphs.Rnw\")\n|\u003e Iona.write!(\"/path/to/graphs.pdf\",\n               preprocess: [knitr])\n```\n\nImportant: As always, only interpolate trusted input into shell commands.\n\n## From an EEx TeX template\n\n```elixir\n%{title: \"My Document\"}\n|\u003e Iona.template!(path: \"/path/to/template.tex.eex\")\n|\u003e Iona.write(\"/path/to/my_document.pdf\")\n```\n\nValues are inserted into EEx with, eg, `\u003c%= @title %\u003e` after being automatically\nescaped by `Iona.Template.Helper.escape/1`.\n\nIf you're confident values are safe for raw insertion into your LaTeX documents\n(or you'd like to support insertion of LaTeX commands), use `raw/1`, made\navailable by default as part of `Iona.Template.Helper`:\n\nFor instance, if you wanted to style `@title` as boldface, you could pass it\nas `\"{\\bf My Document}\"` and insert it as a raw string:\n\n```\n\u003c%= raw @title %\u003e\n```\n\n### With Custom Helpers\n\nYou can import additional helper modules for use in your templates by two methods.\n\nThe first (and preferred) method is by overriding the `:helpers` application\nconfiguration setting (see \"Configuration,\" below).\n\nYou can also pass a `:helpers` option to `Iona.template/2` with a list of\nadditional helpers:\n\n```elixir\n%{title: \"My Document\"}\n|\u003e Iona.template!(path: \"/path/to/template.tex.eex\",\n                 helpers: [My.Custom.HelperModule])\n|\u003e Iona.write(\"/path/to/my_document.pdf\")\n```\n\nNote in this case the setting is additive; the list is concatenated with the\n`:helpers` defined in the application configuration.\n\n## Configuration\n\nThe default, out-of-the-box settings for Iona are equivalent to the\nfollowing Mix config:\n\n```elixir\nconfig :iona,\n  helpers: [Iona.Template.Helper],\n  preprocess: [],\n  processors: [pdf: \"pdflatex\", dvi: \"latex\"]\n  ```\n\nNote you can also pass a `:preprocess` and `:processor` options to define a preprocessing pipeline\non a case-by-case basis. See the examples above or the documentation for `Iona.to/3` and `Iona.write/3`.\n\n## License\n\nSee [LICENSE](./LICENSE).\n\n### LaTeX\n\nLaTeX is free software, and is not distributed with this (unaffiliated) project.\nPlease see the [LaTeX homepage](https://latex-project.org) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaennchen%2Fiona","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaennchen%2Fiona","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaennchen%2Fiona/lists"}