Collecticons processor 
Processor script for collecticons icon library.
This utility is meant to be used to generate webfont (woff, woff2) and style files (css, sass) from the collecticons icon library.
Install the module as a global dependency.
npm install -g collecticons-processor
Usage
The script has 2 commands explained below.
$ collecticons
Usage: collecticons [options] [command]
Options:
-v, --verbose increase verbosity
--quiet disable all output
-V, --version output the version number
-h, --help output usage information
Commands:
compile [options] <source-folder> Compile the font from svg icons
bundle <source-folder> <destination-file> Compile the font outputting a zip file. Contains all the used icons, stylesheet and preview.
Compile
Compiles the font and the style files.
$ collecticons compile --help
Usage: compile [options] <source-folder>
Compile the font from svg icons
Options:
--font-name <name> name of the font (default: "collecticons")
--font-types <val> font types to output (woff,woff2) (default: ["woff2"])
--font-dest <val> outputs font files to given destination. Output disabled by default. Using this disables font embed
--author-name <val> name of the author
--author-url <val> url of the author
--class-name <name> class name to use (default: "collecticon")
--style-name <name> name for for the style file (default: "icons")
--style-formats <val> style formats to output (sass,css) (default: ["sass"])
--style-dest <val> destination folder for the style files (default: "collecticons/styles/")
--no-sass-placeholder disable the sass placeholder
--no-css-class disable the css standalone classes
--preview-dest <dest> destination folder for the preview (default: "collecticons/")
--no-preview disable the preview
--rescale normalize icons by scaling them to the height of the highest icon
--catalog-dest <dest> destination folder for the catalog. Output disable by default
--experimental-font-on-catalog includes the base64 string of the fonts on the catalog. Experimental feature, may change at anytime
--experimental-disable-styles disabled the style output. Experimental feature, may change at anytime
-h, --help output usage information
By default everything will be output to a collecticons/ folder. It includes a sass file with an embedded woff2 font and a preview to view the exported icons.
$ collecticons compile source/
Result:
collecticons/
- styles/
- icons.scss
- preview.html
It is possible to change all the paths through options:
$ collecticons compile source/ --no-preview --style-dest assets/styles
Font embed
By default the sass/css files will have an embedded woff2 font. This can be disabled and use font files instead with the --font-dest <dest> parameter. This parameter expects a destination where to store the fonts. The font inclusion in the css file will point to this path.
$ collecticons compile source/ --no-preview --style-dest assets/styles --font-dest assets/fonts
Font types
The --font-types flag allows you to limit the output formats to particular types. Only woff and woff2 are supported.
$ collecticons compile source/ --font-types woff2,woff
SASS vs CSS
The script can output both sass and css formats but they have significant differences in the way they are structured.
By default only the sass file is created, but this can be changed with --style-formats:
$ collecticons compile source/ --style-formats sass,css
SASS placeholders vs CSS classes
When outputting the style in sass format, the script will by default include both sass placeholders and css classes. The output can be modified with --no-sass-placeholder and --no-css-class. Important to note that they can't both be disabled, and these flags are not valid for css output.
SASS
%collecticon,
[class^="collecticon-"],
[class*=" collecticon-"] {
font-family: "collecticons";
// ...
}
.collecticon-add:before {
content: "\EA01"
}
%collecticon-add {
@extend %collecticon;
content: "\EA01"
}Placeholders don't make any assumption to what pseudo selector is used (before or after) therefore some semantic styling is required.
<button class="bttn-add">Add</button>.bttn-add:before { // or .bttn-add:after {
@extend %collecticon-add;
}Using this approach allows the usage of up to two icons per element (one per selector).
CSS
[class^="collecticon-"],
[class*=" collecticon-"] {
font-family: "collecticons";
/* ... */
}
.collecticon-add:before {
content: "\EA01"
}You can place Collecticons just about anywhere using the respective CSS class. The icon library is designed to be used with inline elements (we like the <i> tag for brevity, but using a <span> is more semantically correct).
<button><i class="collecticon-add"></i> Add</button>Bundle
Creates a zip file with the fonts, css styles, and the icons. Used to prepare the library for distribution.
$ collecticons bundle -h
Usage: bundle [options] <source-folder> <destination-file>
Compile the font outputting a zip file. Contains all the used icons, stylesheet and preview.
Options:
-h, --help output usage information
Example:
$ collecticons bundle source/ destination.zip
Programmatic API
Both collecticons functions can be used programmatically.
const { compile, bundle } = require('../src');
compile(params)
Compiles the collecticons font and associated styles, catalog and preview files.
params.dirPath
Source path for the svg icons.
params.fontName
Font name. Default: collecticons
params.fontTypes
List of fonts to create. Default to [woff2]. Possible values [woff, woff2]
params.fontDest
If defined has to be a valid folder path and fonts will be output instead of embedded. Default undefined.
params.authorName
Author name for meta information. Default Development Seed
params.authorUrl
Author url for meta information. Default https://developmentseed.org/
params.className
Class name for SASS and CSS files. Default collecticons
params.styleName
Style file name. scss and css extensions will be using according to the generated file. Default icons
params.styleFormats
List of style files to create. Default to [sass]. Possible values [css, sass]
params.styleDest
Output destination for the style files. Default collecticons/styles/
params.sassPlaceholder
Whether or not to render sass placeholders. Only valid for sass style. Default true
params.cssClass
Whether or not to render css classes. Default true
params.previewDest
Output destination for the preview file. Default collecticons/
params.preview
Whether or not to render the preview file. Default true
params.rescale
Whether or not to normalize icons by scaling them to the height of the highest icon. Default false
params.catalogDest
If defined has to be a valid folder path and catalog will be output. Default undefined.
params.noFileOutput
If set to true a list of files and their content is returned instead of writing the files to disk. Default undefined.
params.experimentalFontOnCatalog
Includes the base64 string of the fonts on the catalog. Default undefined.
Experimental feature, may change at anytime.
params.experimentalDisableStyles
Disables the output of the style files. Default undefined.
Experimental feature, may change at anytime.
bundle(params)
Compiles the collecticons font and zips it. Contains all the used icons, stylesheet and preview.
params.dirPath
Source path for the SVG icons.
params.destFile
Destination of the zip file.
Contributing
You are free to contribute to the project. If you find a bug and/or have a nice idea about a feature feel free to open an issue or submit your own solution. See DEVELOPMENT.md for setup instructions. We'll be more than happy to hear your suggestions. :)
License
Collecticons is licensed under The MIT License (MIT), see the LICENSE file for more details.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent