API

Dependencies

Your plugin should include the Package Control dependencies listed below. Please read about Package Control's dependencies to learn more.

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

Check out facelessuser/mdpopups_test if to create quick and easy popup tests. Clone it into Packages/mdpopups_test, run Package Control: Satisfy dependencies, and then restart Sublime. You should be able to then run the command Mdpopups: Test to see an example popup, phantom, or (if on Sublime Text 4) HTML sheet. You can even create output of the source HTML for debugging. Feel free to try it out.

Markdown Support

MdPopups uses Python-Markdown/markdown to parse Markdown and transform it into a Sublime popup or phantom. The Markdown environment supports basic Markdown syntax, but also includes a number of specialty extensions to enhance and extend the Markdown environment.

Due to the minihtml environment that Sublime uses, the type of tags and CSS that can be used are a bit limited. MdPopups provides a CSS that includes most of the common supported tags that can be used. Then few specific extensions (that work well within the minihtml environment) have been selected to provide support for a some additional useful features.

Prior to version 2.0.0, the default extensions and extension configurations were locked down, but starting with 2.1.0, this restriction has been mostly removed. Not all Python Markdown extensions and extension options are compatible with Sublime's minihtml environment, and extensions like markdown.extensions.extra can include some extensions that are not compatible, but there are a number of additional extension and extension options that can be used beyond what is provided by default. In general, it is recommended to include each plugin individual on a case by case basis and disable features that aren't compatible.

Below we will touch on the specific extensions used by default which are known to work in the Sublime minihtml environment. If you are on version 2.1.0+, read on in Frontmatter to learn how to customize extensions.

Extensions

These three extensions are setup and configured automatically and should not be configured manually. Also, do not try to use markdown.extensions.codehilite or markdown.extensions.fenced_code as the following extensions have been specifically altered to output Sublime syntax highlighting properly and will clash with markdown.extensions.codehilite and markdown.extensions.fenced_code.

mdpopups.mdx.highlight ( a modified version pymdownx.highlight for Sublime Text highlighting) controls and configures the highlighting of code blocks.
mdpopups.mdx.superfences (a modified version pymdownx.superfences for Sublime Text highlighting) that provides support for nested fenced blocks.
mdpopups.mdx.inlinehilite (a modified version of [pymdownx.inlinehilite] for Sublime Text highlighting) allows for inline code highlighting: `#!py3thon import module` → import module. Please don't use this version.

These extensions are provided by Python Markdown:

markdown.extensions.attr_list allows you to add HTML attributes to block and inline elements easily.
markdown.extensions.nl2br turns new lines into <br> tags.
markdown.extensions.def_list adds support for definition lists.
markdown.extensions.admonition provides admonition blocks.

These are 3^rd party extensions provided by PyMdown Extensions:

pymdownx.betterem is an extension that aims to improve upon emphasis support in Python Markdown. MdPopups leaves it configured in its default state where underscores are handled intelligently: _handled_intelligently_ → handled_intelligently and asterisks can be used to do mid word emphasis: em*pha*sis → emphasis.
pymdownx.magiclink auto links HTML and email links. In 2.1.0+, it also allows the shortening of common repository pull request, issue, and commit links (if configured).
pymdownx.extrarawhtml allows you to add markdown="1" to raw, block HTML elements to allow content under them to be parsed with Python markdown (inline tags should already have their content parsed). This module is exposing just this functionality from the Python Markdown's Extra extension as the feature could not be enabled without including all of the Extra extensions other features. You can read the Python Markdown's Extra extension documentation to learn more about this feature.

Frontmatter

Frontmatter can be used to configure content in 2.1.0+. The frontmatter must be specified, starting on the first line of the content, before the Markdown. The frontmatter content should be in YAML syntax and should come between the YAML markers: ---.

---
# yaml content
---

Optionally the content can use the ending ... as shown below:

---
# yaml content
...

At the base level, the YAML content is a hash table containing key value pairs.

---
key1: value1
key2: value2
...

Enable Code Wrapping

The allow_code_wrap setting allows block code tags to have their content wrapped. If disabled (the default), code content will not wrap lines.

---
allow_code_wrap: true
...

Custom Fences

The included mdpopups.mdx.superfences has an option that allows for custom fences. Custom fences are a convenient way to add support for special block content such as UML diagrams. Since configuring mdpopups.mdx.superfences is not allowed directly, you can setup your own custom fences via a separate custom_fences option. See the original SuperFences' Custom Fences documentation to learn more.

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

Configure Markdown Extensions

Custom extension configurations are specified under the markdown_extensions key whose value is an array of extensions. Each extension is specified as a string. If you have specific settings to configure for an extension, simply make that array entry a dictionary where the key name is the extension name, and value is a hash table with all the settings. The default configuration is below.

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

