Sublime Markdown Popups

https://facelessuser.github.io/sublime-markdown-popups/
Admin
Sublime Markdown Popups is a library for Sublime Text that converts Markdown or HTML into...
Tokens:17,495
Snippets:171
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Linting Dependencies

Source: https://facelessuser.github.io/sublime-markdown-popups/about/contributing

Install the required flake8 plugins to perform project linting.

```bash
pip install flake8
pip install flake8-docstrings
pip install flake8-mutable
pip install flake8-builtins
pip install pep8-naming
```

--------------------------------

### Preview Documentation Locally

Source: https://facelessuser.github.io/sublime-markdown-popups/about/contributing

Start the local development server to preview documentation changes at localhost:8000.

```bash
mkdocs serve
```

--------------------------------

### Full Pygments CSS Example

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

A comprehensive example of Pygments CSS rules covering various token types. This can be pasted directly into your user CSS for detailed syntax highlighting.

```css
.mdpopups .highlight { background-color: #f8f8f8; color: #4d4d4c }
.mdpopups .highlight .c { color: #8e908c; font-style: italic } /* Comment */
.mdpopups .highlight .err { color: #c82829 } /* Error */
.mdpopups .highlight .k { color: #8959a8; font-weight: bold } /* Keyword */
.mdpopups .highlight .l { color: #f5871f } /* Literal */
.mdpopups .highlight .n { color: #4d4d4c } /* Name */
.mdpopups .highlight .o { color: #3e999f } /* Operator */
.mdpopups .highlight .p { color: #4d4d4c } /* Punctuation */
.mdpopups .highlight .cm { color: #8e908c; font-style: italic } /* Comment.Multiline */
.mdpopups .highlight .cp { color: #8e908c; font-weight: bold } /* Comment.Preproc */
.mdpopups .highlight .c1 { color: #8e908c; font-style: italic } /* Comment.Single */
.mdpopups .highlight .cs { color: #8e908c; font-style: italic } /* Comment.Special */
.mdpopups .highlight .gd { color: #c82829 } /* Generic.Deleted */
.mdpopups .highlight .ge { font-style: italic } /* Generic.Emph */
.mdpopups .highlight .gh { color: #4d4d4c; font-weight: bold } /* Generic.Heading */
.mdpopups .highlight .gi { color: #718c00 } /* Generic.Inserted */
.mdpopups .highlight .gp { color: #8e908c; font-weight: bold } /* Generic.Prompt */
.mdpopups .highlight .gs { font-weight: bold } /* Generic.Strong */
.mdpopups .highlight .gu { color: #3e999f; font-weight: bold } /* Generic.Subheading */
.mdpopups .highlight .kc { color: #8959a8; font-weight: bold } /* Keyword.Constant */
.mdpopups .highlight .kd { color: #8959a8; font-weight: bold } /* Keyword.Declaration */
.mdpopups .highlight .kn { color: #8959a8; font-weight: bold } /* Keyword.Namespace */
.mdpopups .highlight .kp { color: #8959a8; font-weight: bold } /* Keyword.Pseudo */
.mdpopups .highlight .kr { color: #8959a8; font-weight: bold } /* Keyword.Reserved */
.mdpopups .highlight .kt { color: #eab700; font-weight: bold } /* Keyword.Type */
.mdpopups .highlight .ld { color: #718c00 } /* Literal.Date */
.mdpopups .highlight .m { color: #f5871f } /* Literal.Number */
.mdpopups .highlight .s { color: #718c00 } /* Literal.String */
.mdpopups .highlight .na { color: #4271ae } /* Name.Attribute */
.mdpopups .highlight .nb { color: #4271ae } /* Name.Builtin */
.mdpopups .highlight .nc { color: #c82829; font-weight: bold } /* Name.Class */
.mdpopups .highlight .no { color: #c82829 } /* Name.Constant */
.mdpopups .highlight .nd { color: #3e999f } /* Name.Decorator */
.mdpopups .highlight .ni { color: #4d4d4c } /* Name.Entity */
.mdpopups .highlight .ne { color: #c82829; font-weight: bold } /* Name.Exception */
.mdpopups .highlight .nf { color: #4271ae; font-weight: bold } /* Name.Function */
.mdpopups .highlight .nl { color: #4d4d4c } /* Name.Label */
.mdpopups .highlight .nn { color: #4d4d4c } /* Name.Namespace */
.mdpopups .highlight .nx { color: #4271ae } /* Name.Other */
.mdpopups .highlight .py { color: #4d4d4c } /* Name.Property */
.mdpopups .highlight .nt { color: #c82829 } /* Name.Tag */
.mdpopups .highlight .nv { color: #c82829 } /* Name.Variable */
.mdpopups .highlight .ow { color: #3e999f } /* Operator.Word */
.mdpopups .highlight .w { color: #4d4d4c } /* Text.Whitespace */
.mdpopups .highlight .mb { color: #f5871f } /* Literal.Number.Bin */
.mdpopups .highlight .mf { color: #f5871f } /* Literal.Number.Float */
.mdpopups .highlight .mh { color: #f5871f } /* Literal.Number.Hex */
.mdpopups .highlight .mi { color: #f5871f } /* Literal.Number.Integer */
.mdpopups .highlight .mo { color: #f5871f } /* Literal.Number.Oct */
.mdpopups .highlight .sb { color: #718c00 } /* Literal.String.Backtick */
.mdpopups .highlight .sc { color: #4d4d4c } /* Literal.String.Char */

```

--------------------------------

### Configure Frontmatter

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Example of configuring frontmatter from Python objects, including language mapping and markdown extensions.

```APIDOC
## Configure Frontmatter From Python Objects

A lot of times in plugins, it may be easier to build up a Python dictionary and convert it to YAML. MdPopups provides a function to exactly this:

```python
frontmatter = {
    "allow_code_wrap": false,
    "language_map": {
        "language": [["mapping_alias"], ["MyPackage/MySyntaxLanguage"]]
    },
    "markdown_extensions": [
        "markdown.extensions.admonition",
        "markdown.extensions.attr_list",
        "markdown.extensions.def_list",
        "markdown.extensions.nl2br",
        # Smart quotes always have corner cases that annoy me, so don't bother with them.
        {"markdown.extensions.smarty": {"smart_quotes": False}},
        "pymdownx.betterem",
        {
            "pymdownx.magiclink": {
                "repo_url_shortener": True,
                "base_repo_url": "https://github.com/facelessuser/sublime-markdown-popups"
            }
        },
        "pymdownx.extrarawhtml",
        "pymdownx.keys",
        {"pymdownx.escapeall": {"hardbreak": True, "nbsp": True}},
        # Sublime doesn't support superscript, so no ordinal numbers
        {"pymdownx.smartsymbols": {"ordinal_numbers": False}}
    ]
}

content = mdpopups.format_frontmatter(frontmatter) + markdown_content
```

New in 4.1.0
Added support for `language_map` in front matter. See `sublime_user_lang_map` option to learn more about the structure.
```

--------------------------------

### Pygments General CSS Example

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

A basic Pygments CSS rule to set the background and foreground colors for the general highlight block. This should be defined in your user CSS.

```css
.mdpopups .highlight { background-color: #f8f8f8; color: #4d4d4c }

```

--------------------------------

### Pygments Whitespace CSS Example

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

An example of a Pygments CSS rule for highlighting whitespace. Pygments uses specific classes for spans within a highlighted block, often wrapped in a div with a '.highlight' class.

```css
.highlight .w { color: #cccccc } /* Text.Whitespace */

```

--------------------------------

### Fallback to Background Color for Operators

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Use the 'css' filter with `explicit_background=False` to ensure a background color is always returned, even if not explicitly defined for the scope. This example demonstrates falling back to the '.keyword' scope's background if 'keyword.operator' has no explicit background defined.

```html
/* If `keyword.operator` is not explicitly used, fallback to `.keyword` */
h1, h2, h3, h4, h5, h6 {
  {{'keyword.operator'|css('color', False)}}
}
```

--------------------------------

### Run Project Linting

Source: https://facelessuser.github.io/sublime-markdown-popups/about/contributing

Execute the flake8 command from the root directory to validate the project code.

```bash
flake8 .
```

--------------------------------

### Configure Frontmatter From Python Objects

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Use this pattern to construct a dictionary of Markdown extensions and settings, then convert it into a frontmatter string for MdPopups.

```python
frontmatter = {
    "allow_code_wrap": false,
    "language_map": {
        "language": [["mapping_alias"], ["MyPackage/MySyntaxLanguage"]]
    },
    "markdown_extensions": [
        "markdown.extensions.admonition",
        "markdown.extensions.attr_list",
        "markdown.extensions.def_list",
        "markdown.extensions.nl2br",
        # Smart quotes always have corner cases that annoy me, so don't bother with them.
        {"markdown.extensions.smarty": {"smart_quotes": False}},
        "pymdownx.betterem",
        {
            "pymdownx.magiclink": {
                "repo_url_shortener": True,
                "base_repo_url": "https://github.com/facelessuser/sublime-markdown-popups"
            }
        },
        "pymdownx.extrarawhtml",
        "pymdownx.keys",
        {"pymdownx.escapeall": {"hardbreak": True, "nbsp": True}},
        # Sublime doesn't support superscript, so no ordinal numbers
        {"pymdownx.smartsymbols": {"ordinal_numbers": False}}
    ]
}

content = mdpopups.format_frontmatter(frontmatter) + markdown_content
```

--------------------------------

### Apply emphasis formatting

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Demonstrates the use of underscores and asterisks for emphasis when using the betterem extension.

```markdown
_handled_intelligently_
```

```markdown
em*pha*sis
```

--------------------------------

### Enable Code Wrapping

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Configures block code tags to wrap content instead of truncating.

```yaml
---
allow_code_wrap: true
...
```

--------------------------------

### Styling Popups and Phantoms

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Information on how popups and phantoms are styled using CSS and the Jinja2 template engine, including advice on using wrapper classes for plugin-specific styling.

