Iosevka 16.4.0

Building Iosevka from Source

Cloning

Note that this repo has a 30+ GB commit history. If you only want the current files and future changes, you can avoid downloading so much by cloning the repo with a --depth limit. Example:

git clone --depth 1 https://github.com/be5invis/Iosevka.git 

Building

To build Iosevka you should:

  1. Ensure that nodejs (≥ 14.0.0) and ttfautohint are present, and accessible from PATH.
  2. Run npm install. This command will install all the NPM dependencies, and will also validate whether external dependencies are present.
  3. npm run build -- contents::iosevka.

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

Using a Docker container

A Docker container handling the build environment for you can be found here.

To pull it from Docker Hub and start a standard build of the latest released version, run

docker run -it -v $(pwd):/build avivace/iosevka-build

If you are using Powershell, run

docker run -it -v ${pwd}:/build avivace/iosevka-build

Fonts files will be placed in the dist folder.

You can provide private-build.plans.toml for a customized build and/or specify the desired release appending -e FONT_VERSION=X.X.X. to the Docker command.

Customized Build

To create a custom build, you need:

  1. Create private-build-plans.toml file if absent.

  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.

Inside the plan, top-level properties include:

Build plan could have 5 optional subsections: ligations, variants, weights, widths and slopes.

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 of either strings formatted in default.<weight> format, meaning reusing a default weight grade, or sub-objects with properties:

Subsection widths is used to change the width grades that the custom family needs. It is a dictionary of either strings formatted in default.<width> format, meaning reusing a default width grade, or sub-objects with properties:

Subsection slopes is used to change the slope angles and grades that the custom family needs. It is a dictionary of either strings formatted in default.<slope> format, meaning reusing a default slope grade, or sub-objects with properties:

Subsection slopes is a simple string-to-string dictionary maps slopes (upright, italic or oblique) to CSS font-style values, represented in string.

Compatibility Ligatures

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

A sample of compatibility ligature config is:

[[buildPlans.iosevka-custom.compatibility-ligatures]]
unicode = 57600 # 0xE100
featureTag = 'calt'
sequence = '<*>'

Metric Override

Subsection metric-override 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.

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.iosevka-custom.metric-override]
leading = 1500
sb = 'default_sb * 1.0625 + 15'
dotSize = 'blend(weight, [100, 50], [400, 125], [900, 180])'

will:

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.iosevka-custom]
from = ["iosevka-custom1", "iosevka-custom-2"]
  1. Run build with the following command: