{"id":42847,"library":"hexo-tiny","title":"hexo-iconify","description":"Hexo plugin providing two methods to use the entire 100,000+ icon set from Iconify: inline SVG via the `icon()` helper and CSS mask-image via the `icons()` helper. Current stable version 1.0.0. Requires `@iconify/json`, `@iconify/utils`, and `hexo-fs` (bundled with Hexo). Designed for Hexo blogs; the `icons()` helper injects SVG data URLs into a specified CSS file at build time, avoiding runtime requests. Replaces earlier approaches like `hexo-iconify-beta` and focuses on simplicity and zero runtime overhead.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","hexo","minifier","optimization","html"],"install":[{"cmd":"npm install hexo-tiny","lang":"bash","label":"npm"},{"cmd":"yarn add hexo-tiny","lang":"bash","label":"yarn"},{"cmd":"pnpm add hexo-tiny","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides icon collection data (required for both helpers)","package":"@iconify/json","optional":false},{"reason":"Utility functions for icon parsing and SVG generation (required for both helpers)","package":"@iconify/utils","optional":false},{"reason":"File system operations used to write generated CSS; Hexo bundles it natively","package":"hexo-fs","optional":true}],"imports":[{"note":"Requires full Iconify icon name with collection prefix (e.g., 'ant-design:...'). Works as a Hexo helper in templates.","wrong":"icon('home-outlined')","symbol":"icon","correct":"icon('ant-design:home-outlined')"},{"note":"Second argument is the CSS file relative to theme source. The plugin appends icon definitions to this file. Both `icon` and `icons` are registered as Hexo helpers.","wrong":"icons('home-outlined', 'style.css')","symbol":"icons","correct":"icons('ant-design:home-outlined', 'style.css')"},{"note":"Do not require/import in theme scripts; helpers are injected by Hexo upon plugin install.","wrong":"const iconify = require('hexo-iconify')","symbol":"default import","correct":"// Not needed; helpers are automatically registered in Hexo"}],"quickstart":{"code":"1. Install dependencies:\nnpm install hexo-iconify @iconify/json @iconify/utils\n\n2. In your Hexo theme's layout file (e.g., layout.ejs):\n<span class=\"menu-icon\"><%- icon('ant-design:home-outlined') %></span>\n\n3. In your Hexo theme's CSS file (e.g., main.css), add base styles:\n.icons {\n  display: inline-block;\n  width: 1em;\n  height: 1em;\n  vertical-align: -.15em;\n  background-color: currentcolor;\n  mask: no-repeat center / 100%;\n  mask-image: var(--svg);\n}\n\n4. In your template, use 'icons' helper with CSS file path:\n<span class=\"<%- icons('ph:magnifying-glass', 'css/main.css') %>\"></span>\n\n5. Optionally set default CSS file in root _config.yml:\niconify:\n  file: 'css/main.css'\n\n6. Run hexo generate to see icons injected.","lang":"javascript","description":"Install hexo-iconify, then use icon() for inline SVG or icons() for CSS mask-image icons in Hexo themes."},"warnings":[{"fix":"Rename conflicting helpers or avoid using those names in your theme.","message":"Plugin registers helpers named 'icon' and 'icons' – conflicts if theme or other plugins already use these names.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Upgrade to hexo-iconify@1.0.0 and update helper usage.","message":"Older version 'hexo-iconify-beta' may have different API; this plugin replaces it.","severity":"deprecated","affected_versions":"<1.0.0"},{"fix":"Always provide the full name with colon separator, e.g., 'ph:magnifying-glass'.","message":"The icon name must include the collection prefix (e.g., 'ant-design:home-outlined'); omitting the prefix will cause errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Provide the file path or set `iconify.file` in root config.","message":"The 'icons' helper's second argument (CSS file path) is required unless a default is set in _config.yml.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Base class must be defined before the auto-generated rules, and avoid modifying the appended `--svg` rules.","message":"The plugin modifies the specified CSS file at build time – do not edit the auto-generated portions.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'000':14 '1.0.0':37 '100':13 'approach':72 'avoid':67 'beta':77 'blog':51 'build':65 'bundl':45 'css':26,62 'current':34 'data':57 'design':48 'earlier':71 'entir':12 'file':63 'focus':79 'fs':44 'helper':24,33,54 'hexo':2,4,43,47,50,75,87 'hexo-f':42 'hexo-iconifi':1 'hexo-iconify-beta':74 'html':90 'icon':15,23,32,53 'iconifi':3,18,76 'iconify/json':39 'iconify/utils':40 'imag':29 'inject':55 'inlin':19 'javascript':86 'like':73 'mask':28 'mask-imag':27 'method':8 'minifi':88 'optim':89 'overhead':85 'plugin':5 'provid':6 'replac':70 'request':69 'requir':38 'runtim':68,84 'set':16 'simplic':81 'specifi':61 'stabl':35 'svg':20,56 'time':66 'two':7 'url':58 'use':10 'version':36 'via':21,30 'zero':83","created_at":"2026-06-05T16:56:57.448091+00:00","updated_at":"2026-06-05T16:56:57.448091+00:00","problems":[{"fix":"Verify the collection prefix and icon name; use https://icones.netlify.app to find valid names.","cause":"Icon name is not in @iconify/json","error":"Missing local icon \"fa-solid:home\""},{"fix":"Run `npm install @iconify/json` in your project root.","cause":"@iconify/json is not installed","error":"Cannot find module '@iconify/json'"},{"fix":"Run `npm install @iconify/utils` in your project root.","cause":"@iconify/utils is not installed","error":"Cannot find module '@iconify/utils'"},{"fix":"Set `iconify.file: 'path/to/your.css'` in _config.yml or pass file path as second argument.","cause":"No default CSS file set and 'icons' helper called without second argument","error":"iconify.file is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"hexo-tiny","openapi_spec":null,"status_page":null,"smithery":null,"categories":["ecommerce","productivity"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}