Fork me on GitHub

Font Custom

Generate custom icon webfonts from the comfort of the command line.

Cross-browser

Output multiple font formats and a bulletproof stylesheet with one command. Works on modern browsers, quirky mobile flavors, and even your old friend IE8.

Bootstrap-ready

Font Custom creates styles using Bootstrap's .icon-{{your-icon-name}} naming convention. Just include fontcustom.css and you're set.

Plug and play

No configuration or navigating confusing APIs. Just place all your vectors in a folder, link a CSS file, and let Font Custom take care of the rest.

Infinite options

Why limit yourself to generic, overused icon sets? Create your own vectors or check out Glyphicons and The Noun Project for a buffet of possibilities.

Flexible sizes

Resize icons to your heart's content. Since they're vector, Font Custom icons appear crisp at any size. (Also, no more @2x icon assets.)

Just add CSS

Change colors, add shadows, rotate, transmogrify — style icons however you want with just a little CSS. Tweaking icon designs has never been easier.

Smaller file sizes

Icon font sets like Pictos and Font Awesome require browsers to download hundreds of icons you'll never use. Font Custom only includes the icons you choose.

Screen reader friendly

Some icon fonts use letters or alphanumeric characters which are read out by screen readers. Font Custom uses Unicode's PUA so this won't ever be an issue.

Automatic regeneration

Add an icon? Remove an icon? Fonts and styles are regenerated instantly thanks to Font Custom's handy command line watcher.

Just create a directory for your svg files. Then, on the command line, run:

fontcustom watch /path/to/vectors

Font Custom will create the font files and accompanying CSS file. It will also continue to run and watch the folder for changes, so you don't have to manually re-run it each time you update the vector set.


Want to just run it once, without watching the folder?

fontcustom compile /path/to/vectors

Ready to start using Font Custom? You just need Ruby and RubyGems to get started.

To install on OS X using Homebrew simply run:

brew install fontforge ttfautohint
gem install fontcustom

On Linux? No problem*:

sudo apt-get install fontforge ttfautohint
wget http://people.mozilla.com/~jkew/woff/woff-code-latest.zip
unzip woff-code-latest.zip -d sfnt2woff && cd sfnt2woff && make && sudo mv sfnt2woff /usr/local/bin/
gem install fontcustom

Requirements

  • Ruby 1.9.x or greater.
  • A version of FontForge that includes Python scripting
  • On Debian and Ubuntu, you may need to install the ruby dev packages first: sudo apt-get install ruby1.*.*-dev.
  • If ttfautohint is not available in your distribution, Font Custom will still work but your generated font will not be properly hinted.

Configuration

You can configure several settings that will affect what files are generated, where, and how. It's possible to manually configure Font Custom on each use or, for convenience, generate a fontcustom.yml that will store your configuration settings for a given project.

To generate a new configuration file, simply use the config option:

fontcustom config /path/to/vectors

Options

There are several settings you can set to modify Font Custom's results:

  • output

    The directory to which the resulting font and CSS files will be added. If the directory doesn't exist, it will be created. By default, the output directory is /path/to/vectors/fontcustom. You probably want to set this.

  • templates

    In addition to the font files, Font Custom has the ability to generate several different types of templates/helper files, such as the accompanying CSS file. Any or all of these options can be turned on or off, depending on what you need.

    The options include:

    • preview

      A preview HTML file of the generated font, including each icon at several sizes, the class name in the CSS file, and the HTML entity the character is accessible through. See an example.
    • css

      Your standard CSS file, with each icon mapped to a class name.
    • scss

      A SCSS file with the same output as the CSS file, but suitable for easy compilation into a SCSS-based project.
    • bootstrap

      A CSS file with Twitter Bootstrap compatible overrides for the icons. Great to drop into any Bootstrap-based project.
    • bootstrap-scss

      Same as above, but as a SCSS file.
    • bootstrap-ie7

      For Bootstrap projects that may need IE7 compatibility, you can export a helper CSS file.
    • bootstrap-ie7-scss

      Same as above, but as a SCSS file.

    You can also build your own template and have Font Custom compile it for you. Simply include the path to the template, relative to either the input folder or the pwd. You can base your template off of one of the existing templates.

    By default, Font Custom will generate css and preview files for you.

  • font-name

    The font name used in your templates (automatically normalized to lowercase spinal case). By default, fontcustom. You can also pass this in on the command-line with the -n options (e.g. fontcustom -n "your-awesome-name")

  • file-hash

    Generate font files with asset-busting hashes. The hash is based on the file size and filename of each included icon, so when the icons or filenames change, new files with new hashes will be generated. Hashes will not be appended to any of the CSS/SCSS files (though the references to the fonts will be updated), only the fonts. By default, this option is on.

  • css-prefix

    The prefix for each glyph's CSS class. Default: icon-

  • font-face-path

    The http path used in @font-face declarations. Only used in .scss partials. By default, none is set.

  • debug

    Display debug messages from fontforge. This can be particularly helpful if a font isn't outputting as expected or at all (as well, very useful for submitting bug reports). By default, this is off.

  • verbose

    Display output messages containing information about the files generated/removed. By default, this is on.

Files

Font Custom generates a number of files by default, including font files, css, and a preview file as follows:

fontcustom.css
fontcustom-preview.html
fontcustom_UNIQUEHASH.ttf
fontcustom_UNIQUEHASH.eot
fontcustom_UNIQUEHASH.woff
fontcustom_UNIQUEHASH.svg

The UNIQUEHASH is generated based on the filenames and sizes of all of the vector files. This way, when new font files are generated, the old font won’t be cached by the browser.

CSS

The CSS file contains selectors and classes for each icon. The icon classes can be found at the bottom of the file, like this:

/*
Icon Classes
*/

.icon-graffiti:before { content: "\f000"; }
.icon-star:before { content: "\f001"; }
.icon-walk:before { content: "\f002"; }
.icon-windmill:before { content: "\f003"; }

Including Font Custom in your project

First, include the CSS file (there are multiple ways to do this, of course).

<link href="path/to/fontcustom/fontcustom.css" rel="stylesheet">

To add an icon to a selector, simply add the class that corresponds to the vector's file name:

<span class="icon-sheep">Mary had a little lamb.</span>

Generating alternate output (SCSS, custom templates)

Sometimes you simply need a SCSS file, an HTML preview, or want to use a custom template. Fortunately, we've made that easy with the --template argument.

By default, the --template argument is 'css preview' by default, which generates a CSS file and HTML preview of all the glyphs. You can instead provide alternative combinations of any of the types listed in the configuration section, or provide your own custom templates.

<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu">
  <li><a tabindex="-1" href="#"><span class="icon-lightning"></span> Action</a></li>
  <li><a tabindex="-1" href="#"><span class="icon-pen"></span> Another action</a></li>
  <li><a tabindex="-1" href="#"><span class="icon-graffiti"></span> Something else here</a></li>
  <li class="divider"></li>
  <li><a tabindex="-1" href="#"><span class="icon-star"></span> Separated link</a></li>
</ul>
<div class="btn-group">
  <a class="btn dropdown-toggle icon-lightning" data-toggle="dropdown" href="#">
    Action
    <span class="caret"></span>
  </a>
  <ul class="dropdown-menu">
    <!-- dropdown menu links -->
  </ul>
</div>
<div class="btn-group">
  <button class="btn btn-mini"><span class="icon-star"></span> Action</button>
  <button class="btn btn-mini dropdown-toggle" data-toggle="dropdown">
    <span class="caret"></span>
  </button>
  <ul class="dropdown-menu">
    <!-- dropdown menu links -->
  </ul>
</div>
<div class="btn-group">
  <button class="btn"><span class="icon-scale"></span> 1</button>
  <button class="btn"><span class="icon-customize"></span> 2</button>
  <button class="btn"><span class="icon-pen"></span> 3</button>
</div>

This project is licensed under the MIT License and © 2013 Kai Zau, Joshua Gross. You can find a copy of all of the licenses in the projects LICENSE.txt file.

This project was lovingly hand-crafted by Joshua Gross and Kai Zau in New York City.

You should follow us on Twitter, if that’s your thing: