# FontCustom: A Decade-Old Icon Font Generator That Still Works, Barely > FontCustom turns a folder of SVGs into icon webfonts and CSS from the command line. It is unmaintained and its own README tells you to use SVG sprites instead, but the tool remains functional for legacy projects. **FontCustom/fontcustom** — GitHub describes it as Generate custom icon webfonts from the comfort of the command line.. The repository metadata lists Ruby as its primary language. This article stays within the project description and details documented in the GitHub repository README. - Repository: https://github.com/FontCustom/fontcustom - Stars: 3,294 · Forks: 419 - Language: Ruby - License: not declared - Published: 2026-08-13 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/fontcustom-fontcustom ## What FontCustom Solves and Who It Serves FontCustom addresses a problem that was common a decade ago: turning a set of SVG icons into a single webfont so that a website could display icons with a simple class like .icon-cars54. Before widespread SVG support in browsers, icon fonts were the standard way to get scalable, colorable icons without loading many image files. The tool is aimed at developers who had a folder of SVGs and wanted to generate the font files, the @font-face CSS, and the glyph mappings automatically. Today that problem is largely gone. Modern browsers render inline SVG and SVG sprites natively, and the README itself says icon fonts are mostly unnecessary. FontCustom serves a narrow audience: people who maintain older codebases that already use icon fonts and need to regenerate or extend them without rewriting the front end. ## How FontCustom Works: From SVG to Font Files The core mechanism is a command-line compiler that reads a directory of SVG files, converts each one into a glyph in a font, and outputs the font in multiple formats plus a stylesheet. The README shows the output from a Rails example: it creates .ttf, .svg, .woff, and .eot files, plus a manifest and a SCSS partial. The tool assigns each SVG a codepoint, and the generated CSS maps a class name like .icon-cars54 to that codepoint using a :before pseudo-element. The configuration file, fontcustom.yml, controls details such as the font name, the CSS selector pattern, and whether to trim horizontal whitespace (autowidth). FontCustom also supports custom templates: any non-SVG file in the input directory is treated as a template, and embedded Ruby is processed with helpers like font_face and glyphs. This means you can generate LESS, Stylus, or any text file from the same data. The manifest file stores everything FontCustom knows, which is useful for debugging but also a sign of the tool's age. ## Getting It Running: Commands and Dependencies Installation is not trivial because FontCustom depends on external tools that are not Ruby gems. The README lists Ruby 2.6+, WOFF2, and FontForge with Python scripting. On macOS, you use Homebrew to install woff2, sfnt2woff, fontforge, and eot-utils, then run gem install fontcustom. On Linux, you need to compile sfnt2woff-zopfli and woff2 from source, which the README admits is untested and likely requires updates. Windows users must install FontForge to a path without spaces and add it to the system PATH. After installation, the basic workflow is simple: fontcustom compile my/vectors generates the font and CSS into a folder called fontcustom/. You can also run fontcustom watch to recompile on file changes, or fontcustom config to create a config file. The command-line flags mirror the config keys, so --css-selector overrides the YAML setting. For a Rails project, you add the gem, create a fontcustom.yml, write a Rake task that calls fontcustom compile, and run rake icons:compile. The README shows the expected output, including the manifest and the four font formats. ## Real Limitations: SVG Constraints and Maintenance Status FontCustom has several genuine limitations that you must accept. First, it only handles solid-color SVGs. The README warns that all colors are rendered identically, white fills are a problem, and any SVG with transparency is skipped. This means you cannot use gradients, opacity, or multi-color icons. Second, the tool is over a decade old and no longer actively maintained. The README carries a warning banner saying exactly that. There are no recent releases listed, and the last push is unknown. This has practical consequences: if you hit a bug, there is no one to fix it, and the dependency on FontForge and WOFF2 tools may break with newer OS versions. Third, the Linux installation path is acknowledged as untested, so you are on your own if you use that platform. These constraints make FontCustom a poor choice for any project that needs modern SVG features or long-term support. ## Configuration Depth: From Simple to Custom Templates FontCustom offers more configuration than you might expect from a simple CLI tool. The fontcustom.yml file can set font_design_size, font_em, font_ascent, font_descent, and autowidth to control the font metrics. The input and output hashes let you separate where SVGs are read from and where fonts and CSS are written, which is useful for Rails asset pipelines. The templates hash can include scss-rails to generate SCSS with a font-url() helper, and you can set preprocessor_path to adjust the relative path from compiled CSS to fonts. For advanced use, you can write custom templates with embedded Ruby. The README lists helpers like font_name, font_face, glyph_selectors, and glyphs, plus access to the full manifest and options. This gives you the power to generate any text file, but it also means you need to understand Ruby templating and the internal data structures. The documentation is thin on examples, so expect to read the template source in the repository to get it right. ## The Wrong Tool for New Projects: Modern Alternatives FontCustom is the wrong tool for any new project. The README itself points to alternatives: inline SVG or SVG sprites with elements, and icon libraries like Font Awesome, Heroicons, Lucide, Feather Icons, and Material Symbols. The difference in approach is fundamental. Inline SVG keeps the icon as a vector graphic in the DOM, so you can style it with CSS, animate it, and use multiple colors. SVG sprites with references a symbol defined once and reused, which reduces duplication. Icon fonts like FontCustom's output are single-color by design, and they require a separate font file and a CSS class. For a new site, you would be adding a legacy artifact that limits your design and adds a maintenance burden. If you need a maintained icon font approach, Font Awesome is a drop-in library with its own font files and CSS, but it is not a generator. The choice is clear: use SVG for new work, and only consider FontCustom if you are stuck with an existing icon font. ## Maintenance and Upgrade Cost The maintenance cost of FontCustom is high relative to its age. There is no active development, so you cannot expect fixes for compatibility with new Ruby versions or operating systems. The dependency chain includes FontForge, which is a large and complex tool, and the WOFF2 compressor, which may need to be built from source. Upgrading your system could break the tool at any time, and you would have to troubleshoot the installation again. The README provides no upgrade path beyond re-running the install commands. There is a changelog in the repository, which helps you track what changed, but with no recent releases, the changelog is likely stale. The license is listed as unknown, which is a concern if you plan to redistribute the tool or embed it in a product. You should check the repository for a LICENSE file before relying on it. For a legacy project, the cost is acceptable if you only need to regenerate fonts occasionally; for anything else, it is a liability. ## Conclusion Adopt FontCustom only if you are maintaining a legacy project that already depends on icon fonts and you cannot refactor to SVG. Do not start a new project with it. The README explicitly recommends inline SVG or SVG sprites with elements, and the tool is no longer actively maintained. Before using it, verify that your Ruby version is 2.6 or newer, that FontForge and WOFF2 tools are installed, and that your SVGs use solid fills only. Test the generated fonts in all target browsers, especially for EOT support if you still need IE. If you need a maintained icon font pipeline, look at Font Awesome or Heroicons as drop-in replacements, or build your own SVG sprite system. FontCustom is a working relic, not a foundation. ## FAQ ### What does Font Custom do? It generates cross-browser icon fonts and their supporting files, including font-face CSS, from a collection of SVG files. It runs from the command line with compile, watch, config and help commands, and it needs Ruby 2.6 or newer, WOFF2 tooling, and FontForge with Python scripting. Configuration is a generated file listing every option, and each option is also a dash-case command line flag that overrides the file. ### Is Font Custom still maintained? The project's own README says otherwise. Its opening warning states that the project is over a decade old, that modern browser SVG support makes icon fonts largely unnecessary, that it remains available for existing users, and that it is no longer actively maintained. The last push to the default branch master is dated 2026-01-09 and there are no GitHub releases. The warning lists six alternatives, including inline SVG or sprites and five icon libraries. ### How do I install Font Custom on macOS and on Linux? On macOS the instructions add a Homebrew tap named after an individual, install four packages covering WOFF2, the WOFF converter, FontForge and the legacy EOT tools, then install the gem. The Linux route is labelled untested and likely to require updates: it installs two packages with apt, then clones and builds the WOFF converter and the WOFF2 tools from source and moves both binaries into the system binary directory before installing the gem. ### Which SVG files will Font Custom accept? Only solid colours. Anything with transparency is skipped rather than flattened, all colours in a file are rendered identically so a second colour does not survive, and the guidelines warn specifically about white fills. For precision on curved icons the file recommends fills rather than strokes, and an option that trims horizontal whitespace from each glyph is offered as an alternative to centering source files by hand. ### How do I configure Font Custom? Run the config command to generate a file containing every available option. Each option is also available as a dash-case command line flag, such as the CSS selector flag, which overrides the config file. Running compile with no path reads the options from a config file in the working directory or from a config subdirectory. Input and output locations are separate YAML hashes, so vectors, fonts, stylesheets and templates can each live somewhere different. ### What can Font Custom's custom templates generate? Anything, because a template is a text file with Ruby in it. Any non-SVG file in the input directory, or in a templates subdirectory of the input, is available as a template to be copied into the output after compilation, and embedded Ruby in templates is processed. The available helpers include the font name, the font-face template, the list of icon selectors, the glyphs with their codepoint assignments, the options used during compilation, a manifest of paths and codepoints, the font path from the stylesheet, and the pseudo-element name. ## Sources - [Official README](https://github.com/FontCustom/fontcustom#readme) - [Project repository](https://github.com/FontCustom/fontcustom) - [README](https://github.com/FontCustom/fontcustom/blob/master/README.md) - [Releases](https://github.com/FontCustom/fontcustom/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/fontcustom-fontcustom