```APIDOC
## Styling

Popups and phantoms are styled with CSS that is fed through the Jinja2 template engine. A default CSS is provided that styles commonly used elements. Plugins can provide CSS to add additional styling for plugin specific purposes. See CSS Styling to learn more about the template engine and general styling info.

It is advised to use the `wrapper_class` option of the `show_popup`, `update_popup`, and `add_phantom` commands to wrap your plugin content in a div with a unique, plugin specific class. This way plugins can inject CSS to style their specific elements via `.mdpopups .myplugin-wrapper .myclass {}` or simply `.myplugin-wrapper .myclass {}`.

Also check out the included Python Markdown `attr_list` extension syntax. This is a good extension for applying classes directly to elements within Markdown format. Sometimes it can be difficult to target certain kinds of block elements, so if all else fails, you can insert raw HTML for specific elements into your Markdown and apply classes directly to them.
```

--------------------------------

### Frontmatter Syntax

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Basic structure for YAML frontmatter using markers.

```yaml
---
# yaml content
---
```

```yaml
---
# yaml content
...
```

```yaml
---
key1: value1
key2: value2
...
```

--------------------------------

### Use Sublime Syntax Highlighter

Source: https://facelessuser.github.io/sublime-markdown-popups/settings

Toggles between Pygments and the native Sublime syntax highlighter for code highlighting. Set to `true` to use Sublime's highlighter.

```json
    "mdpopups.use_sublime_highlighter": true
```

--------------------------------

### Configure Package Control dependencies

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Defines the required mdpopups dependency for Package Control.

```json
{
    "*": {
        ">=3124": [
            "mdpopups"
        ]
    }
}
```

--------------------------------

### Show Popup API

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Details on the `mdpopups.show_popup` function, which accepts Markdown and creates a Sublime popup, with options for highlighting, CSS, location, and callbacks.

```APIDOC
### Show Popup 

`mdpopups.show_popup`
    
Accepts Markdown and creates a Sublime popup. By default, the built-in Sublime syntax highlighter will be used for code highlighting.

Parameter | Type | Default | Description  
---|---|---|---
`view` | `sublime.View` |  | A Sublime Text view object.  
`content` | `str` |  | Markdown/HTML content for the popup.  
`md` | `bool` | `True` | Defines whether the content is Markdown and needs to be converted.  
`css` | `str` | `None` | Additional CSS that will be injected.  
`flags` | `int` | `0` | Flags to pass down to the Sublime Text `view.show_popup` call.  
`location` | `int` | `-1` | Location to show popup in view. -1 means to show right under the first cursor.  
`max_width` | `int` | `320` | Maximum width of the popup.  
`max_height` | `int` | `240` | Maximum height of the popup.  
`on_navigate` | `def fn()` | `None` | Callback that receives one variable `href`.  
`on_hide` | `def fn()` | `None` | Callback for when the popup is hidden.  
`wrapper_class` | `str` | `None` | A string containing the class name you wish wrap your content in. A `div` will be created with the given class.  
`template_vars` | `dict` | `None` | A dictionary containing template vars. These can be used in either the CSS or the HTML/Markdown content. These vars are found under the object `plugin`.  
`template_env_options` | `dict` | `None` | A dictionary containing options for the Jinja2 template environment. This **only** applies to the **HTML/Markdown** content.  

Removed in 4.0
4.0 removed the parameter `nl2br` and `alow_code_wrap`. If passed to the function, they will be ignored.
To disable `nl2br`, you can customize which extensions get loaded; see Configure Markdown Extensions.
To enable code wrapping, see Enable Code Wrapping.
```

--------------------------------

### Configure Package Control dependencies with Python 3.3 support

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Includes the typing dependency required for Python 3.3 support.

```json
{
    "*": {
        ">=3124": [
            "mdpopups",
            "typing"
        ]
    }
}
```

--------------------------------

### Scope to Style Return Format

Source: https://facelessuser.github.io/sublime-markdown-popups/api

The structure of the dictionary returned by mdpopups.scope2style.

```python
{
    # Colors will be None if not found,
    # though usually, even if the scope has no color
    # it will return the overall theme foreground.
    #
    # Background might be None if using `explicit_background`
    # as it only returns a background if that style specifically
    # defines a background.
    "color": "#RRGGBB",
    "background": "#RRGGBB",
    # Style will usually be either 'bold', 'italic'.
    # Multiple styles may be returned 'bold italic' or an empty string ''.
    "style": 'bold italic'
}
```

--------------------------------

### Specify Custom User CSS File

Source: https://facelessuser.github.io/sublime-markdown-popups/settings

Overrides default and plugin CSS with a custom file. Provide a relative path, e.g., `Packages/User/my_custom_theme.css`. Defaults to `Packages/User/mdpopups.css` and overrides all other CSS.

```json
    "mdpopups.user_css": "Packages/User/mdpopups.css"
```

--------------------------------

### Enable inline code highlighting

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Use the inlinehilite extension to highlight code snippets within a line of text.

