# @honkit-plugin-fontsettings

`@honkit/honkit-plugin-fontsettings` is a fork of [Gitbook/plugin-fontsettings]@2.0.0.

This plugin adds font settings button in the HonKit website.

### Disable this plugin

This is a default plugin and it can be disabled using a `book.json` configuration:

```
{
    plugins: ["-fontsettings"]
}
```

### Configuration

This plugin can be configured in the `book.json`:

Default configuration is:

```js
{
    "pluginsConfig": {
        "fontsettings": {
            "theme": 'white', // 'sepia', 'night' or 'white',
            "family": 'sans', // 'serif' or 'sans',
            "size": 2         // 1 - 4
        }
    }
}
```

### Plugin API

This plugin exposes the following API to easily allow new themes to manage the plugin behavior.

All API functions are called using the prefix `gitbook.fontsettings.`, for instance `gitbook.fontsettings.enlargeFontSize()`.

#### Font manipulation

##### `gitbook.fontsettings.enlargeFontSize()`

Increases the font size of the document by one. Max value is `4`.

##### `gitbook.fontsettings.reduceFontSize()`

Decreases the font size of the document by one. Min value is `1`.

#### Font families

Each font family should be described as:

```js
var fontFamily = {
    config: 'sans',  // name of the font family in book.json for your theme
    text: 'Sans',    // display name of the font family in menu
    id: 0            // the id appended to the CSS class for this font-family
};
```

The `text` property will be used to display the font-family name in the fontsettings dropdown menu.

The `config` property allows you to let the users of your theme choose a default font family in their `book.json`. You will have to handle setting the chosen font family in your theme's frontend JavaScript.

For instance:

```json
// book.json
{
    plugins: ["my-theme"],
    pluginsConfig: {
        "my-theme": {
            "font-family": "sans"
        }
    }
}
```

```js
// my-theme.js
require('gitbook', function(gitbook) {
    var FONT_FAMILIES = [
        {
            config: 'sans',
            text: 'Sans',
            id: 0
        },
        {
            config: 'serif',
            text: 'Serif',
            id: 1
        }
    ];

    gitbook.events.on('start', function(e, config) {
        // Read configuration
        var themeConfig = config['my-theme'],
            defaultFont = themeConfig['font-family'];

        // Initialize new font families
        gitbook.fontsettings.setFamilies(FONT_FAMILIES);
        // Set to configured font-family
        gitbook.fontsettings.setFamily(defaultFont);
    });
});
```

The `id` property lets you define a specific id to use for your CSS rules as explained below.

##### CSS rules

The CSS class `font-family-<id>` will be applied to the theme book's root element `<div class="book">` when a font family is selected in the menu.

The CSS rules for the font-family can then easily be defined using the parent selector `.book.font-family-<id>`:

```CSS
.book.font-family-<id> {
  font-family: 'My Awesome Font';
}
```

##### Managing the font families

##### `gitbook.fontsettings.getFamilies()`

Returns the currently set font families.

By default, the font families are:

```js
// Default font families
var FAMILIES = [
    {
        config: 'serif',
        text: 'Serif',
        id: 0
    },
    {
        config: 'sans',
        text: 'Sans',
        id: 1
    }
];
```

##### `gitbook.fontsettings.setFamilies()`

Set the new font families configuration, as an array of font family objects, used by the `plugin-fontsettings` in the form:

```js
var FONT_FAMILIES = [
    {
        config: 'sans',
        text: 'Sans',
        id: 0
    },
    {
        config: 'serif',
        text: 'Serif',
        id: 1
    }
];

gitbook.fontsettings.setFamilies(FONT_FAMILIES);
```

This will recreate the fontsettings menu to reflect the changes.

##### `gitbook.fontsettings.setFamily()`

Takes a font-family `config` key as an argument and updates the font-family used for this book.

This will basically apply the CSS class with the corresponding family `id`: `.font-family-<id>`.

#### Color themes

Setting and manipulating color themes follow the exact same rules as font families.

Here are the default value for the color themes in the plugin:

```js
// Default themes
var THEMES = [
    {
        config: 'white',
        text: 'White',
        id: 0
    },
    {
        config: 'sepia',
        text: 'Sepia',
        id: 1
    },
    {
        config: 'night',
        text: 'Night',
        id: 2
    }
];
```

##### CSS rules

The applied CSS classes for color themes will be in the form: `.color-theme-<id>`.

**Caution**: No CSS class for color theme with `id: 0` will be applied. Basically, the first color theme corresponds to your default theme's colors.

For instance, using the default color themes:

```js
gitbook.fontsettings.setTheme('night');
```

will result in the following HTML state for the root element:

```HTML
<div class="book color-theme-2">
```

While:

```js
gitbook.fontsettings.setTheme('white');
```

will reset the HTML state for the root element:

```HTML
<div class="book">
```

##### Managing the color themes

##### `gitbook.fontsettings.getFamilies()`

Returns the currently set color themes.

By default, the font families are:

```js
// Default themes
var THEMES = [
    {
        config: 'white',
        text: 'White',
        id: 0
    },
    {
        config: 'sepia',
        text: 'Sepia',
        id: 1
    },
    {
        config: 'night',
        text: 'Night',
        id: 2
    }
];
```

##### `gitbook.fontsettings.setThemes()`

Set the new color themes configuration, as an array of font family objects, used by the `plugin-fontsettings` in the form:

```js
var COLOR_THEMES = [
    {
        config: 'light',
        text: 'Light',
        id: 0
    },
    {
        config: 'dark',
        text: 'Dark',
        id: 1
    }
];

gitbook.fontsettings.setThemes(COLOR_THEMES);
```

This will recreate the fontsettings menu to reflect the changes.

##### `gitbook.fontsettings.setTheme()`

Takes a color theme `config` key as an argument and updates the color theme used for this book.

This will basically apply the CSS class with the corresponding theme `id`: `.color-theme-<id>`, or remove the applied CSS class if the selected theme `id` is `0`.

## License

Apache-2.0 (same as [Gitbook/plugin-fontsettings])

[Gitbook/plugin-fontsettings]: https://github.com/GitbookIO/plugin-fontsettings
[gitbook-tester]: https://github.com/todvora/gitbook-tester
[honkit-tester]: https://github.com/vowstar/honkit-tester