Notice that mdpopups.mdx.highlight, mdpopups.mdx.superfences, and mdpopups.mdx.inlinehilite are not shown here as they cannot be set directly and are handled by automatically by MdPopups.

Let's say we wanted to keep the default extensions, but we wanted to enable pymdown.magiclink's repository URL shortening and add and configure pymdownx.keys, pymdownx.escapeall, pymdownx.smartsymbols, and markdown.extensions.smarty. We must specify the full configuration we would like. We will use the base default settings outlined above, adding our new options and extensions.

---
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
...

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:

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.

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.

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.

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.

mdpopups.update_popup

Updates the current existing popup.

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.
`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.

mdpopups.hide_popup

Hides the current popup. Included for convenience and consistency.

Parameter	Type	Default	Description
`view`	`sublime.View`		A Sublime Text view object.

bool mdpopups.is_popup_visible

Checks if popup is visible in the view. Included for convenience and consistency.

Parameter	Type	Default	Description
`view`	`sublime.View`		A Sublime Text view object.

Add Phantom

int mdpopups.add_phantom

Adds a phantom to the view and returns the phantom id as an integer. 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.
`key`	`str`		A key that is associated with the given phantom. Multiple phantoms can share the same key, but each phantom will have its own id.
`region`	`sublime.Region`		Region in the view where the phantom should be inserted.
`content`	`str`		Markdown/HTML content for the phantom.
`layout`	`int`		How the HTML content should be inserted. Acceptable values are: `sublime.LAYOUT_INLINE`, `sublime.LAYOUT_BLOCK`, and `sublime.LAYOUT_BELOW`.
`md`	`bool`	`True`	Defines whether the content is Markdown and needs to be converted.
`css`	`str`	`None`	Additional CSS that will be injected.
`on_navigate`	`def fn()`	`None`	Callback that receives one variable `href`.
`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.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. Content plugin vars are found under the object: `plugin`.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.

Erase Phantoms

mdpopups.erase_phantoms

Erase all phantoms associated with the given key. Included for convenience and consistency.

Parameter	Type	Default	Description
`view`	`sublime.View`		A Sublime Text view object.
`key`	`str`		A key that is associated with phantoms. Multiple phantoms can share the same key, but each phantom will have its own id.

Erase Phantom by ID

mdpopups.erase_phantom_by_id

Erase a single phantom by its id. Included for convenience and consistency.

Parameter	Type	Default	Description
`view`	`sublime.View`		A Sublime Text view object.
`pid`	`str`		The id associated with a single phantom. Multiple phantoms can share the same key, but each phantom will have its own id.

Query Phantom

[sublime.Region] mdpopups.query_phantom

Query the location of a phantom by specifying its id. A list of sublime.Regions will be returned. If the phantom with the given id is not found, the region will be returned with positions of (-1, -1). Included for convenience and consistency.

Parameter	Type	Default	Description
`view`	`sublime.View`		A Sublime Text view object.
`pid`	`int`		The id associated with a single phantom. Multiple phantoms can share the same key, but each phantom will have its own id.

Query Phantoms

[sublime.Region] mdpopups.query_phantoms

Query the location of multiple phantoms by specifying their ids. A list of sublime.Regions will be returned where each index corresponds to the index of ids that was passed in. If a given phantom id is not found, that region will be returned with positions of (-1, -1). Included for convenience and consistency.

Parameter	Type	Default	Description
`view`	`sublime.View`		A Sublime Text view object.
`pids`	`[int]`		A list of ids associated with phantoms. Multiple phantoms can share the same key, but each phantom will have its own id.

Phantom Class

mdpopups.Phantoms

A phantom object for use with PhantomSet.