```markdown
`#!py3thon import module`
```

--------------------------------

### mdpopups.tint_raw

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Tints a PNG image and returns the modified byte string.

```APIDOC
## mdpopups.tint_raw

### Description
Takes a path to a PNG or a byte string of a PNG, tints it with a specific color, and returns a byte string of the modified PNG.

### Parameters
#### Path Parameters
- **img** (str/bytes) - Required - Either a string in the form Packages/Package/resource.png or a byte string of a PNG image.
- **color** (str) - Required - A string in the form of #RRGGBB or #RRGGBBAA.
- **opacity** (int) - Optional (Default: 255) - An integer value between 0 - 255 that specifies the opacity of the tint.

### Response
- **return** (bytes) - A byte string of the modified PNG.
```

--------------------------------

### Color Box Generation

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Generates a color preview box image encoded in base 64, suitable for embedding in Markdown or HTML as an `img` tag.

```APIDOC
## Color Box

### Description
Generates a color preview box image encoded in base 64 and formatted to be inserted right in your your Markdown or HTML code as an `img` tag.

### Method
`mdpopups.color_box`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **colors** ([str]) - Required - A list of color strings formatted as `#RRGGBBAA` where R is the red channel, G is the green channel, B is the blue channel, and A is the alpha channel.
- **border** (str) - Optional - The color for the color box border. Input is a RGB color formatted as `#RRGGBB`.
- **border2** (str) - Optional - The optional secondary border color. This is great if you are going to have it on a light and dark backgrounds. You can use a double border so the color stands out regardless of the background. Input is a RGB color formatted as `#RRGGBB`.
- **height** (int) - Optional - Height of color box. Default is 32.
- **width** (int) - Optional - Width of color box. Default is 32.
- **border_size** (int) - Optional - Width of the color box border. If using `border2`, the value should be set to at least 2 to see both colors. Default is 1.
- **check_size** (int) - Optional - Size of checkered box squares used for the background of transparent colors. Default is 4.
- **max_colors** (int) - Optional - Max number of colors that will be evaluated in the `colors` parameter. Multiple colors are used to to create palette boxes showing multiple colors lined up horizontally. Default is 5.
- **alpha** (bool) - Optional - Will create color box images with a real alpha channel instead of simulating one with a checkered background. Default is False.
- **border_map** (int) - Optional - A mapping of which borders to show. Where `0x1` is `TOP`, `0x2` is `LEFT`, `0x4` is `BOTTOM`, `0x8` is `RIGHT`. Map flags can be accessed via `mdpopups.colorbox.TOP` etc. Default is `0xF`.

### Request Example
```python
import mdpopups

img_tag = mdpopups.color_box(
    colors=["#FF0000", "#00FF00"],
    border="#000000",
    height=50,
    width=50,
    border_size=2
)
```

### Response
#### Success Response (200)
- **img_tag** (string) - An HTML `img` tag with the base64 encoded color box image.

#### Response Example
```html
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAAyCAY..." alt="Color Box">
```
```

--------------------------------

### Enable GitHub Flavored Markdown

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Enables GFM extensions for the Marko parser. Note that table support is stripped as it is incompatible with minihtml.

```yaml
---
markdown_parser: marko
markdown_extensions:
- gfm
---
```

--------------------------------

### Configure Markdown Extensions

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Defines the list of active markdown extensions and their specific configurations.

```yaml
---
markdown_extensions:
- markdown.extensions.admonition
- markdown.extensions.attr_list
- markdown.extensions.def_list
- markdown.extensions.nl2br
- pymdownx.betterem
- pymdownx.magiclink
- pymdownx.extrarawhtml
...
```

```yaml
---
markdown_extensions:
- markdown.extensions.admonition
- markdown.extensions.attr_list
- markdown.extensions.def_list
- markdown.extensions.nl2br
- markdown.extensions.smarty:
    smart_quotes: false
- pymdownx.betterem
- pymdownx.magiclink:
    base_repo_url: https://github.com/facelessuser/sublime-markdown-popups
    repo_url_shortener: true
- pymdownx.extrarawhtml
- pymdownx.keys
- pymdownx.escapeall:
    hardbreak: true
    nbsp: true
- pymdownx.smartsymbols:
    ordinal_numbers: false
...
```

--------------------------------

### Enable CommonMark Parser

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Specifies the use of the Marko parser via frontmatter. Requires Python 3.13 in Sublime Text 4201+.

```yaml
---
markdown_parser: marko
---
```

--------------------------------

### mdpopups.tint

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Tints a PNG image and returns a base64 encoded HTML element.

```APIDOC
## mdpopups.tint

### Description
Takes a path to a PNG or a byte string of a PNG, tints it with a specific color, and returns a string containing the base 64 encoded PNG in an HTML element.

### Parameters
#### Path Parameters
- **img** (str/bytes) - Required - Either a string in the form Packages/Package/resource.png or a byte string of a PNG image.
- **color** (str) - Required - A string in the form of #RRGGBB or #RRGGBBAA.
- **opacity** (int) - Optional (Default: 255) - An integer value between 0 - 255 that specifies the opacity of the tint.
- **height** (int) - Optional (Default: None) - Height that should be specified in the return HTML element.
- **width** (int) - Optional (Default: None) - Width that should be specified in the return HTML element.

