# gitbook-plugin-fontsettings

> Fonts and colors themes settings the website for a better reading experience

Latest version **2.0.0** (published 2016-06-02) · Apache-2.0 license · 11.2K weekly downloads

## Install

```sh
npm install gitbook-plugin-fontsettings
pnpm add gitbook-plugin-fontsettings
yarn add gitbook-plugin-fontsettings
bun add gitbook-plugin-fontsettings
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2016-06-02 |
| First published | 2015-10-05 |
| Weekly downloads | 11.2K |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 16 |
| Maintainers | jpreynat, samypesse |

## Links

- npm: https://www.npmjs.com/package/gitbook-plugin-fontsettings
- Repository: https://github.com/GitbookIO/plugin-fontsettings
- Issues: https://github.com/GitbookIO/plugin-fontsettings/issues
- npm.io page: https://npm.io/package/gitbook-plugin-fontsettings

## Recent versions

- 2.0.0 (latest) — 2016-06-02
- 1.0.3 — 2016-04-12
- 1.0.2 — 2015-10-13
- 1.0.1 — 2015-10-13
- 1.0.0 — 2015-10-05

## README

# plugin-fontsettings

This plugin adds font settings button in the GitBook 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`.

---
_Source: https://npm.io/package/gitbook-plugin-fontsettings · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._