Parameter	Type	Default	Description
`region`	`sublime.Region`		Region in the view where the phantom should be inserted.
`content`	`str`		Markdown/HTML content for the phantom.
`layout`	`int`		How the HTML content should be inserted. Acceptable values are: `sublime.LAYOUT_INLINE`, `sublime.LAYOUT_BLOCK`, and `sublime.LAYOUT_BELOW`.
`md`	`bool`	`True`	Defines whether the content is Markdown and needs to be converted.
`css`	`str`	`None`	Additional CSS that will be injected.
`on_navigate`	`def fn()`	`None`	Callback that receives one variable `href`.
`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.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. Content plugin vars are found under the object: `plugin`.A dictionary containing options for the Jinja2 template environment. This only applies to the HTML/Markdown content.

Attributes

Attribute	Type	Description
`region`	`sublime.Region`	Region in the view where the phantom should be inserted.
`content`	`str`	Markdown/HTML content for the phantom.
`layout`	`int`	How the HTML content should be inserted. Acceptable values are: `sublime.LAYOUT_INLINE`, `sublime.LAYOUT_BLOCK`, and `sublime.LAYOUT_BELOW`.
`md`	`bool`	Defines whether the content is Markdown and needs to be converted.
`css`	`str`	Additional CSS that will be injected.
`on_navigate`	`def fn()`	Callback that receives one variable `href`.
`wrapper_class`	`str`	A string containing the class name you wish wrap your content in. A `div` will be created with the given class.
`template_vars`	`dict`	A dictionary containing template vars. These can be used in either the CSS or the HTML/Markdown content.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`	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`.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.

Phantom Set Class

mdpopups.PhantomSet

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

Parameter	Type	Default	Description
`view`	`sublime.View`		A Sublime Text view object.
`key`	`str`		The key that should be associated with all related phantoms in the set.

Methods

mdpopups.PhantomSet.update

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

Parameter	Type	Default	Description
`new_phantoms`	`[mdpopups.Phantom]`		A list of MdPopups phantoms. `sublime.Phantom` will be converted to `mdpopups.Phantom`.

New HTML Sheet

mdpopups.new_html_sheet

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

Parameter	Type	Default	Description
`window`	`sublime.Window`		A Sublime Text view object.
`name`	`str`		Name for the HTML sheet.
`contents`	`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 `new_html_sheet` call.
`group`	`int`	`-1`	Specify window group.
`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.

New 3.6.0

new_html_sheet is new in 3.6.0. This feature should be considered experimental.

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.

Update HTML Content

Experimental Feature

This feature is new in Sublime Text 4. Sublime's API may change in future versions for this feature and may break this.

mdpopups.update_html_sheet

Accepts Markdown and updates the content of a Sublime HTML sheet. By default, the built-in Sublime syntax highlighter will be used for code highlighting.

Parameter	Type	Default	Description
`sheet`	`sublime.HtmlSheet`		A Sublime Text HTML sheet object.
`contents`	`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.
`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.

New 3.6.0

new_html_sheet is new in 3.6.0.

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.

Clear Cache

mdpopups.clear_cache: Clears the CSS theme related caches.

Markdown to HTML

str mdpopups.md2html

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.

Parameter	Type	Required	Default	Description
`view`	`sublime.View`	Yes		Sublime text View object.
`markup`	`string`	Yes		The markup code to be converted.
`template_vars`	`dict`	No	`None`	A dictionary containing template vars. These can be used in either the CSS or the HTML/Markdown content.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`	No	`None`	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`.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.

Color Box

str mdpopups.color_box

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.

Parameter	Type	Default	Description
`colors`	`[str]`		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`		The color for the color box border. Input is a RGB color formatted as `#RRGGBB`.
`border2`	`str`	`None`	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`	`32`	Height of color box.
`width`	`int`	`32`	Width of color box.
`border_size`	`int`	`1`	Width of the color box border. If using `border2`, the value should be set to at least 2 to see both colors.
`check_size`	`int`	`4`	Size of checkered box squares used for the background of transparent colors.
`max_colors`	`int`	`5`	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.
`alpha`	`bool`	`False`	Will create color box images with a real alpha channel instead of simulating one with a checkered background.
`border_map`	`int`	`0xF`	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.

Color Box Raw

bytes mdpopups.color_box

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

Parameter	Type	Default	Description
`colors`	`[str]`		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`		The color for the color box border. Input is a RGB color formatted as `#RRGGBB`.
`border2`	`str`	`None`	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`	`32`	Height of color box.
`width`	`int`	`32`	Width of color box.
`border_size`	`int`	`1`	Width of the color box border. If using `border2`, the value should be set to at least 2 to see both colors.
`check_size`	`int`	`4`	Size of checkered box squares used for the background of transparent colors.
`max_colors`	`int`	`5`	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.
`alpha`	`bool`	`False`	Will create color box images with a real alpha channel instead of simulating one with a checkered background.
`border_map`	`int`	`0xF`	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.

Tint

str mdpopups.tint

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

Parameter	Type	Default	Description
`img`	`str/bytes`		Either a string in the form `Packages/Package/resource.png` or a byte string of a PNG image.
`color`	`str`		A string in the form of `#RRGGBB` or `#RRGGBBAA` (alpha layer will be stripped and ignored and is only allowed to make it easy to pass in colors from a color scheme).
`opacity`	`int`	`255`	An integer value between 0 - 255 that specifies the opacity of the tint.
`height`	`int`	`None`	Height that should be specified in the return HTML element.
`width`	`int`	`None`	Width that should be specified in the return HTML element.

Tint Raw

bytes mdpopups.tint_raw

Takes a either a path to an PNG or a byte string of a PNG and tints it with a specific color and returns a byte string of the modified PNG.

