Iosevka 33.1.0

Building Iosevka from Source

Getting the files

To make the font, first you need to have the files that contain the repository’s source code. Here are two ways:

Building

To build Iosevka you should:

  1. Install nodejs (≥ 18.0.0) and ttfautohint. Make sure that they are accessible from PATH environment variable.
  2. Open a CLI shell in a terminal, cd into the directory containing Iosevka source code.
  3. Run npm install. This command will install all the NPM dependencies.
  4. Run npm run build -- contents::Iosevka. This command will build your fonts.

You will find TTFs, as well as WOFF(2) web fonts and one Webfont CSS in the dist/ directory.

To using Docker build, read docker/README.md.

Customized Build

To create a custom build, you need:

  1. Create private-build-plans.toml file if absent, place alongside the build-plans.toml in the repository.

  2. Add a build plan into private-build-plans.toml. The configurable properties are described in the following sections.

  3. Run npm run build -- contents::<your plan name> and the built fonts would be available in dist/. Aside from contents::<plan>, other options are:

    1. contents::<plan> : Everything (TTF + webfont, hinted + unhinted);
    2. ttf::<plan> : TTF only;
    3. ttf-unhinted::<plan> : Unhinted TTF only;
    4. webfont::<plan> : Web fonts only (CSS + WOFF2);
    5. webfont-unhinted::<plan> : Unhinted web fonts only (CSS + WOFF2);
    6. woff2::<plan> : WOFF2 only.
    7. woff2-unhinted::<plan> : Unhinted WOFF2 only.

⚠️ Important: By default, the build system will schedule a number of concurrently running jobs equal to the number of threads available on the CPU, which will push CPU usage and also likely RAM usage, if you do not have very much to work with, to the ceiling (each job consumes more than 1 GB of RAM at its peak). If this is an issue for you, pass an additional argument --jCmd=<number of concurrent jobs>.

Configuring Custom Build

Configuration of build plans are organized under [buildPlans.<plan name>] sections in the private-build-plans.toml. You can use the Customizer to create the build plan, and/or manually edit them, following the instructions below. It is recommended to use PascalCase in the plan names.

Inside the plan, top-level properties include:

Build plan could have 9 optional subsections: * ligations * variants * weights * widths * slopes * compatibilityLigatures * excludeChars * metricOverride * namingOverride

Configuring Ligations

Subsection ligations is used to customize the ligation set assigned to calt OpenType feature. Properties include:

Configuring Character Variants

Subsection variants is used to configure character variants in the font. Properties include:

Configuring Weights, Widths and Slopes

Subsection weights is used to change the weight grades that the custom family needs. It is a dictionary from the filename suffix (in PascalCase) to either…

Subsection widths is used to change the width grades that the custom family needs. It is a dictionary from the filename suffix (in PascalCase) to either…

Subsection slopes is used to change the slope angles and grades that the custom family needs. It is a dictionary from the filename suffix (in PascalCase) to either…

In addition to list all the weights/widths/slopes directly, the user could also configure the weights/widths/slopes list using “inherits” to inherit the list from another build plan:

[buildPlans.IosevkaCustom2]
family = "Iosevka Custom 2"

weights.inherits = "buildPlans.IosevkaCustom1" # Inherit weights list from "IosevkaCustom1"
widths.inherits = "buildPlans.IosevkaCustom1"  # Inherit widths list from "IosevkaCustom1"
slopes.inherits = "default"  # Inherit slopes list from default

Compatibility Ligatures

Certain software, notably Emacs, relies on pre-encoded ligatures instead of OpenType to provide ligations. Iosevka could be configured with additional subsection compatibilityLigatures, being an array of records with following fields:

A sample of compatibility ligature config is:

[[buildPlans.IosevkaCustom.compatibilityLigatures]]
unicode = 57600 # 0xE100
featureTag = 'calt'
sequence = '<*>'

Excluding Characters

Use the excludeChars configuration to exclude character ranges from the font.

[buildPlans.iosevkaCustom.excludeChars]
ranges = [[10003, 10008]]

Metric Override

Subsection metricOverride provides ability to override certain metric values, if you reallly want to. Adding this section is strongly discouraged as it may introduce broken geometry or broken shapes.

