# Customization

# Webshell Configuration Guide

Per-user web terminal preferences are stored in `~/.config/webshell/`.

---

## Directory Structure

```text
~/.config/webshell/
├── config.json      # Theme, font size, and cursor settings
└── fonts/           # Dir for local fonts
    └── font.woff2   # (Optional) Local custom font file (.woff2, .ttf, or .otf)
```

---

## `config.json` Options

| Key | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `fontFamily` | String | `'JetBrains Mono', monospace` | Font family stack |
| `fontSize` | Number | `15` | Font size in pixels |
| `cursorStyle` | String | `"block"` | Cursor shape (`"block"`, `"underline"`, or `"bar"`) |
| `cursorBlink` | Boolean | `true` | Enable or disable cursor blinking |
| `theme` | Object | *See below* | Color palette overrides |

---

## Theme Options (`theme` object)

| Key | Description |
| :--- | :--- |
| `background` | Terminal background color (e.g. `"#000000"`) |
| `foreground` | Default text color (e.g. `"#e0e0e0"`) |
| `cursor` | Cursor color (e.g. `"#ffffff"`) |
| `black` – `white` | Standard 8 ANSI colors |
| `brightBlack` – `brightWhite` | High-intensity 8 ANSI colors |

---

## Example `~/.config/webshell/config.json`

```json
{
  "fontFamily": "'JetBrains Mono', 'Fira Code', monospace",
  "fontSize": 15,
  "cursorStyle": "block",
  "cursorBlink": true,
  "theme": {
    "background": "#000000",
    "foreground": "#e0e0e0",
    "cursor": "#00ff00",
    "green": "#00ff00",
    "cyan": "#00ffff"
  }
}
```

------

# Using Local Font Files

## Location

Place your font file in `~/.config/webshell/` as one of the following:

* `font.woff2` *(Create your own if needed! See below)*
* `font.ttf`
* `font.otf`

The webshell will automatically encode and load your font file into the web browser upon login.

## Determining Font Family Name from a Font File

fc-scan will return the font family name for you. It is possible to return multiple aliases so you can use the first one to simplify the process.

```bash
$ fc-scan GoogleSansCodeNerdFontMono-SemiBoldItalic.ttf --format "%{family}\n" | cut -d, -f1
GoogleSansCode Nerd Font Mono
```

## Use woff2 files instead of ttf or otf

These are normal font files, but compressed so it will be nicer for web use:

```shell
# one at a time
for f in *.ttf *.otf; do woff2_compress "$f"; done
# use all those cores!
parallel woff2_compress ::: *.[ot]tf
```

On 181 of my fonts the size dropped from 381M to 220M.