{"id":17681252,"url":"https://github.com/jessedoyle/prawn-icon","last_synced_at":"2025-04-12T21:28:38.378Z","repository":{"id":22612575,"uuid":"25954891","full_name":"jessedoyle/prawn-icon","owner":"jessedoyle","description":"Easy icons for Prawn.","archived":false,"fork":false,"pushed_at":"2024-12-13T02:28:22.000Z","size":2250,"stargazers_count":31,"open_issues_count":0,"forks_count":15,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-10T08:50:32.510Z","etag":null,"topics":["fontawesome","hacktoberfest","prawn"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/jessedoyle.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING","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,"publiccode":null,"codemeta":null}},"created_at":"2014-10-30T04:33:54.000Z","updated_at":"2024-12-13T02:23:43.000Z","dependencies_parsed_at":"2024-12-16T08:13:57.779Z","dependency_job_id":"8ccc4bca-1104-42c9-9972-9b40ab6cdd04","html_url":"https://github.com/jessedoyle/prawn-icon","commit_stats":{"total_commits":62,"total_committers":5,"mean_commits":12.4,"dds":0.06451612903225812,"last_synced_commit":"e76a2934237f97121fe93223cf5c71499624a594"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessedoyle%2Fprawn-icon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessedoyle%2Fprawn-icon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessedoyle%2Fprawn-icon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessedoyle%2Fprawn-icon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jessedoyle","download_url":"https://codeload.github.com/jessedoyle/prawn-icon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248634003,"owners_count":21136962,"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":["fontawesome","hacktoberfest","prawn"],"created_at":"2024-10-24T09:10:37.576Z","updated_at":"2025-04-12T21:28:38.345Z","avatar_url":"https://github.com/jessedoyle.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Prawn::Icon\n\n[![Gem Version](https://badge.fury.io/rb/prawn-icon.svg)](http://badge.fury.io/rb/prawn-icon)\n![Build Status](https://github.com/jessedoyle/prawn-icon/actions/workflows/ci.yml/badge.svg?branch=master)\n\nPrawn::Icon provides a simple mechanism for rendering icons and icon fonts from within [Prawn](https://github.com/prawnpdf/prawn).\n\nThe following icon fonts ship with Prawn::Icon:\n\n* FontAwesome (http://fontawesome.io/icons/)\n* Material Design Icons (https://materialdesignicons.com/)\n* Foundation Icons (http://zurb.com/playground/foundation-icon-fonts-3)\n* PaymentFont (https://paymentfont.com)\n\nPrawn::Icon was originally written by Jesse Doyle.\n\n## Installation\n\nPrawn::Icon is distributed via RubyGems. You can install it with the following command:\n\n```bash\ngem install prawn-icon\n```\n\n## Usage\n\nPrawn::Icon was designed to have an API familiar to Prawn. A single icon may be rendered as such:\n\n```ruby\nrequire 'prawn/icon'\n\nPrawn::Document.generate('icons.pdf') do |pdf|\n  pdf.icon 'fas-beer', size: 60\nend\n```\n\nproduces:\n\n![FontAwesome Beer](https://raw.github.com/jessedoyle/prawn-icon/master/examples/fas-beer.png)\n\n## Inline Icons\n\nYou can also provide the `inline_format: true` option to Prawn::Icon:\n\n```ruby\nrequire 'prawn/icon'\n\nPrawn::Document.generate('inline_icons.pdf') do |pdf|\n  pdf.icon 'Enjoy: \u003cicon size=\"20\" color=\"AAAAAA\"\u003efas-beer\u003c/icon\u003e', inline_format: true\nend\n```\n\nproduces:\n\n![FontAwesome Beer Inline](https://raw.github.com/jessedoyle/prawn-icon/master/examples/fas-beer-inline.png)\n\nWhen using `inline_format: true`, you may supply `\u003cicon\u003e` tags with `color` and `size` attributes.\n\n## Use with [Prawn::Table](https://github.com/prawnpdf/prawn-table)\n\nA `table_icon` method may be called when creating a table's data array to render icons within a table cell:\n\n```ruby\nrequire 'prawn/icon'\nrequire 'prawn/table'\n\nPrawn::Document.generate('table_icons.pdf') do |pdf|\n\n  data = [\n    # Explicit brackets must be used here\n    [pdf.table_icon('fas-birthday-cake'), 'Cake'],\n    ['is', 'Great!']\n  ]\n\n  pdf.table(data) # =\u003e (2 x 2 table)\nend\n```\n\nNote that the `table_icon` method supports the `inline_format: true` option to create multiple icons within a cell.\n\n## Specifying Icon Families\n\nPrawn::Icon uses the prefix of an icon key to determine which font family is used to render a particular icon.\n\nCurrently supported prefixes include:\n\n* `fab` - [FontAwesome Brands](https://fontawesome.com/icons?d=gallery\u0026s=brands\u0026m=free) (eg. `fab-amazon`).\n* `far` - [FontAwesome Regular](https://fontawesome.com/icons?d=gallery\u0026s=regular\u0026m=free) (eg. `far-address-book`).\n* `fas` - [FontAwesome Solid](https://fontawesome.com/icons?d=gallery\u0026s=solid\u0026m=free) (eg. `fas-location-arrow`).\n* `mdi` - [Material Design Icons](https://materialdesignicons.com/) (eg. `mdi-beer`),\n* `fi` - [Foundation Icons](https://zurb.com/playground/foundation-icon-fonts-3) (eg. `fi-compass`).\n* `pf` - [PaymentFont](https://paymentfont.com/#icons) (eg. `pf-cash`).\n\n## How It Works\n\nPrawn::Icon uses a \"legend\" to map icon keys to unicode characters that respresent a particular icon within the font file.\n\nThis legend is a standard `.yml` file located within the font's directory.\n\nIf you wish to fork this repository and add a new font, you'll likely need to supply a corresponding legend file. Please see the current legend files within the `data/fonts` directory for examples.\n\n## Examples\n\nA Rake task is included to generate documents that display each icon and its corresponding icon key.\n\nThe command:\n\n```bash\nrake legend\n```\n\nshould generate these files when run from Prawn::Icon's gem directory.\n\n## Configuration\n\nYou can optionally configure Prawn::Icon to use an alternate data directory for font files.\n\n```ruby\nPrawn::Icon.configure do |config|\n  config.font_directory = '/path/to/my/fonts'\nend\n```\n\n## Icon Size Mode\n\nSome font families (in particular those of FontAwesome 6) define metrics that may render an icon at a size larger than requested (as described [here](https://github.com/jessedoyle/prawn-icon/pull/62#issuecomment-2501622305)).\n\nPrawn::Icon provides a `size_mode` parameter that can be utilized to control this behaviour:\n\n* `size_mode: :font_size` (**default**) - Renders the icon at a size calculated via font metrics. This may result in an icon that renders larger than requested due to ascender/descender metrics.\n* `size_mode: :icon_height` - Renders the icon at a size scaled down to the requested size.\n\nYou can specify the size mode as follows:\n\n```ruby\nPrawn::Document.generate('size_mode.pdf') do |pdf|\n  pdf.icon 'far-circle', size: 100, size_mode: :icon_height\nend\n```\n\n## Contributing\n\nI'll gladly accept pull requests that are well tested for any bug found in Prawn::Icon.\n\nIf there is enough demand for including a particular icon font, I will also accept a pull request to include it in Prawn::Icon.\n\n## License\n\nPrawn::Icon is licensed under the same terms that are used by Prawn.\n\nYou may choose between Matz's terms, the GPLv2, or GPLv3. For details, please see the LICENSE, GPLv2, and GPLv3 files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjessedoyle%2Fprawn-icon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjessedoyle%2Fprawn-icon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjessedoyle%2Fprawn-icon/lists"}