### Response
- **return** (str) - A string containing the base 64 encoded PNG in a HTML element.
```

--------------------------------

### mdpopups.syntax_highlight

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Performs syntax highlighting on source code outside the Markdown environment.

```APIDOC
## mdpopups.syntax_highlight

### Description
Converts source code into a block of HTML that has been syntax highlighted.

### Parameters
#### Path Parameters
- **view** (sublime.View) - Required - Sublime text View object.
- **src** (str) - Required - The source code to be converted.
- **language** (str) - Optional (Default: None) - Specifies the language to highlight as.
- **inline** (bool) - Optional (Default: False) - Returns code formatted for inline display.
- **allow_code_wrap** (bool) - Optional (Default: False) - Allows wrapping by not converting spaces to &nbsp;.
- **language_map** (Dict) - Optional (Default: None) - Language map to add to the built-in language map.

### Response
- **return** (str) - A block of HTML that has been syntax highlighted.
```

--------------------------------

### Apply Sepia Filter

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Use the sepia filter to convert all colors to a sepia tone. This filter takes no arguments.

```html
body { {{'.background'|css('background-color')|sepia}} }
```

--------------------------------

### Retrieve CSS from Packages

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Retrieves a CSS file from Sublime's Packages folder. This CSS can include template variables and filters.

```jinja
{{'Packages/User/aprosopo-dark.css'|getcss}}
```

--------------------------------

### Convert Tabs to Spaces with mdpopups

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Converts tabs to spaces based on specified tab stops, providing more intelligent whitespace formatting than simple fixed-width conversion.

```python
>>> import mdpopups
>>> text = '''
============================================================
T\tTp\tSp\tD\tDp\tS\tD7\tT
------------------------------------------------------------
A\tF#m\tBm\tE\tC#m\tD\tE7\tA
A#\tGm\tCm\tF\tDm\tD#\tF7\tA#
B♭\tGm\tCm\tF\tDm\tE♭m\tF7\tB♭
'''
>>> print(mdpopups.tabs2spaces(text, tab_size=8))

============================================================
T       Tp      Sp      D       Dp      S       D7      T
------------------------------------------------------------
A       F#m     Bm      E       C#m     D       E7      A
A#      Gm      Cm      F       Dm      D#      F7      A#
B♭      Gm      Cm      F       Dm      E♭m     F7      B
```

--------------------------------

### Enable MdPopups Debug Mode

Source: https://facelessuser.github.io/sublime-markdown-popups/settings

Turns on debug mode to output detailed information to the console. Set to `1` for errors, `2` for warnings and errors, or `3` for general info including HTML output. `0` or `false` disables it.

```json
    "mdpopups.debug": 1,
```

--------------------------------

### New HTML Sheet API

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Creates a new HTML sheet from Markdown content, with options for styling and templating.

```APIDOC
## mdpopups.new_html_sheet

### Description
Accepts Markdown and creates a Sublime HTML sheet. By default, the built-in Sublime syntax highlighter will be used for code highlighting.

### Parameters
#### Path Parameters
- **window** (sublime.Window) - Required - A Sublime Text view object.
- **name** (str) - Required - Name for the HTML sheet.
- **contents** (str) - Required - Markdown/HTML content for the popup.
- **md** (bool) - Optional - Defines whether the content is Markdown and needs to be converted. Defaults to `True`.
- **css** (str) - Optional - Additional CSS that will be injected. Defaults to `None`.
- **flags** (int) - Optional - Flags to pass down to the Sublime Text `new_html_sheet` call. Defaults to `0`.
- **group** (int) - Optional - Specify window group. Defaults to `-1`.
- **wrapper_class** (str) - Optional - A string containing the class name you wish wrap your content in. A `div` will be created with the given class. Defaults to `None`.
- **template_vars** (dict) - Optional - A dictionary containing template vars. These can be used in either the CSS or the HTML/Markdown content. These vars are found under the object `plugin`. Defaults to `None`.
- **template_env_options** (dict) - Optional - A dictionary containing options for the Jinja2 template environment. This **only** applies to the **HTML/Markdown** content. Defaults to `None`.

### Notes
- `new_html_sheet` is new in 3.6.0. This feature should be considered experimental.
- Removed in 4.0: `nl2br` and `alow_code_wrap` parameters are ignored if passed.
```

--------------------------------

### MdPopups API Functions

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Overview of the accessible functions provided by the MdPopups library.

```APIDOC
## API Usage

MdPopups provides a number of accessible functions.

### Version 

`(int,) mdpopups.version`
    Returns the version of the MdPopups library. Returns a tuple of integers which represents the major, minor, and patch version.
```

--------------------------------

### Color Box Raw Byte String Generation

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Generates the raw byte string of a color preview box image, useful for direct image manipulation or saving.

```APIDOC
## Color Box Raw

