{"id":19349073,"url":"https://github.com/digineo/texd-ruby","last_synced_at":"2026-05-04T11:40:02.047Z","repository":{"id":37820665,"uuid":"469809694","full_name":"digineo/texd-ruby","owner":"digineo","description":"Ruby/Rails client for https://github.com/digineo/texd","archived":false,"fork":false,"pushed_at":"2024-04-08T07:46:23.000Z","size":293,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-08T08:55:21.838Z","etag":null,"topics":["latex","rails","ruby","tex","texd"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digineo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-03-14T16:11:52.000Z","updated_at":"2024-04-15T08:45:38.768Z","dependencies_parsed_at":"2023-12-12T11:27:40.656Z","dependency_job_id":"c31d5d28-1936-48d4-bd86-ac38e9b5858e","html_url":"https://github.com/digineo/texd-ruby","commit_stats":{"total_commits":173,"total_committers":3,"mean_commits":"57.666666666666664","dds":"0.49132947976878616","last_synced_commit":"82c41d6d9cdc8b0dea424651f5b8ebdcd20997a9"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digineo%2Ftexd-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digineo%2Ftexd-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digineo%2Ftexd-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digineo%2Ftexd-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digineo","download_url":"https://codeload.github.com/digineo/texd-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240457988,"owners_count":19804489,"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","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":["latex","rails","ruby","tex","texd"],"created_at":"2024-11-10T04:24:34.777Z","updated_at":"2026-05-04T11:40:02.040Z","avatar_url":"https://github.com/digineo.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# texd\n\n[![Gem Version](https://badge.fury.io/rb/texd.svg)](https://badge.fury.io/rb/texd)\n[![Build Status](https://github.com/digineo/texd-ruby/actions/workflows/main.yml/badge.svg)](https://github.com/digineo/texd-ruby/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\ntexd is a Ruby client for the [texd web service](https://github.com/digineo/texd).\n\nIt leverages ActionView's template rendering mechanism to compile `.tex`\ntemplates to PDF documents. The primary use case is to render documents\nin background jobs.\n\n## Installation\n\nThe following Rails and Ruby versions[^1] are supported\n[and tested](https://github.com/digineo/texd-ruby/actions/workflows/main.yml?query=branch%3Amaster);\nolder versions of Ruby and Rails *may* work, but this is not guaranteed.\n\n| ↓ Rails / Ruby → | 3.2 | 3.3 | 3.4 | 4.0 | Notes   |\n|-----------------:|:----|:----|:----|:----|:--------|\n| 7.0              | ✅  | ❌  | ❌  | ❌  | (1) |\n| 7.1              | ✅  | ❌  | ❌  | ❌  | (1) |\n| 7.2              | ✅  | ✅  | ✅  | ✅  |     |\n| 8.0              | ✅  | ✅  | ✅  | ✅  | (2) |\n| 8.1              | ✅  | ✅  | ✅  | ✅  | (2) |\n| main branch      | ❌  | ✅  | ✅  | ✅  | (3) |\n\n\u003cdetails open\u003e\u003csummary\u003eNotes\u003c/summary\u003e\n\n1. Rails upto 7.2 depends on a version of Nokogiri which isn't available for Ruby 3.2+\n2. Rails 8.0+ requires Ruby 3.2+[^2]\n2. Rails Edge requires Ruby 3.3+[^3]\n\n\u003c/details\u003e\n\nInstall the gem and add to the application's Gemfile by executing:\n\n    $ bundle add texd\n\n[^1]: We're focussing on the minimal Ruby version available in [Debian Stable](https://packages.debian.org/trixie/ruby) and [Ubuntu LTS](https://packages.ubuntu.com/noble/ruby), i.e. 3.3 and 3.2 respectively. Regarding Rails, we'll cover a wider range.\n\n[^2]: See [commit `c7b9bb1b73`](https://github.com/rails/rails/commit/c7b9bb1b73628daf9c9ebd56c63ce3008b31ac6f) in the Rails repository\n\n[^3]: See [commit `fc22a8fc62`](https://github.com/rails/rails/commit/fc22a8fc62d5240c0d09f1078800900ea2f132ff) in the Rails repository\n\n## Configuration\n\nBefore you can use texd, you need to tell it where your instance is located.\n\nBy default, this gem reads the `TEXD_ENDPOINT` environment variable and falls\nback to `http://localhost:2201/render`, should it be empty.\n\nIf this does not match your environment, you need can reconfigure texd:\n\n```rb\nTexd.configure do |config|\n  config.endpoint = ENV.fetch(\"TEXD_ENDPOINT\", \"http://localhost:2201/\")\nend\n```\n\n\u003cdetails\u003e\u003csummary\u003eFull default config (click to open)\u003c/summary\u003e\n\n```rb\nTexd.configure do |config|\n  config.endpoint       = ENV.fetch(\"TEXD_ENDPOINT\", \"http://localhost:2201/\")\n  config.open_timeout   = ENV.fetch(\"TEXD_OPEN_TIMEOUT\", 60)\n  config.read_timeout   = ENV.fetch(\"TEXD_READ_TIMEOUT\", 180)\n  config.write_timeout  = ENV.fetch(\"TEXD_WRITE_TIMEOUT\", 60)\n  config.error_format   = ENV.fetch(\"TEXD_ERRORS\", \"full\")\n  config.error_handler  = ENV.fetch(\"TEXD_ERROR_HANDLER\", \"raise\")\n  config.tex_engine     = ENV[\"TEXD_ENGINE\"]\n  config.tex_image      = ENV[\"TEXD_IMAGE\"]\n  config.helpers        = []\n  config.lookup_paths   = []\n  config.lookup_paths   = [] # Rails.root.join(\"app/tex\") is always prepended\n  config.ref_cache_size = 128\nend\n```\n\n\u003c/details\u003e\n\nFor development environments, you can start the texd server like so (requires\nDocker and about 4GB of disk space for the included TeX live installation):\n\n```console\n$ docker run --rm -d -p localhost:2201:2201 --name texd-dev digineogmbh/texd\n```\n\nHead to [the texd project page](https://github.com/digineo/texd#readme) to learn\nabout other installation methods.\n\n## Usage\n\nFirst, create a few files:\n\n\u003cdetails\u003e\u003csummary\u003e\u003ccode\u003eapp/views/layouts/application.tex.erb\u003c/code\u003e\u003c/summary\u003e\n\nThis is the default layout. Here, you should define a `\\documentclass`\nand use `yield`. In this example, we're using ERB (Erubi) to include\ndynamic content into a `.tex` file.\n\n```erb\n\\documentclass{article}\n\\usepackage{graphicx}\n\u003c%= content_for :preamble %\u003e\n\n\\begin{document}\n\u003c%= yield %\u003e\n\\end{document}\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e\u003ccode\u003eapp/views/document/doc.tex.erb\u003c/code\u003e\u003c/summary\u003e\n\nIn `document/doc.tex`, we're specifying some stuff for the preamble,\nrender a partial, and add content for the document:\n\n```erb\n\u003c% content_for :preamble do %\u003e\n\\usepackage{blindtext}\n\n\\title{Demo document}\n\\date{\\today}\n\\author{\u003c%= user.full_name %\u003e}\n\u003c% end %\u003e\n\n\u003c%= render partial: \"document/title_page\" %\u003e\n\n\\Blinddocument\n```\n\nOK, that wasn't true. We're leveraging the `blindtext` package to add\ncontent for us :)\n\nThe `user` variable is passed as local method to `Texd.render` (see below).\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e\u003ccode\u003eapp/views/document/_title_page.tex.erb\u003c/code\u003e\u003c/summary\u003e\n\nThis partial embeds an image and creates the title page.\n\n```erb\n\\begin{center}\n  \\includegraphics[width=0.5\\linewidth]{\u003c%= texd_attach \"logo.png\" %\u003e}\n\\end{center}\n\n\\titlepage\n```\n\nWith `texd_attach`, we're referencing a file *outside* ActionView's lookup\npaths, but in Texd's lookup paths (`RAILS_ROOT/app/tex` by default).\n\nYou can use this directory to store and deploy static assets.\n\nPlease be aware, that attachments will be renamed (`att00123.png`)\nin the POST body, and `att00123.png` will be returned from `texd_attach`.\nYou can skip the renaming, if you want/need to:\n\n```erb\n% attaches RAILS_ROOT/app/tex/logo.png, and inserts \"logo.png\":\n\u003c%= texd_attach \"logo.png\", rename: false %\u003e\n\n% attaches RAILS_ROOT/app/tex/logo.png, and inserts \"assets/logo.png\":\n\u003c%= texd_attach \"logo.png\", rename: \"assets/logo.png\" %\u003e\n\n% attaches RAILS_ROOT/app/tex/common.tex, and inserts \"att00042\" (or similar):\n\u003c%= texd_attach \"common.tex\", without_extension: true %\u003e\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\u003csummary\u003e\u003ccode\u003eapp/tex/logo.png\u003c/code\u003e\u003c/summary\u003e\n\n*(Imagine your logo here.)*\n\n\u003c/details\u003e\n\nWith those files in place, you can create a PDF document:\n\n```rb\nbegin\n  blob = Texd.render(template: \"documents/doc\", locals: {\n    user: User.find(1)\n  })\n  Rails.root.join(\"tmp/doc.pdf\").open(\"wb\") { |f|\n    f.write blob\n  }\nrescue Texd::Client::QueueError =\u003e err\n  # texd server is busy, please retry in a moment\nrescue Texd::Client::InputError =\u003e err\n  # file input processing failed, maybe some file names were invalid\nrescue Texd::Client::CompilationError =\u003e err\n  # compilation failed\n  if err.logs\n    # TeX compiler logs, only available if Texd.config.error_format\n    # is \"full\" or \"condensed\"\n  end\nend\n```\n\nAll errors inherit from `Texd::Client::RenderError` and should have\na `details` attribute (a Hash) containing the actual error returned\nfrom the server.\n\n## Global error reporting\n\ntexd can be configured with external error reporting, like Sentry.\n\nThis example sends the LaTeX compilation log and compiled main input `.tex`\nfile to Sentry:\n\n```ruby\nTexd.configure do |config|\n  config.error_handler = -\u003e(err, doc) {\n    Sentry.set_context \"texd\", {\n      details: err.details, # if config.error_format == \"json\"\n      logs:    err.logs,    # otherwise\n    }.compact\n    Sentry.capture_exception(err)\n\n    raise err # re-raise, so that your code can decide further actions\n  }\nend\n```\n\n`config.error_handler` must respond to `call`, and receives the error (an instance\nof `Texd::Client::CompilationError`) and the document context (an instance of\n`Texd::Document::Compilation`).\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run\n`rake spec` to run the tests. You can also run `bin/console` for an interactive\nprompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To\nrelease a new version, update the version number in `lib/texd/version.rb`, and\nthen run `bundle exec rake release`, which will create a git tag for the version,\npush git commits and the created tag, and push the `.gem` file to\n[rubygems.org](https://rubygems.org).\n\nYou may want to run a texd server instance locally. This is easiest done by\ncalling `make texd-docker` (which pulls and runs the `ghcr.io/digineo/texd` Docker\nimage). If you need to develop/test against the bleeding edge, you can clone and\nrun texd from source:\n\n```console\n$ cd ~/code/github.com/digineo\n$ git clone git@github.com:digineo/texd\n$ cd texd\n$ mkdir -p tmp/refs\n$ make run-container EXTRA_RUN_ARGS='--reference-store dir://./tmp/refs'\n```\n\nNote: In order to run the tests against the latest `rails/main` commit, you\nneed to have Ruby 3.2 or newer installed. To run the tests against all released\nRails versions, Ruby 3.2 currently suffices.\n\nI'd recommend running `USE_DOCKER=1 make test-all` to run against all minimally\nsupported Ruby versions in Docker containers. This obviously requires Docker to\nbe installed.\n\nNote: `USE_DOCKER=1 make test-x` *also* requires to define the endpoint for the\ngem. The easiest way is to declare `TEXD_ENDPOINT=http://$CONTAINER_IP:2201/` in\naddition to `USE_DOCKER=1` (substitute `$CONTAINER_IP` with the *Docker host* IP\naddress of the container, usually in 172.17.0.1/16).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/digineo/texd.\n\n## License\n\nThis gem is open source under the terms of the [MIT license](./LICENSE). It is\nbased heavily on the [`rails-latex` gem](https://github.com/amagical-net/rails-latex).\n\n- © 2022, Dominik Menke\n- © 2010-2015, Geoff Jacobsen, Jan Baier and contributors\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigineo%2Ftexd-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigineo%2Ftexd-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigineo%2Ftexd-ruby/lists"}