DOCSEARCHbyAlgolia
Submit Docs

Maple Mono Font Documentation

repository·variable·Indexed 12 days ago

https://github.com/subframe7536/maple-font

An open-source monospace font for coding featuring variable font support, smart ligatures, Nerd Font icons, and robust CJK coverage (Simplified Chinese, Traditional Chinese, Japanese, and Korean). Includes documentation for the build.py CLI to customize weights, OpenType features, and CJK build configurations for version 8.0b1.

Tokens
25.9K
Snippets
70
Records
107
Agent score
93%

What's inside Maple Mono

  1. Overview of Maple Mono features

    variable

    Maple Mono is an open-source monospaced font designed for coding efficiency. Key features include:

    • Variable Font Support: Allows continuous weight adjustment and optimized italic glyphs.
    • Visual Improvements: Rounded design with redesigned characters like @ $ % & Q -> and improved italic ligatures (f i j k l x y).
    • Smart Ligatures: Includes numerous smart ligatures, character variants, OpenType style sets, and built-in label ligatures.
    • Extended Unicode Coverage: Supports box-drawing characters, braille, mathematical operators (U+2200–U+22FF), chess/card symbols, terminal status/progress symbols, and Claude Code loading symbols.
    • Nerd Font Integration: Standard integration of Nerd Fonts for terminal and developer tools.
    • High Customizability: Supports OpenType features, custom tag ligatures, line height, character width, and weight mapping via source builds.

  2. Overview of Maple Mono

    variable

    Maple Mono is an open-source monospaced font designed to improve coding comfort and efficiency.

    Key features include:

    • Variable Font Support: Continuous control over font weight and refined italic glyphs.
    • Visual Improvements: Rounded design, redesigned core symbols (e.g., @ $ % & Q ->), and improved italic connections (f i j k l x y).
    • Smart Ligatures: Enhanced smart ligatures, character variations, OpenType style sets, and status label ligatures.
    • Extended Unicode Support: Includes box-drawing characters, Braille, mathematical operators (U+2200–U+22FF), chess/card symbols, terminal status/progress symbols, and Claude Code status loading symbols.
    • Nerd Font Integration: Built-in support for Nerd Fonts icons.
    • High Customizability: Supports OpenType features, status label ligatures, line height, character width, and font weight mapping.

  3. Configure BuildPlan decisions

    variable

    The BuildPlan determines which assets are generated based on the following rules:

    DecisionRule
    Target stylesleast_styles selects Regular, Bold, Italic, and BoldItalic; debug selects Regular and Italic; otherwise all styles are eligible.
    Base formatsVariable is always required. TTF is required for requested TTF/WOFF2 or hinted consumers. OTF is added only when requested and the build is not debug.
    WOFF2Built only when requested and not in debug mode, from static TTF output in fonts/TTF/ into fonts/Woff2/.
    Nerd FontBuilt when nerd_font.enable is true; debug resolution disables it.
    CJK modeNone when no locale is selected; otherwise the configured static or variable mode.
    CJK profilesNF is selected when the NF stage is available and with_nerd_font is true; plain is added when NF is unavailable or cjk-both is enabled.
    CleanupIf TTF is not requested, remove fonts/TTF/ and fonts/TTF-AutoHint/ only after every consumer completes.
    ArchiveControlled by the resolved archive flag; processes existing non-JSON output directories at archive time.

  4. Customize OpenType feature handling

    variable

    OpenType features control built-in variants and ligatures. During the build process, you can specify how these features are handled for each feature set using three modes:

    1. enable: Forces the features to be enabled. Users do not need to manually set cvXX, ssXX, or zero tags; they behave like default ligatures.
    2. disable: Removes the features from cvXX, ssXX, and zero sets, making them impossible to enable manually.
    3. ignore: Keeps the default behavior without any processing.

  5. Understand the CJK build pipeline phases

    variable

    When building CJK fonts, the system executes several sequential phases:

    1. Source Resolution: Locating and loading the input font.
    2. Unicode Subsetting: Filtering the font to the required Unicode ranges.
    3. Master Preparation: Preparing the 100, 400, and 800 weight masters.
    4. Outline Normalization: Standardizing the outline data.
    5. Variable-Base Generation: Creating the base variable font structure.
    6. Optional Static Instantiation: Generating static font files if requested.
    7. Main-Pipeline Merging: Final assembly of the font components.

    Note on CFF2 Sources: If the source font uses the CFF2 outline format, it is automatically converted to compatible glyf masters before the variable or static merge work begins.

  6. Customize OpenType features during build

    variable

    You can control how OpenType features (ligatures and character variants) are handled during the build process. This is useful for forcing certain styles or removing them entirely to reduce configuration overhead in your editor.

    In config.json, you can set the handling mode for features to:

    1. enable: Forces the feature to be active (similar to default ligatures) without needing manual cvXX / ssXX / zero settings in your editor.
    2. disable: Removes the feature from the font entirely; it will not work even if manually enabled in your editor.
    3. ignore: Keeps the default behavior without any special processing.

  7. CJK Support in Maple Mono

    variable

    Maple Mono supports Chinese (Simplified/Traditional), Japanese, and Korean (CJK) character sets. In V8, CJK support is significantly expanded.

    To maintain alignment in Markdown tables and multi-language text, CJK characters are set to a 2:1 width ratio relative to Latin characters. Note that the default CJK character spacing is wider than typical Korean fonts.

    CJK Build Variants:

    RegionCoverageSourceBuild Output
    CNSimplified Chinese, common Traditional/Japanese charactersWenYuan Rounded SCCN
    TCTraditional ChineseChiron Go Round TCTC
    JPJapaneseResource Han Rounded JPJP
    KRKoreanChiron Go Round TC (Korean range)KR

    Note: CJK builds are disabled by default. You can configure target regions, static or variable outputs, and optional compressed spacing in the CJK build settings.

  8. Understand the CJK static merge resolution order

    variable

    When performing a main-pipeline static merge, the system attempts to resolve sources in the following priority order:

    1. Valid local static directory: Uses existing styles if the directory and its static-<locale>.sha256 digest are valid.
    2. Valid local static archive: Extracts <locale>-base-static.zip if the directory is unavailable.
    3. Remote static archive: Downloads and validates a supported release archive if local options fail.
    4. Local variable bases: Instantiates static styles from existing regular/italic variable files (if clean_cache is false).
    5. Valid local variable archive: Installs <locale>-base-variable.zip if variable files are missing.
    6. Remote variable archive: Downloads and validates a matching cjk-base variable archive.
    7. Source rebuild: Rebuilds regular and italic variable bases from source (vf_only=True) as a last resort.

    If all sources fail, the system raises a CJKBaseUnavailable error.

  9. Enable Maple Mono ligatures via calt

    variable

    Maple Mono supports various programming ligatures (e.g., ==, !=, =>, &&, //). These are controlled by the OpenType calt (Contextual Alternates) feature. Enabling "ligatures" in your font settings is equivalent to enabling the calt feature.

    Common ligatures include:

    • Operators: ==, !=, !==, <=, >=, &&, ||
    • Arrows: ->, =>, >>, >>>
    • Comments/Tags: //, ///, /*, /**, [DEBUG], [INFO], [WARN], [ERROR], [TODO], [FIXME], [HACK]
    • Other: {{, }}, ..., ..
    <!-- Example of input characters and their resulting ligatures -->
:: -> <--
::: -> ..<
?: -> .= 
:? -> <-
:?> -> <~>
#_ -> [DEBUG]
#= -> [TRACE]
<< -> =<
>>> -> ===
&& -> >=
// -> :=

  10. Understand Maple Mono filename components

    variable

    Maple Mono filenames are constructed using a specific order: [Base Name][Feature Preset][Width][Style]. Feature and width suffixes are compact and are not separated by additional hyphens.

    Feature Presets

    • Default: No suffix (e.g., Maple Mono). Uses default glyph design and ligatures.
    • Ligatures disabled (NL): Disables default ligatures (e.g., MapleMonoNL-Regular.ttf).
    • --normal preset (Normal): Uses glyph designs closer to common programming fonts.
    • --normal with ligatures disabled (NormalNL): Combines both presets.

    Character Widths

    • Default: No suffix. Latin glyph target width is 600.
    • Narrow (NR): Target width of 550.
    • Slim (SL): Target width of 500.

    Example: The configuration --normal --no-liga --width narrow results in the filename MapleMonoNormalNLNR-Regular.ttf.

  11. Manage the build cache and avoid stale builds

    variable

    The build system uses an opt-in cache located at fonts/build-cache.json.

    Cache Mechanics:

    • A cache hit requires a match on stage identity, expected output paths, file existence, and file digests.
    • A cache miss does not clear the entire directory; it preserves unrelated files. For CJK misses, only the specific locale/profile record is removed.

    Important: When to bypass the cache Stage identities do not track the following:

    • Generator source code
    • Dependency versions
    • UFO outline contents
    • CJK base contents

    If you change any of these untracked inputs, you must run the build without the --cache flag to ensure the results are not incorrectly served from a stale cache.

  12. Understand the Maple Mono build lifecycle

    variable

    The build pipeline follows a deterministic sequence of stages to ensure consistent font outputs:

    1. Resolve inputs: Converts config.json and CLI flags into a ResolvedConfig object.
    2. Dry-run handling: If --dry is passed, the system prints the resolved configuration and exits.
    3. Plan creation: Constructs a BuildPlan that selects target styles, formats (WOFF2, Nerd Font, CJK), and archive policies.
    4. Base font compilation: Uses fontmake.py to prepare Designspace/UFO sources and compile Variable/TTF/OTF branches.
    5. Derived output generation: Consumes static TTF outputs to create AutoHinter TTFs and WOFF2 files. Nerd Font and CJK stages consume specific outputs based on their dependency policies.
    6. Finalization: Writes build-config.json at the start and rewrites it upon success. The fonts/build-cache.json is only updated after the entire pipeline succeeds.