Parameter	Type	Default	Description
`img`	`str/bytes`		Either a string in the form `Packages/Package/resource.png` or a byte string of a PNG image.
`color`	`str`		A string in the form of `#RRGGBB` or `#RRGGBBAA` (alpha layer will be stripped and ignored and is only allowed to make it easy to pass in colors from a color scheme).
`opacity`	`int`	`255`	An integer value between 0 - 255 that specifies the opacity of the tint.

Scope to Style

dict mdpopups.scope2style

Takes a sublime scope (complexity doesn't matter), and guesses the style that would be applied. While there may be untested corner cases with complex scopes where it fails, in general, it is usually accurate. The returned dictionary is in the form:

{
    # 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'
}

Parameter	Type	Default	Description
`view`	`sublime.View`		Sublime text View object so that the correct color scheme will be searched.
`scope`	`string`		The scope to search for.
`selected`	`bool`	`False`	Whether this scope is in a selected state (selected text).
`explicit_background`	`bool`	`False`	Only return a background if one is explicitly defined in the color scheme.

Syntax Highlight

str mdpopups.syntax_highlight

Allows for syntax highlighting outside the Markdown environment. You can just feed it code directly and give it the language of your choice, and you will be returned a block of HTML that has been syntax highlighted. By default, the built-in Sublime syntax highlighter will be used for code highlighting.

Parameter	Type	Default	Description
`view`	`sublime.View`		Sublime text View object.
`src`	`str`		The source code to be converted. No fence tokes are needed (```).
`language`	`str`	`None`	Specifies the language to highlight as.
`inline`	`bool`	`False`	Will return the code formatted for inline display.
`allow_code_wrap`	`bool`	`False`	Do not convert all the spaces in code blocks to ` ` so that wrapping can occur.
`language_map`	`Dict`	`None`	Language map that can be passed in to add to the built-in language map. Mainly for Plugins to add plugin specific languages that are too specific to be added globally.

New in 4.1.0

Added language_map parameter. See sublime_user_lang_map option to learn more about the structure.

Tabs to Spaces

str mdpopups.tabs2spaces

The Markdown parser used converts all tabs to spaces with the simple logic of 1 tab equals 4 spaces. This logic is generally applied in other places like syntax_highlight. When formatting code for syntax_highlight, you may want to translate the tabs to spaces based on tab stops before passing it through opposed to apply the simple logic of converting all tabs to 4 spaces regardless of tab stops. tabs2spaces does exactly this, allowing you format the whitespace in a more intelligent manner.

tabs2spaces cannot do anything about characters, and there are some even in monospace fonts, that are wider than normal characters. It doesn't detect zero width characters either. It also cannot predict cases where two or more Unicode character are shown as one. But in some cases, this more intelligent output is much better than the "all tabs are arbitrarily one size" logic.

Example (Notice that ♭ is a bit larger than normal characters):

>>> 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

Parameter	Type	Default	Description
`text`	`str`		Text to convert.
`tab_size`	`int`	`4`	Tab size.

Get Language From View

str mdpopups.get_language_from_view

Allows a user to extract the equivalent language specifier for mdpopups.syntax_highlight from a view. If the language cannot be determined, None will be returned.

Parameter	Type	Default	Description
`view`	`sublime.View`		Sublime text View object.

Resolve Remote Images

str mdpopups.resolve_images

This was added to download remote images. resolve_images accepts an HTML buffer, a resolver and a callback and will search the HTML buffer for image URLs and download them if appropriate.

Since this function can have a resolver that can download the images asynchronously, it is not performed in the main path when showing popups or phantoms.

Ideally, this would be used after manually running Markdown through md2html.

The following resolve functions are available:

Name	Description
`blocking_resolver`	A blocking image resolver. Will block while download an image.
`ui_thread_resolver`	Will execute image downloads on the main thread.
`worker_thread_resolver`	Will execute image downloads on the worker ("async") thread of Sublime Text.

Parameter	Type	Description
`minihtml`	`str`	A `minihtml` string buffer.
`resolver`	function	A function that resolves an image URL by downloading it. It accepts a URL and callback.
`on_done`	function	A callback for when the image resolving is complete. Accepts a `minihtml` string buffer.

New in 4.0

This is a new feature added in 4.0, and is currently considered experimental.

Last update: July 23, 2022

API

Dependencies

Markdown Support

Extensions

Frontmatter

Enable Code Wrapping

Custom Fences

Configure Markdown Extensions

Configure Frontmatter From Python Objects

Styling

API Usage

Version

Show Popup

Update Popup

Hide Popup

Is Popup Visible

Add Phantom

Erase Phantoms

Erase Phantom by ID

Query Phantom

Query Phantoms

Phantom Class

Phantom Set Class

New HTML Sheet

Update HTML Content

Clear Cache

Markdown to HTML

Color Box

Color Box Raw

Tint

Tint Raw

Scope to Style

Syntax Highlight

Tabs to Spaces

Get Language From View

Resolve Remote Images