{"id":13656615,"url":"https://github.com/csstools/postcss-font-magician","last_synced_at":"2025-05-13T22:09:19.502Z","repository":{"id":35374197,"uuid":"39637252","full_name":"csstools/postcss-font-magician","owner":"csstools","description":"Magically generate all the @font-face rules","archived":false,"fork":false,"pushed_at":"2024-12-28T18:59:23.000Z","size":1133,"stargazers_count":1001,"open_issues_count":1,"forks_count":31,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-05-11T05:23:18.742Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/csstools.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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":"2015-07-24T14:03:12.000Z","updated_at":"2025-04-15T15:51:50.000Z","dependencies_parsed_at":"2024-04-13T21:27:47.521Z","dependency_job_id":"bdb3d55e-b9c7-49d6-8a27-b6a458bd9a74","html_url":"https://github.com/csstools/postcss-font-magician","commit_stats":{"total_commits":93,"total_committers":11,"mean_commits":8.454545454545455,"dds":0.5591397849462365,"last_synced_commit":"9563b3ec27ef659e78f44851c561c28b1eb0a185"},"previous_names":["jonathantneal/postcss-font-magician"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstools%2Fpostcss-font-magician","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstools%2Fpostcss-font-magician/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstools%2Fpostcss-font-magician/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstools%2Fpostcss-font-magician/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/csstools","download_url":"https://codeload.github.com/csstools/postcss-font-magician/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254013690,"owners_count":21999450,"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":[],"created_at":"2024-08-02T05:00:25.731Z","updated_at":"2025-05-13T22:09:19.446Z","avatar_url":"https://github.com/csstools.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Font Magician [![test](https://github.com/csstools/postcss-font-magician/actions/workflows/test.yml/badge.svg)](https://github.com/csstools/postcss-font-magician/actions/workflows/test.yml)\n\n\u003cimg align=\"right\" width=\"135\" height=\"95\" src=\"http://postcss.github.io/postcss/logo-leftp.png\" title=\"Philosopher’s stone, logo of PostCSS\"\u003e\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\tfont-family: \"Alice\";\n}\n\n/* after */\n\n@font-face {\n\tfont-family: \"Alice\";\n\tfont-style: normal;\n\tfont-weight: 400;\n\tsrc: local(\"Alice\"), local(\"Alice-Regular\"),\n\t\turl(\"http://fonts.gstatic.com/s/alice/v7/sZyKh5NKrCk1xkCk_F1S8A.eot?#\") format(\"eot\"),\n\t\turl(\"http://fonts.gstatic.com/s/alice/v7/l5RFQT5MQiajQkFxjDLySg.woff2\") format(\"woff2\"),\n\t\turl(\"http://fonts.gstatic.com/s/alice/v7/_H4kMcdhHr0B8RDaQcqpTA.woff\")  format(\"woff\"),\n\t\turl(\"http://fonts.gstatic.com/s/alice/v7/acf9XsUhgp1k2j79ATk2cw.ttf\")   format(\"truetype\")\n}\n\nbody {\n\tfont-family: \"Alice\";\n}\n```\n\n* Want to use **[Google Fonts](#foundries)**? I’ll add them for you.\n* Want to use **Material Icons**? \n```css\nbody {\n\tfont-family: \"Material Icons\";\n}\n```\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 postcss-font-magician --save-dev\n```\nor\n```sh\nyarn add postcss postcss-font-magician --dev\n```\n\n### Node\n\nUse [Font Magician] in your script:\n\t```js\n\tconst fs = require('fs');\n\tconst postcss = require('postcss');\n\tconst pfm = require('postcss-font-magician');\n\tpostcss([\n\t\tpfm({ /* options */ })\n\t]).process(\n\t\tfs.readFileSync('./css/src/style.css', 'utf8')\n\t).then(function (result) {\n\t\tfs.writeFileSync('./css/style.css', result.css);\n\t});\n\t```\n\n\n### Webpack\n\nUse [Font Magician] in your webpack.config.js:\n\n*Webpack 1.x*\n\n```js\n\tpostcss: function () {\n\t\treturn [\n\t\t\t...\n\t\t\tfontMagician({\n\t\t\t\t\tvariants: {\n\t\t\t\t\t\t\t'Roboto Condensed': {\n\t\t\t\t\t\t\t\t\t'300': [],\n\t\t\t\t\t\t\t\t\t'400': [],\n\t\t\t\t\t\t\t\t\t'700': []\n\t\t\t\t\t\t\t}\n\t\t\t\t\t},\n\t\t\t\t\tfoundries: ['google']\n\t\t\t})\n\t\t\t...\n\t\t];\n}\n```\n\n*Webpack 2.x*\n\n```js\nplugins: [\n\tnew webpack.LoaderOptionsPlugin({\n\t\toptions: {\n\t\t\t...\n\t\t\tpostcss: [\n\t\t\t\t...\n\t\t\t\tfontMagician({\n\t\t\t\t\tvariants: {\n\t\t\t\t\t\t'Roboto Condensed': {\n\t\t\t\t\t\t\t'300': [],\n\t\t\t\t\t\t\t'400': [],\n\t\t\t\t\t\t\t'700': []\n\t\t\t\t\t\t}\n\t\t\t\t\t},\n\t\t\t\t\tfoundries: ['google']\n\t\t\t\t})\n\t\t\t]\n\t\t},\n\t}),\n\t...\n]\n```\n\n*Webpack 3+*\n\n**postcss.config.js**\n```js\nmodule.exports = {\n\tplugins: {\n\t\t'postcss-font-magician': {\n\t\t\tvariants: {\n\t\t\t\t'Roboto Condensed': {\n\t\t\t\t\t'300': [],\n\t\t\t\t\t'400': [],\n\t\t\t\t\t'700': []\n\t\t\t\t}\n\t\t\t},\n\t\t\tfoundries: ['google']\n\t\t}\n\t}\n}\n```\n\n**webpack.config.js**\n```js\n{\n\tloader: 'postcss-loader',\n\toptions: {\n\t\tconfig: {\n\t\t\tpath: 'path/to/postcss.config.js'\n\t\t}\n\t}\n}\n```\n\n### Grunt\n\nUse [Font Magician] in your Gruntfile:\n```js\ngrunt.loadNpmTasks('grunt-postcss');\n\ngrunt.initConfig({\n\tpostcss: {\n\t\toptions: {\n\t\t\tprocessors: [\n\t\t\t\trequire('postcss-font-magician')({ /* options */ })\n\t\t\t]\n\t\t},\n\t\tsrc: './css/src/*.css',\n\t\tdest: './css'\n\t}\n});\n```\n\n### Gulp\n\nUse [Font Magician] in your Gulpfile:\n```js\nvar postcss = require('gulp-postcss');\n\ngulp.task('css', function () {\n\treturn gulp.src('./css/src/*.css').pipe(\n\t\tpostcss([\n\t\t\trequire('postcss-font-magician')({ /* options */ })\n\t\t])\n\t).pipe(\n\t\tgulp.dest('./css')\n\t);\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\tvariants: {\n\t\t'Open Sans': {\n\t\t\t'300': ['woff, eot, woff2'],\n\t\t\t'400 italic': ['woff2']\n\t\t}\n\t}\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 both the names of the subsets of Google fonts (e.g. 'latin-ext' or 'cyrillic') and specific unicode ranges values. You can use it as a second element in an option array.\n\n```js\nrequire('postcss-font-magician')({\n\tvariants: {\n\t\t'Open Sans': {\n\t\t\t'300': ['woff2', 'cyrillic-ext, greek'],\n\t\t\t'400 italic': ['woff2', 'U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF']\n\t\t}\n\t}\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\tvariants: {\n\t\t'Open Sans': {\n\t\t\t'300 ultra-condensed': ['woff, eot, woff2'],\n\t\t\t'400 italic': ['woff2'],\n\t\t\t'400 italic semi-expanded': ['woff2']\n\t\t}\n\t}\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\tdisplay: 'swap'\n});\n```\n\n### hosted\n\nHave a directory of self-hosted fonts?\n\n```js\nrequire('postcss-font-magician')({\n\thosted: ['./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\taliases: {\n\t\t'sans-serif': 'Source Sans Pro'\n\t}\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\taliases: {\n\t\t'sans-serif': 'Source Sans Pro'\n\t},\n\tvariants: {\n\t\t'sans-serif': {\n\t\t\t'400': ['woff']\n\t\t}\n\t}\n});\n```\n\n### async\n\nNeed to load the fonts asynchronously?\n\n```js\nrequire('postcss-font-magician')({\n\tasync: '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\tformats: '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\tfoundries: '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\tcustom: {\n\t\t'My Special Font': {\n\t\t\tvariants: {\n\t\t\t\tnormal: {\n\t\t\t\t\t400: {\n\t\t\t\t\t\turl: {\n\t\t\t\t\t\t\twoff2: 'path/to/my-body-font-normal-400.woff2',\n\t\t\t\t\t\t\twoff: 'path/to/my-body-font-normal-400.woff'\n\t\t\t\t\t\t}\n\t\t\t\t\t},\n\t\t\t\t\t700: {\n\t\t\t\t\t\turl: {\n\t\t\t\t\t\t\twoff2: 'path/to/my-body-font-normal-700.woff2'\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\titalic: {\n\t\t\t\t\t400: {\n\t\t\t\t\t\turl: {\n\t\t\t\t\t\t\twoff2: 'path/to/my-body-font-italic-400.woff2'\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n});\n```\n\n### protocol\n\nDo you want to control the font URL-address protocol?\n\n```js\nrequire('postcss-font-magician')({\n\tprotocol: '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\t/* font-magician: ignore-next */\n\tfont-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[creating an issue]: https://github.com/csstools/postcss-font-magician/issues\n[Font Magician]: https://github.com/csstools/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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsstools%2Fpostcss-font-magician","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcsstools%2Fpostcss-font-magician","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsstools%2Fpostcss-font-magician/lists"}