Settings

Settings of Prettify Symbols Mode (Continued). The README explains them in more detail; this page is a quick reference. All keys can also be set in the VS Code settings UI.

Global settings

• prettifySymbols.substitutions: array of language entries, see below.
• prettifySymbols.revealOn: when to show the original ("ugly") text. "cursor" (default), "cursor-inside", "active-line", "selection" or "none".
• prettifySymbols.prettyCursor: rendering of a symbol that is contacted by the cursor. "boxed" (default) displays a box outline, "none" does not change its appearance.
• prettifySymbols.adjustCursorMovement: if true, cursor movement treats each symbol as a single character. Defaults to false. This currently does not work for all kinds of cursor movement.
• prettifySymbols.insertionPosition: "before" (default) or "after". Where the "pretty" text is inserted relative to the original text; "before" avoids issues with syntax highlighting.
• prettifySymbols.hideTextMethod: "hack-letterSpacing" (default), "hack-fontSize" or "none". How the original text is hidden: with a negative letter spacing, by shrinking its font size, or not at all (the "pretty" text is shown next to it). Can be overridden per language entry.
• prettifySymbols.preserveAlignment: "off" (default), "comments" or "columns". Keeps text after shortened symbols at its column by inserting the width they lost (as spaces) directly before the next text after a run of spaces. "comments" keeps trailing comments aligned: it pads only the gap in front of a trailing comment (needs a TextMate grammar to detect comments), "columns" keeps every column aligned: it pads every gap of two or more spaces. Tabs are not supported.

Language entries

Each entry of prettifySymbols.substitutions has:

• language: the languages the entry applies to. Can be any of
  1. a language identifier as defined by VS Code and the extensions you have installed (e.g. "ocaml", "fsharp", "plaintext"),
  2. a DocumentFilter, composed of one or more of
     • language: a language identifier
     • pattern: a glob pattern (e.g. "**/*.{txt,ml}")
     • scheme: a URL scheme (e.g. "http" or "file")
  3. an array of (1) and (2).
• revealOn, prettyCursor, adjustCursorMovement: override the global settings of the same name for this entry.
• substitutions: array of substitutions, see below.
• Advanced options, only needed together with "scope": combineIdenticalScopes, textMateGrammar, textMateInitialScope.

Substitutions

• ugly [required]: a JavaScript regular expression describing the text to be replaced.
• pretty: plain-text replacement. Unicode characters can be used directly or escaped, e.g. ∑ is ∑. If omitted, style must be given and is applied to the "ugly" text instead.
• pre: the text before ugly must match this regular expression for the substitution to proceed.
• post: the text after ugly must match this regular expression for the substitution to proceed.
• scope: restrict the substitution to tokens with this TextMate scope. Experimental, only available on VS Code versions older than 1.21.1.
• style: styling applied to pretty
  • border, textDecoration, color, backgroundColor: CSS properties
  • light: the same four properties, applied when a light theme is selected
  • dark: the same four properties, applied when a dark theme is selected

Example with all options

A settings.json snippet that lists every option, to copy and trim down. The global values are the defaults, the language entries show the per-language overrides. VS Code accepts comments in settings.json.

{
    // global settings (values shown are the defaults)
    "prettifySymbols.revealOn": "cursor",           // "cursor" | "cursor-inside" | "active-line" | "selection" | "none"
    "prettifySymbols.prettyCursor": "boxed",        // "boxed" | "none"
    "prettifySymbols.adjustCursorMovement": false,
    "prettifySymbols.insertionPosition": "before",  // "before" | "after"
    "prettifySymbols.hideTextMethod": "hack-letterSpacing",  // "hack-letterSpacing" | "hack-fontSize" | "none"
    "prettifySymbols.preserveAlignment": "off",     // "off" | "comments" | "columns"

    "prettifySymbols.substitutions": [
        {
            // language: id, DocumentFilter or an array of both
            "language": [
                "python",
                { "language": "plaintext", "pattern": "**/*.{txt,py}", "scheme": "file" }
            ],

            // per-entry overrides of the global settings
            "revealOn": "active-line",
            "prettyCursor": "none",
            "adjustCursorMovement": true,
            "hideTextMethod": "hack-fontSize",

            "substitutions": [
                // plain replacement, restricted by the surrounding text
                { "ugly": "lambda", "pretty": "λ", "pre": "\\b", "post": "\\b" },

                // replacement with styling
                {
                    "ugly": "sum",
                    "pretty": "∑",
                    "pre": "\\b",
                    "post": "\\(",
                    "style": {
                        "border": "1px dotted gray",
                        "textDecoration": "underline",
                        "color": "red",
                        "backgroundColor": "yellow",
                        "light": { "color": "darkred", "backgroundColor": "lightyellow" },
                        "dark": { "color": "salmon", "backgroundColor": "#333300" }
                    }
                },

                // no "pretty": only style the "ugly" text
                { "ugly": "TODO", "style": { "color": "orange" } }
            ]
        },
        {
            // advanced options, only needed together with "scope"
            "language": "fsharp",
            "combineIdenticalScopes": false,
            "textMateGrammar": "/path/to/fsharp.tmLanguage.json",
            "textMateInitialScope": "source.fsharp",
            "substitutions": [
                { "ugly": "->", "pretty": "→", "scope": "keyword.operator" }
            ]
        }
    ]
}

Commands

For keybindings:

• prettifySymbols.copyWithSubstitutions: copy the selected text with "pretty" substitutions applied
• prettifySymbols.enablePrettySymbols
• prettifySymbols.disablePrettySymbols
• prettifySymbols.togglePrettySymbols