"readme": "# Font Magician [![Build Status][ci-img]][ci]\n\n<img align=\"right\" width=\"135\" height=\"95\" src=\"http://postcss.github.io/postcss/logo-leftp.png\" title=\"Philosopher’s stone, logo of PostCSS\">\n\n[Font Magician] is a [PostCSS] plugin that magically generates all of your `@font-face` rules. Never write a `@font-face` rule again.\n\nJust use the **font** and **font-family** properties as if they were magic.\n\n```css\n/* before */\n\nbody {\n font-family: \"Alice\";\n}\n\n/* after */\n\n@font-face {\n font-family: \"Alice\";\n font-style: normal;\n font-weight: 400;\n src: local(\"Alice\"), local(\"Alice-Regular\"),\n url(\"http://fonts.gstatic.com/s/alice/v7/sZyKh5NKrCk1xkCk_F1S8A.eot?#\") format(\"eot\"),\n url(\"http://fonts.gstatic.com/s/alice/v7/l5RFQT5MQiajQkFxjDLySg.woff2\") format(\"woff2\"),\n url(\"http://fonts.gstatic.com/s/alice/v7/_H4kMcdhHr0B8RDaQcqpTA.woff\") format(\"woff\"),\n url(\"http://fonts.gstatic.com/s/alice/v7/acf9XsUhgp1k2j79ATk2cw.ttf\") format(\"truetype\")\n}\n\nbody {\n font-family: \"Alice\";\n}\n```\n\n* Want to use **[Google Fonts](#foundries)**? I’ll add them for you.\n* Want to use the visitor’s **local** copy of a font? Done.\n* Want to **[host](#hosted)** your own fonts? Just tell me where they are, and I’ll do the rest.\n* Want to load a font **[async](#async)** and only use it after it has been loaded? I can do that too.\n* Want to use **[Bootstrap](#foundries)** typography? Beautiful, fully-stacked families for **serif**, **sans-serif**, and **monospace** are waiting for you.\n\nSeriously, never write a `@font-face` rule again.\n\nNeed more? Request additional magic by [creating an issue].\n\n## Installation\n\nAdd [Font Magician] to your build tool.\n```sh\nnpm install postcss-font-magician --save-dev\n```\nor\n```sh\nyarn add postcss-font-magician --dev\n```\n\n### Node\n\nUse [Font Magician] in your script:\n ```js\n const pfm = require('postcss-font-magician');\n postcss([\n pfm({ /* options */ })\n ]).process(\n fs.readFileSync('./css/src/style.css', 'utf8')\n ).then(function (result) {\n fs.writeFileSync('./css/style.css', result.css);\n });\n ```\n\n\n### Webpack\n\nUse [Font Magician] in your webpack.config.js:\n\n *Webpack 1.x*\n\n ```js\n postcss: function () {\n return [\n ...\n fontMagician({\n variants: {\n 'Roboto Condensed': {\n '300': [],\n '400': [],\n '700': []\n }\n },\n foundries: ['google']\n })\n ...\n ];\n }\n ```\n\n *Webpack 2.x*\n\n ```js\n plugins: [\n new webpack.LoaderOptionsPlugin({\n options: {\n ...\n postcss: [\n ...\n fontMagician({\n variants: {\n 'Roboto Condensed': {\n '300': [],\n '400': [],\n '700': []\n }\n },\n foundries: ['google']\n })\n ]\n },\n }),\n ...\n ]\n ```\n\n *Webpack 3+*\n\n **postcss.config.js**\n ```js\n module.exports = {\n plugins: {\n 'postcss-font-magician': {\n variants: {\n 'Roboto Condensed': {\n '300': [],\n '400': [],\n '700': []\n }\n },\n foundries: ['google']\n }\n }\n }\n ```\n\n **webpack.config.js**\n ```js\n {\n loader: 'postcss-loader',\n options: {\n config: {\n path: 'path/to/postcss.config.js'\n }\n }\n }\n ```\n\n### Grunt\n\nUse [Font Magician] in your Gruntfile:\n ```js\n grunt.loadNpmTasks('grunt-postcss');\n\n grunt.initConfig({\n postcss: {\n options: {\n processors: [\n require('postcss-font-magician')({ /* options */ })\n ]\n },\n src: './css/src/*.css',\n dest: './css'\n }\n });\n ```\n\n### Gulp\n\nUse [Font Magician] in your Gulpfile:\n ```js\n var postcss = require('gulp-postcss');\n\n gulp.task('css', function () {\n return gulp.src('./css/src/*.css').pipe(\n postcss([\n require('postcss-font-magician')({ /* options */ })\n ])\n ).pipe(\n gulp.dest('./css')\n );\n });\n ```\n\n## Options\n\n### variants\n\nWant to download only specific font weights, styles and formats?\n\n```js\nrequire('postcss-font-magician')({\n variants: {\n 'Open Sans': {\n '300': ['woff, eot, woff2'],\n '400 italic': ['woff2']\n }\n }\n});\n```\n\nThe plugin will download the font only selected weights, styles and formats.\n\n### unicode-range\n\nNeed to support [unicode-range](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range)? You can use it as a second element in an option array.\n\n```js\nrequire('postcss-font-magician')({\n variants: {\n 'Open Sans': {\n '300': ['woff, eot, woff2', 'U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF'],\n '400 italic': ['woff2']\n }\n }\n});\n```\n\n### font-stretch\n\nNeed to support [font-stretch](https://developer.mozilla.org/en-US/docs/Web/CSS/font-stretch)? You can use it as a 2nd or 3rd params in an option key.\n\n```js\nrequire('postcss-font-magician')({\n variants: {\n 'Open Sans': {\n '300 ultra-condenced': ['woff, eot, woff2'],\n '400 italic': ['woff2'],\n '400 italic semi-expanded': ['woff2']\n }\n }\n});\n```\n\n### font-display\n\nNeed to control how custom fonts display when they loading? You can use [font-display](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display) css rule. \n\n```js\nrequire('postcss-font-magician')({\n display: 'swap'\n});\n```\n\n### hosted\n\nHave a directory of self-hosted fonts?\n\n```js\nrequire('postcss-font-magician')({\n hosted: ['./src/fonts', /custom/path/to/fonts/on/site]\n});\n```\n\nThe directory will be scanned for font files, which will be read and automatically added if they are used in the document.\n\n**Please note** that at the moment the plugin doesn't detect woff2 fonts\n\nThe first argument of `hosted` array is required and it should be a path that related to the project root. i.e. `./src/fonts`\nIn this case, the path to the fonts folder structure must match the structure of the path to the fonts folder on the server, because the path will be relative css file.\n\nThe second argument of `hosted` array is optional and it can be an arbitrary path which should match the fonts directory on the site.\ni.e. `/assets/fonts`\n\n\n### aliases\n\nPrefer another name for particular fonts?\n\n```js\nrequire('postcss-font-magician')({\n aliases: {\n 'sans-serif': 'Source Sans Pro'\n }\n});\n```\n\nThe `@font-face` rule will be updated so that your alias key is the new name of the font family.\n\nYou can also use the 'aliases' option with other options, i.g with the 'variants'\n\n\n```js\nrequire('postcss-font-magician')({\n aliases: {\n 'sans-serif': 'Source Sans Pro'\n },\n variants: {\n 'sans-serif': {\n '400': ['woff']\n }\n }\n});\n```\n\n### async\n\nNeed to load the fonts asynchronously?\n\n```js\nrequire('postcss-font-magician')({\n async: 'path/to/your-fonts-async-loader.js'\n});\n```\n\nAny `@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.\n\n### formats\n\nWant to control which font formats are used?\n\n```js\nrequire('postcss-font-magician')({\n formats: 'woff2 woff'\n});\n```\n\nBy default, `local`, `woff2`, `woff`, and `eot` are enabled.\nSupported formats include `local`, `woff2`, `woff`, `ttf`, `eot`, `svg`, and `otf`.\n\n### foundries\n\nWant to enable specific foundries? Provide a space-separated list or array:\n\n```js\nrequire('postcss-font-magician')({\n foundries: 'bootstrap google'\n});\n```\n\nBy default, all foundries are enabled.\nSupported foundries include `custom`, `hosted`, `bootstrap`, and `google`.\n\n### custom\n\nNeed something very specific? I can do that, too.\n\n```js\nrequire('postcss-font-magician')({\n custom: {\n 'My Special Font': {\n variants: {\n normal: {\n 400: {\n url: {\n woff2: 'path/to/my-body-font-normal-400.woff2',\n woff: 'path/to/my-body-font-normal-400.woff'\n }\n },\n 700: {\n url: {\n woff2: 'path/to/my-body-font-normal-700.woff2'\n }\n }\n },\n italic: {\n 400: {\n url: {\n woff2: 'path/to/my-body-font-italic-400.woff2'\n }\n }\n }\n }\n }\n }\n});\n```\n\n### protocol\n\nDo you want to control the font URL-address protocol?\n\n```js\nrequire('postcss-font-magician')({\n protocol: 'https:'\n});\n```\n\nBy default, 'http/https' protocol is removed from the font url.\nSupports any string values, eg - '', 'http:' or 'https:'\n\n## Ignore\n\nIf you don't need Font Magician in some part of your CSS, you can use control comments to disable it.\n\n```css\n\nbody {\n /* font-magician: ignore next */\n font-family: \"Alice\"; /* will not generate font-face */ \n}\n```\n\n## Future\n\nLook forward to more magic, like:\n\n- Support for the TypeKit foundry.\n- Option to warn you when unmatched typefaces are used.\n\nEnjoy!\n\n[ci]: https://travis-ci.org/jonathantneal/postcss-font-magician\n[ci-img]: https://travis-ci.org/jonathantneal/postcss-font-magician.svg\n[creating an issue]: https://github.com/jonathantneal/postcss-font-magician/issues\n[Font Magician]: https://github.com/jonathantneal/postcss-font-magician\n[Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss\n[Gulp PostCSS]: https://github.com/postcss/gulp-postcss\n[PostCSS]: https://github.com/postcss/postcss\n",
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments