Skip to content

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:

These are 3rd 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.

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.

Update Popup

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.

Hide Popup

mdpopups.hide_popup

Hides the current popup. Included for convenience and consistency.

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

Is Popup Visible

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