leolebras/postcss-font-magician

Magically generate all the @font-face rules

Font Magician

Font Magician is a PostCSS plugin that magically generates all of your @font-face rules. Never write a @font-face rule again.

Just use the font and font-family properties as if they were magic.

/* before */

body {
   font-family: "Alice";
}

/* after */

@font-face {
   font-family: "Alice";
   font-style: normal;
   font-weight: 400;
   src: local("Alice"), local("Alice-Regular"),
        url("http://fonts.gstatic.com/s/alice/v7/sZyKh5NKrCk1xkCk_F1S8A.eot?#") format("eot"),
        url("http://fonts.gstatic.com/s/alice/v7/l5RFQT5MQiajQkFxjDLySg.woff2") format("woff2"),
        url("http://fonts.gstatic.com/s/alice/v7/_H4kMcdhHr0B8RDaQcqpTA.woff")  format("woff"),
        url("http://fonts.gstatic.com/s/alice/v7/acf9XsUhgp1k2j79ATk2cw.ttf")   format("truetype")
}

body {
  font-family: "Alice";
}

Want to use Google Fonts? I’ll add them for you.

Want to use the visitor’s local copy of a font? Done.

Want to host your own fonts? Just tell me where they are, and I’ll do the rest.

Want to load a font async and only use it after it has been loaded? I can do that too.

Want to use Bootstrap typography? Beautiful, fully-stacked families for serif, sans-serif, and monospace are waiting for you.

Seriously, never write a @font-face rule again.

Need more? Request additional magic by creating an issue.

Usage

Follow these steps to use Font Magician:

Add Font Magician to your build tool.

npm install postcss-font-magician --save-dev

Node

1. Add PostCSS to your build tool:

   npm install postcss --save-dev

2. Use Font Magician in your script:

   postcss([
      require('postcss-font-magician')({ /* options */ })
   ]).process(
      fs.readFileSync('./css/src/style.css', 'utf8')
   ).then(function (result) {
      fs.writeFileSync('./css/style.css', result.css);
   });

Grunt

1. Add Grunt PostCSS to your build tool:

   npm install postcss-font-magician --save-dev

2. Use Font Magician in your Gruntfile:

   grunt.loadNpmTasks('grunt-postcss');
   
   grunt.initConfig({
      postcss: {
         options: {
            processors: [
               require('postcss-font-magician')({ /* options */ })
            ]
         },
         src: './css/src/*.css',
         dest: './css'
      }
   });

Gulp

1. Add Gulp PostCSS to your build tool:

   npm install --save-dev gulp-postcss

2. Use Font Magician in your Gulpfile:

   var postcss = require('gulp-postcss');
   
   gulp.task('css', function () {
      return gulp.src('./css/src/*.css').pipe(
         postcss([
            require('postcss-font-magician')({ /* options */ })
         ])
      ).pipe(
         gulp.dest('./css')
      );
   });

Options

hosted

Have a directory of self-hosted fonts?

require('postcss-font-magician')({
   hosted: '../fonts'
});

The directory will be scanned for font files, which will be read and automatically added if they are used in the document.

aliases

Prefer another name for particular fonts?

require('postcss-font-magician')({
   aliases: {
      'sans-serif': 'Source Sans Pro'
   }
});

The @font-face rule will be updated so that your alias key is the new name of the font family.

async

Need to load the fonts asynchronously?

require('postcss-font-magician')({
   async: 'path/to/your-fonts-async-loader.js'
});

Any @font-face rules are moved out of CSS and into a JavaScript file may be added to a page separately. It will automatically load the fonts before using them.

formats

Want to control which font formats are used?

require('postcss-font-magician')({
   formats: 'woff2 woff'
});

By default, local, woff2, woff, and eot are enabled. Supported formats include local, woff2, woff, ttf, eot, svg, and otf.

foundries

Want to enable specific foundries?

require('postcss-font-magician')({
   foundries: 'bootstrap google'
});

By default, all foundries are enabled. Supported foundries include custom, hosted, bootstrap, and google.

custom

Need something very specific? I can do that, too.

require('postcss-font-magician')({
   custom: {
      'My Special Font': {
         variants: {
            400: {
               normal: {
                  url: {
                     woff2: 'path/to/my-special-font.woff2'
                  }
               }
            }
         }
      }
   }
});

Future

Look forward to more magic, like:

• Support for the TypeKit foundry.
• Option to warn you when unmatched typefaces are used.

Enjoy!