### Description
Generates a color preview box image and returns the raw byte string of the image.

### Method
`mdpopups.color_box_raw`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **colors** ([str]) - Required - A list of color strings formatted as `#RRGGBBAA` where R is the red channel, G is the green channel, B is the blue channel, and A is the alpha channel.
- **border** (str) - Optional - The color for the color box border. Input is a RGB color formatted as `#RRGGBB`.
- **border2** (str) - Optional - The optional secondary border color. This is great if you are going to have it on a light and dark backgrounds. You can use a double border so the color stands out regardless of the background. Input is a RGB color formatted as `#RRGGBB`.
- **height** (int) - Optional - Height of color box. Default is 32.
- **width** (int) - Optional - Width of color box. Default is 32.
- **border_size** (int) - Optional - Width of the color box border. If using `border2`, the value should be set to at least 2 to see both colors. Default is 1.
- **check_size** (int) - Optional - Size of checkered box squares used for the background of transparent colors. Default is 4.
- **max_colors** (int) - Optional - Max number of colors that will be evaluated in the `colors` parameter. Multiple colors are used to to create palette boxes showing multiple colors lined up horizontally. Default is 5.
- **alpha** (bool) - Optional - Will create color box images with a real alpha channel instead of simulating one with a checkered background. Default is False.
- **border_map** (int) - Optional - A mapping of which borders to show. Where `0x1` is `TOP`, `0x2` is `LEFT`, `0x4` is `BOTTOM`, `0x8` is `RIGHT`. Map flags can be accessed via `mdpopups.colorbox.TOP` etc. Default is `0xF`.

### Request Example
```python
import mdpopups

raw_image_bytes = mdpopups.color_box_raw(
    colors=["#0000FF"],
    height=40,
    width=40
)
```

### Response
#### Success Response (200)
- **raw_image_bytes** (bytes) - The raw byte string of the generated color box image.

#### Response Example
```python
# Example of how to use the raw bytes (e.g., save to a file)
with open("color_box.png", "wb") as f:
    f.write(raw_image_bytes)
```
```

--------------------------------

### Conditional Padding Based on Sublime Version

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Conditionally applies padding based on the Sublime Text version. Use this for version-specific styling.

```jinja
{% if var.sublime_version >= 3119 %}
padding: 0.2rem;
{% else %}
padding: 0.2em;
{% endif %}
```

--------------------------------

### Map Custom Sublime Syntax Languages

Source: https://facelessuser.github.io/sublime-markdown-popups/settings

Maps personal Sublime syntax languages for the Sublime Syntax Highlighter. Allows defining new entries or extending existing ones.

```json
    "mdpopups.sublime_user_lang_map": {
        "language": [["mapping_alias"], ["MyPackage/MySyntaxLanguage"]]
    }
```

```json
"mdpopups.sublime_user_lang_map": {
    "javascript": [["javascript", "js"], ["JavaScript/JavaScript", "JavaScriptNext - ES6 Syntax/JavaScriptNext"]]
}
```

```json
"mdpopups.sublime_user_lang_map": {
    "javascript": [["javascript", "js"], ["scope:source.js"]]
}
```

--------------------------------

### Set CSS Theme Cache Limit

Source: https://facelessuser.github.io/sublime-markdown-popups/settings

Determines the maximum number of CSS theme files to keep in the cache. Value should be a non-negative integer.

```json
    "mdpopups.cache_limit": 10
```

--------------------------------

### Conditional Styling Based on Color Scheme

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Applies styles based on the current color scheme name. Useful for theme-specific adjustments.

```jinja
{% if (
    var.color_scheme in (
        'Packages/Theme - Aprosopo/Tomorrow-Night-Eighties-Stormy.tmTheme',
        'Packages/Theme - Aprosopo/Tomorrow-Morning.tmTheme',
    )
) %}
a { {{'.keyword.operator'|css('color')}} }
{% else %}
a { {{'.support.function'|css('color')}} }
{% endif %}
```

--------------------------------

### Apply Grayscale Filter

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Use the grayscale filter to convert all colors to a grayish tone. This filter takes no arguments.

```html
body { {{'.background'|css('background-color')|grayscale}} }
```

--------------------------------

### Conditional Pygments Styling

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Conditionally includes Pygments syntax highlighting based on the 'use_pygments' flag and whether the scheme is light or dark.

```jinja
{% if var.use_pygments %}
{% if var.is_light %}
{{'default'|pygments}}
{% else %}
{{'native'|pygments}}
{% endif %}
{% endif %}
```

--------------------------------

### Template Variables

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Provides variables to conditionally alter CSS output based on Sublime Text and MdPopups versions, color scheme properties, and popup context.

```APIDOC
## Template Variables

The template environment provides a couple of variables that can be used to conditionally alter the CSS output. Variables are found under `var`.

### `var.sublime_version`

`sublime_version` contains the current Sublime Text version. This allows you conditionally handle CSS features that are specific to a Sublime Text version.

#### Example
```
{% if var.sublime_version >= 3119 %}
padding: 0.2rem;
{% else %}
padding: 0.2em;
{% endif %}
```

### `var.mdpopups_version`

`mdpopups_version` contains the current MdPopups version which you can use in your CSS templates if needed.

#### Example
```
{% if var.mdpopups_version >= (1, 9, 0) %}
/* do something */
{% else %}
/* do something else */
{% endif %}
```

### `var.default_style`

Flag specifying whether default styling is being used. See `mdpopups.default_style` for how to control this flag. And see `default.css` for an example of how it is used.

### `var.is_dark` and `var.is_light`

`is_dark` checks if the color scheme is a dark color scheme. Alternatively, `is_light` checks if the color scheme is a light color scheme.

#### Example
```
{% if var.is_light %}
html{ {{'.background'|css('background-color')|brightness(0.9)}} }
{% else %}
html{ {{'.background'|css('background-color')|brightness(1.1)}} }
{% endif %}
```

### `var.is_popup`, `var.is_phantom`, and `var.is_sheet`

`is_phantom` checks if the current CSS is for a phantom instead of a popup. Alternatively, `is_popup` and `is_sheet` checks if the current use of the CSS is for a popup or HTML sheet respectively.

#### Example
```
{% if var.is_phantom %}
html{ {{'.background'|css('background-color')|brightness(0.9)}} }
{% else %}
html{ {{'.background'|css('background-color')|brightness(1.1)}} }
{% endif %}
```

### `var.use_pygments`

Checks if the Pygments syntax highlighter is being used.

#### Example
```
{% if var.use_pygments %}
{% if var.is_light %}
{{'default'|pygments}}
{% else %}
{{'native'|pygments}}
{% endif %}
{% endif %}
```

### `var.color_scheme`

Retrieves the current color schemes name.

#### Example
```
{% if (
    var.color_scheme in (
        'Packages/Theme - Aprosopo/Tomorrow-Night-Eighties-Stormy.tmTheme',
        'Packages/Theme - Aprosopo/Tomorrow-Morning.tmTheme',
    )
) %}
a { {{'.keyword.operator'|css('color')}} }
{% else %}
a { {{'.support.function'|css('color')}} }
{% endif %}
```
```

--------------------------------

### Conditional Styling for Dark/Light Color Schemes

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Applies different styles based on whether the color scheme is dark or light. Adjusts background brightness accordingly.

```jinja
{% if var.is_light %}
html{ {{'.background'|css('background-color')|brightness(0.9)}} }
{% else %}
html{ {{'.background'|css('background-color')|brightness(1.1)}} }
{% endif %}
```

--------------------------------

### mdpopups.resolve_images

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Downloads remote images within an HTML buffer.

```APIDOC
## mdpopups.resolve_images

### Description
Searches an HTML buffer for image URLs and downloads them using a provided resolver. This is an experimental feature.

### Parameters
- **minihtml** (str) - Required - A minihtml string buffer.
- **resolver** (function) - Required - A function that resolves an image URL by downloading it.
- **on_done** (function) - Required - A callback for when the image resolving is complete.

### Response
- **Returns** (str) - The processed minihtml string buffer.
```

--------------------------------

### mdpopups.tabs2spaces

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Converts tabs to spaces in a string based on specified tab stops.

```APIDOC
## mdpopups.tabs2spaces

### Description
Converts all tabs in a string to spaces based on intelligent tab stops rather than a fixed width for every tab.

### Parameters
- **text** (str) - Required - Text to convert.
- **tab_size** (int) - Optional (Default: 4) - Tab size.

### Request Example
```python
import mdpopups
text = 'T\tTp'
result = mdpopups.tabs2spaces(text, tab_size=8)
```

### Response
- **Returns** (str) - The converted string.
```

--------------------------------

### Markdown to HTML Conversion

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Converts Markdown strings to HTML, utilizing Sublime's syntax highlighter for code blocks. This function is useful for integrating Markdown snippets into HTML content.

```APIDOC
## Markdown to HTML

### Description
Exposes the Markdown to HTML converter in case it is desired to parse only a section of markdown. This works well for someone who wants to work directly in HTML, but might want to still have fragments of markdown that they would like to occasionally convert. By default, the built-in Sublime syntax highlighter will be used for code highlighting.

### Method
`mdpopups.md2html`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **view** (sublime.View) - Required - Sublime text View object.
- **markup** (string) - Required - The markup code to be converted.
- **template_vars** (dict) - Optional - A dictionary containing template vars. These can be used in either the CSS or the HTML/Markdown content. These vars are found under the object `plugin`.
- **template_env_options** (dict) - Optional - A dictionary containing options for the Jinja2 template environment. This **only** applies to the **HTML/Markdown** content. Content plugin vars are found under the object: `plugin`.

### Request Example
```python
import mdpopups

# Assuming 'view' is a valid sublime.View object
html_output = mdpopups.md2html(view, "# Hello World\n```python\nprint(\"Hello\")\n```")
```

### Response
#### Success Response (200)
- **html_output** (string) - The generated HTML string.

#### Response Example
```html
<h1>Hello World</h1>
<pre><code class="language-python">print("Hello")
</code></pre>
```

### Notes
- The parameters `nl2br` and `alow_code_wrap` were removed in version 4.0 and are now ignored. To disable `nl2br`, customize loaded extensions. To enable code wrapping, refer to 'Enable Code Wrapping' documentation.
```