Property Unit Default Value Meaning
cap emu 735 Height of H.
ascender emu 735 Height of b.
xHeight emu 520 Height of x.
sb emu (varies, 60 for Regular) Width of common side-bearings.
accentWidth emu 200 Width of accent marks.
accentClearance emu 72 Vertical clearance of accent marks to the base.
accentHeight emu 176 Height of accent marks.
accentStackOffset emu 220 Offset height of accent mark stack.
dotSize emu (varies, 125 for regular) Size of dots in diacritic marks.
periodSize emu (varies, 140 for regular) Size of dots in period.
leading emu 1250 Built-in line height.
symbolMid emu 340 Height of the center of hyphen (-).
parenSize emu 966 Height of Parentheses.
winMetricAscenderPad emu 0 Additional pad for Win metrics’ ascender to avoid clipping in legacy Windows applications.
winMetricDescenderPad emu 0 Additional pad for Win metrics’ descender to avoid clipping in legacy Windows applications.
powerlineScaleX, powerlineScaleY (ratio) 1 X and Y scale of Powerline glyphs.
powerlineShiftX, powerlineShiftY emu 0 X and Y shift of Powerline glyphs.
onumZeroHeightRatio (ratio) 1.145 Ratio of height of 0 under onum feature, to the height of x.
essRatio (ratio) (varies, 1.12 for Regular) Ratio of the thickness of the neck of S/s/?, to the normal stroke width. essRatioUpper, essRatioLower and rssRatioQuestion will override this value for corresponded glyph categories when set.
essRatioUpper (ratio) (varies, 1.12 for Regular) Ratio of the thickness of the neck of S, to the normal stroke width.
essRatioLower (ratio) (varies, 1.12 for Regular) Ratio of the thickness of the neck of s, to the normal stroke width.
essRatioQuestion (ratio) (varies, 1.12 for Regular) Ratio of the thickness of the neck of ?, to the normal stroke width.
archDepth emu (varies, 195 for Regular) Depth of the curve segment of arches / O rings in capital letters.
smallArchDepth emu (varies, 200 for Regular) Depth of the curve segment of arches / O rings in small letters.
advanceScaleSp (ratio) (varies, 1.0 for monospace, 0.58333 for quasi-proportional) The advance width ratio of space character, relative to the width of digit 0.

The values of each item could be either a number, or a string representing an expression so that it could be different for different instance fonts, or depending on default values. The syntax of valid expressions are:

Expression -> Term (('+' | '-') Term)*
Term       -> Factor (('*' | '/') Factor)*
Factor     -> ('+' | '-')* Primitive
Primitive  -> Literal
            | Call
            | Binding
            | Group
            | List
Literal    -> ['0'..'9']+ ('.' ['0'..'9']+)?
Identifier -> ['A'..'Z', 'a'..'z', '_']+
Call       -> Identifier '(' Expression (',' Expression)* ')'
List       -> Identifier '[' Expression (',' Expression)* ']'
Binding    -> Identifier

Valid identifiers include: * weight: being the weight grade; * width: being the characters’ unit width, measured in em-units; * slopeAngle: being the slope angle in degrees; * Default value of all overridable metrics, prefixed with default_, i.e., default cap value will be accessable thorugh default_cap.

Valid functions include: * blend(x, [x1, y1], [x2, y2], …): Perform a smooth interpolation through data pairs [x1, y1], [x2, y2], …, against parameter x.

For example, the following configuration:

[buildPlans.IosevkaCustom.metricOverride]
leading = 1500
sb = 'default_sb * 1.0625 + 15'
dotSize = 'blend(weight, [100, 50], [400, 125], [900, 180])'

will:

Naming Override

The properties in the namingOverride section could be uase to override menu names of the produced font. The following properties will be applied to the font directly:

Additionally, the namingOverride section now supports a menuNameMap configuration property. This property allows for the customization of menu names based on specific attributes related to the font’s style and characteristics. The menuNameMap configuration is structured as follows:

You are allowed to provide override names only for the values that you want to have custom names. Any values not specified in these mappings will use the default names.

For example, the following configuration:

[buildPlans.IosevkaCustom.namingOverride.menuNameMap.width]
7 = "Expanded"
[buildPlans.IosevkaCustom.namingOverride.menuNameMap.widthShort]
7 = "Exp"

… will name width 7 to “Expanded” in full, and “Exp” in short.

Sample Configuration

A sample configuration could be found at private-build-plans.sample.toml.

TTC Building

It is possible to create a customized TTC build by using the following method:

  1. Add a collect plan into private-build-plans.toml, with a from field containing all the TTF groups it needs:
[collectPlans.IosevkaCustom]
from = ["IosevkaCustom1", "IosevkaCustom2"]
  1. Run build with the following command:

Baking other OpenType features

There are tools tha could be used to bake other OpenType that are not configurable with TOML files (like baking localized forms). The tools include:

These tools could be used in post-processing fonts. Please refer their documents for instructions.