fork-awesome-customizer/README.md

# Fork-Awesome customizer

This is a little hack that lets you generate custom Fork-Awesome builds with only a subset of icons.

![screenshot](screenshot.png)

## Dependencies

Mostly dependencies of the Fork-Awesome project:

- `ruby`, `bundle` (package may be named `ruby-bundler`)
- `node`, `npm`
- `bash`, `make`, `sed`, `head`, `cat`, `git`

## How to use it

1. Make sure you cloned this repository recursively, i.e. the `Fork-Awesome/` folder is not empty. 
   - You can fix that by running `git submodule init` and `git submodule update`
2. Run `./install.sh`. This should prepare the FA submodule for building the font.
3. Verify that files `wanted.all.ini`, `wanted.none.ini`, `fontcustom.yml` and `fontcustom.default.yml` have been created. 
   - You can update Fork-Awesome and these files at any time by running `./install.sh` again.
4. Copy either of the "wanted" templates to `wanted.ini`, and customize it as needed.
   - Lines starting with `#` will be excluded. 
   - The INI suffix is used only to make editors highlight it nicely, it's not really an INI file
   - You can even use a blank text file and just add the icons you want, with coments on `#` lines
   - Use the [FA icons page](https://forkawesome.github.io/Fork-Awesome/icons/) for reference.
5. Adjust `fontconfig.yml` if you wish to give your custom font a different name, or change the class prefix.
6. Run `./build.sh` to build your customized font.
7. Retrieve your output files from the `output/` directory.

## Using the font

The generated font should be compatible with the Fork-Awesome CSS. However, our CSS is different.

This version does not include any of the FA helper classes (like `fa-spin`), and you also don't need to use the `fa` class
to apply the font. Simply add the icon class, like `fa-star`, to your element, and the icon will appear in
its `::before` pseudo-element. This behavior is similar to fonts generated by fontello.

```html
<i class="icon-save"></i> abusing the italic element
```

```html
<div class="icon-save"> this works too</div>
```

Note that the icon does not include any spacing by default. If you want it, add it in your custom CSS, or include spaces
in your HTML (perhaps using `&nbsp;`).

Another way to add the icon to an element is by adding `data-icon="&#1234;"` where `&#1234;` is a character entity
code you copied from the preview HTML. This is a bit harder to use, but may be useful in some situations. You can also
use this method to sneak emoji or other characters into your pages as icons, but you have to html-encode them first.

```html
<i data-icon="&#x1F600;"></i> this is a grinning face emoji
```

--- EOF ---