--------------------------------

### mdpopups.get_language_from_view

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Extracts the language specifier from a Sublime Text view.

```APIDOC
## mdpopups.get_language_from_view

### Description
Extracts the equivalent language specifier for mdpopups.syntax_highlight from a given view.

### Parameters
- **view** (sublime.View) - Required - Sublime text View object.

### Response
- **Returns** (str|None) - The language specifier or None if it cannot be determined.
```

--------------------------------

### Conditional Styling for Phantom/Popup/Sheet

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Applies styles based on the context: phantom, popup, or HTML sheet. Useful for context-specific UI adjustments.

```jinja
{% if var.is_phantom %}
html{ {{'.background'|css('background-color')|brightness(0.9)}} }
{% else %}
html{ {{'.background'|css('background-color')|brightness(1.1)}} }
{% endif %}
```

--------------------------------

### Retrieve Pygments Color Scheme

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Retrieves a built-in Pygments color scheme. Use 'native' for a default scheme or other available schemes.

```jinja
{{'native'|pygments}}
```

--------------------------------

### Conditional Styling Based on MdPopups Version

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Conditionally applies styles based on the MdPopups version. Useful for features introduced in specific versions.

```jinja
{% if var.mdpopups_version >= (1, 9, 0) %}
/* do something */
{% else %}
/* do something else */
{% endif %}
```

--------------------------------

### Define Custom Fences

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Registers custom block content handlers, such as UML diagrams, via the custom_fences option.

```yaml
---
custom_fences:
- name: uml
  class: uml
  format: !!python/name:my_package.my_module.my_custom_format
...
```

--------------------------------

### Increase Contrast

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Apply the contrast filter with a value greater than 1 to increase contrast. Accepted values are floats greater than 0, clamped between 0 and 2.

```html
body { {{'.background'|css('background-color')|contrast(1.1)}} }
```

--------------------------------

### mdpopups.scope2style

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Guesses the style applied to a specific Sublime Text scope.

```APIDOC
## mdpopups.scope2style

### Description
Takes a sublime scope and guesses the style that would be applied based on the current color scheme.

### Parameters
#### Path Parameters
- **view** (sublime.View) - Required - Sublime text View object.
- **scope** (string) - Required - The scope to search for.
- **selected** (bool) - Optional (Default: False) - Whether this scope is in a selected state.
- **explicit_background** (bool) - Optional (Default: False) - Only return a background if one is explicitly defined.

### Response
- **return** (dict) - A dictionary containing 'color', 'background', and 'style' keys.
```

--------------------------------

### Query Phantoms

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Query the location of multiple phantoms by their IDs.

```APIDOC
## mdpopups.query_phantoms

### Description
Query the location of multiple phantoms by specifying their ids. A list of sublime.Region objects will be returned where each index corresponds to the index of ids passed in.

### Parameters
#### Path Parameters
- **view** (sublime.View) - Required - A Sublime Text view object.
- **pids** ([int]) - Required - A list of ids associated with phantoms.

### Response
- **return** ([sublime.Region]) - A list of regions corresponding to the provided ids.
```

--------------------------------

### Disable MdPopups Globally

Source: https://facelessuser.github.io/sublime-markdown-popups/settings

A global kill switch to prevent all MdPopups from appearing. Set to `true` to disable.

```json
    "mdpopups.disable": true,
```

--------------------------------

### Decrease Contrast

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Apply the contrast filter with a value less than 1 to decrease contrast. Accepted values are floats greater than 0, clamped between 0 and 2.

```html
body { {{'.background'|css('background-color')|contrast(0.9)}} }
```

--------------------------------

### PhantomSet Class

Source: https://facelessuser.github.io/sublime-markdown-popups/api

Manages a set of phantoms associated with a specific key in a Sublime Text view.

```APIDOC
## mdpopups.PhantomSet

### Description
A class that allows you to update phantoms under the specified key.

### Parameters
#### Path Parameters
- **view** (sublime.View) - Required - A Sublime Text view object.
- **key** (str) - Required - The key that should be associated with all related phantoms in the set.

### Methods
#### mdpopups.PhantomSet.update

### Description
Update all the phantoms in the set with the given phantom list.

### Parameters
#### Path Parameters
- **new_phantoms** ([mdpopups.Phantom]) - Required - A list of MdPopups phantoms. `sublime.Phantom` will be converted to `mdpopups.Phantom`.
```

--------------------------------

### Apply Brightness Filter to Background

Source: https://facelessuser.github.io/sublime-markdown-popups/styling

Use the brightness filter to darken the popup background. This is useful when the popup color is similar to the view window background.

```html
.mdpopups div.myplugin { {{'.background'|css('background-color')|brightness(0.9)}} }
```
Tokens:
Raw