MdPopups 2.0 Notification

[facelessuser]

For any who use mdpopups, I plan on releasing a new 2.0 version around the beginning of June. The reason for this notification is to give those who use it a chance to make necessary changes.

A lot has changed with popups and phantoms since it was debuted in Sublime, and mdpopups has been carrying around some of that legacy junk. Not only that, but as I’ve had it out in the wild, I understand better how people want to use it and do use it.

The road map is here, but I want to just touch the main points people will care about.

Important Points

1. MdPopups shouldn’t be used on Sublime versions < 3124. You should probably limit your plugin’s usage of MdPopups to 3124+.

2. MdPopups will no longer have css classes like comment etc. If you want to get the CSS for a given scope, you will have to use a template filter to get those. It just clutters the the CSS namespace (I guess that’s what you’d call it). In general, the popups should get their colors from themes. In general it is encouraged to use things like sublimes CSS variables --redish etc. If Sublime can’t calculate good colors for these variables, you should request that your favorite color schemes defines good values for those. Worse case scenario, a user can define them in their custom override CSS mdpopups.css in their User folder.

Other Notes

Other changes should be mild cosmetic changes that can be patched after release. For instance, Mdpopups will no longer the overall popup padding, that will be left up to plugins, or the user can override the plugin if they don’t like it. Stuff like this is really dependent on the content and how it’s being used. Just remember to wrap your content properly with some plugin specific class so people can target it for your specific plugin.

CSS is more flexible. Plugins will now be able to override stuff in the default.css. Content context is important, so I’m going to be less strict here. Just be kind and wrap your plugin content with a class to allow your Users to override what they don’t like.

There’s other new cosmetic stuff as well.

---

Anyways, prepare now for the new version by limiting MdPopups usage to 3124+. And if you must get CSS equivalents for syntax scopes, don’t use the things like the comment class anymore, but use the template filters to acquire CSS.

After release you may need to tweak some minor cosmetics, but probably shouldn’t worry about that now.

If you have some input, popup over to the road map issue and give it there. I’m probably not going to make major changes between now and release, but now is your chance to give your input before release.

[rppn]

I believe we can simply use https://github.com/facelessuser/sublime-markdown-popups/compare/1.13.1...master as a reference?

[facelessuser]

@rppn That’s fine. Some of my commit notes may not be that great, and I flip flopped on some things. But it does give a complete diff, but I’m not sure how much fun it is to look through all of that .

This might be more helpful for developers who use it. If people want to try it out, you can play with the master. You can create your own channel and add this:

        {
            "name": "mdpopups",
            "author": "facelessuser",
            "load_order": "55",
            "description": "Markdown Popups for Sublime",
            "issues": "https://github.com/facelessuser/sublime-markdown-popups/issues",
            "releases": [
                {
                    "base": "https://github.com/facelessuser/sublime-markdown-popups",
                    "branch": "master",
                    "sublime_text": ">=3080"
                }
            ]
        }

More info here: https://github.com/facelessuser/sublime-markdown-popups/issues/16#issuecomment-255216580.

[facelessuser]

Hopefully most people have moved to using native rem sizes instead of using the relativesize template filter, but if you haven’t, I’ve dropped support for relativesize in 2.0. It was always hacky, but at the time it was the only available way to get relative sizes, but since Sublime added rem (in 3119?) it doesn’t make since to support relativesize when we have something native that is much better.

[facelessuser]

MdPopups 2.0 is not tentatively finished, so try it out get your plugins ready. If you find any issues between now and June, or think some small change would be beneficial before now and then, let me know. The tip of master should reflect it’s final release and will report it’s version as 2.0, so if you need to put a template switch around some CSS for 2.0, you can, and you can verify it works with current master.

Though the current rendered doc site reflects the old version, you can read through the documentation source on master and see the current changes. I’ve tried to break things up more to make it an easier read. I’ve also provided a changelog in the docs which currently just shows the 2.0 changes.

One small change that occurred in the last couple of days is to the css template filter. To obtain CSS for a given scope, you had to provide the scope in CSS class form (.my-scope.in.css.class.form), and those scopes had to align with common TextMate base scopes. Since we no longer generate CSS classes for scopes to clean up the CSS namespace, we no longer need to adhere to a specific list of scopes. Now you can give the filter whatever scope you want, and it no longer should be in CSS class form (but it should pass through fine if you still have it defined that way as they are valid scopes preceded by a dot which will now get stripped). Anyways, there are a couple of small changes to the filter as well that won’t affect most people.

Anyways, assuming I don’t get any bug reports, the rest of my time will be spent preparing my plugins that use mdpopups for the release in June.

[facelessuser]

Preview of the new look of things.

There will be some differences between 3127+ and <3127 just because borders are a new thing. For instance Admontions in <3127 will look more like this:

So some contrast issues may occasionally occur with <3127 in admonitions but plugins and/or users should be able to target and patch those minor details with CSS in <3127 (or get on the latest ST dev build with a license ). But in the next official beta, and definitely in the official 3.0 release, users will get the better bordered versions.

[facelessuser]

Everything is on track. All my plugins are updated to handle the new change. Release will be on June 1st.

[facelessuser]

It’s released. Run Satisfy Packages to pick up the latest. In the next few days, I will start the process to adjust Package Control to limit installing it for anything less than 3124.

[r-stein]

Wouldn’t it be possible to install 1.13 on older builds and 2.0 on newer builds?

[facelessuser]

Not sure if Package Control allows that with dependencies. If it does, I guess that’s okay, but I have no intention of offering support for this on ST builds lower than 3124. My basic response would be too upgrade to the latest beta.

[facelessuser]

So looking into this, I don’t really see a path for allowing 1.13 on some builds and 2.0 on others without creating separate tags to release from, and even then, I don’t know if the dependencies support that kind of tag prefix.

Personally, I think allowing packages to continue using 1.13 is just going to be more pain on developers, and I think in general, it would be better if some holdouts upgrade to one of the last two betas as they are pretty stable (now that’s my opinion, others might disagree), but any betas below that are over a year old. I don’t bother debugging issues on anything lower than 3124 anymore.

I also made mention here to give developers a chance to prepare, and also give them a chance to voice that they need more time (never really got that kind of feedback).

It may sting a little to those on old builds, but with the popup/phantom API now more stable, carrying around all of the old experimental legacy baggage needed to be cut.

If someone can show me a path to provide 1.13 to older builds with minimal effort, I will do that, but if not, I’m okay with completely dropping support for older builds.

---

On a side note, I most likely will remove ST2 support from Package Control on all my packages with ST3 official release. I keep exceeding tag release threshold on certain packages requiring me to go in and prune old tags. I have to do this as the last ST2 tag keeps getting pushed past that threshold. So I have to prune ST3 tags or periodically release a new ST2 tag just to keep it over the threshold. And I really don’t want to manage that for ST2, ST3, and ST4 builds in the future.

[facelessuser]

Limiting change for 3124+ is now on Package Control Channel.

[facelessuser]

2.1.0

June 20, 2017

• NEW: Allow adding and configuring extensions via YAML frontmatter. This feature deprecates nl2br function parameter which will be removed some time in the future.
• NEW: Allow setting whether block, code tags will allow word wrapping via YAML frontmatter. This feature deprecates the allow_word_wrap function parameter which will be removed some time in the future.
• NEW: Expose SuperFences’ custom_fences feature via YAML frontmatter.
• NEW: Upgrade internal extensions.
• NEW: Import official pymdownx extension if pymdownx is installed as a dependency so we can drop internal vendored extension copies in the future. This is allowed to be optional for a time until people can update their dependencies.
• NEW: Import pyyaml extension if pyyaml is installed for frontmatter. This is allowed to be optional for a time until people can update their dependencies.
• NEW: inline-highlight class in no longer applied to inline code. Instead highlight is applied to both inline and block code.

This should be backwards compatible and only add features to those who wish to take advantage of it. To see new features in actions, you can clone the test repo mdpopup_test, and run the test commands. Check out the test repo source to see how the new features are used.

---

Notes

1. If you were overriding inline-highlight class in the past, inline code now has the same class as block code: highlight. To specifically target inline code, please use: code.highlight.

2. New configurations are available via YAML frontmatter. Frontmatter support was added to help eliminate the need to keep adding parameters to API functions when a new feature is added. The API function parameters nl2br and allow_code_wrap have been moved to frontmatter, but are also still available as function parameters for now.

3. mdpopups.mdx.superfences, mdpopups.mdx.inlinehilite, and mdpopups.mdx.highlight cannot be removed and should not be replaced with other code highlight extensions. And they cannot be configured directly like other extensions as they are specially included and configured to ensure code highlighting is sourced from Sublime color schemes.

Do I have to do anything?

Nope. You can keep using the API as is for now. At some point, once it has been long enough that most people’s systems have upgraded to 2.1.0+, you could start migrating over to using YAML frontmatter. I do not plan on dropping legacy support until 2018.

I want to use the new features, how can I get started?

If you are itching to configure Markdown extensions and such, you can start right a way, but you will have to be prepared to tell your users to ensure they are using the latest mdpopups, or you will have to add some abstraction to handle mdpopups < 2.1.0.

To start using new features, do the following (abstraction is left up to devs who wish to support both old and new):

1. Add new dependencies pyyaml and pymdownx.

2. Refrain from using function parameters nl2br and allow_code_wrap and instead use frontmatter options to modify your extension environment. If a function parameter is defined, and the relevant YAML frontmatter option is configured, the frontmatter will override the function parameter.

3. Append special options via frontmatter. If it is easier to work with your settings as a Python dictionary, an API function has been provided to turn your dictionary directly into frontmatter to prepend to your content. As always, check out the documentation for more details.

[rwols]

I know this plugin is geared towards markdown, but do you have any plans for processing reStructuredText, too?

[facelessuser]

While I’m not against adding reStructuredText, the reason mdpopups is just Markdown or pure HTML is based on my knowledge.

• I use Markdown a lot so I understand it very well.
• I am extremely familiar with the underlying Python Markdown library. It is very flexible and allows me to override anything making it easy to special format things for Sublime’s minihtml, and to provide special code blocks highlighted with Sublime’s current syntax file.

In order to do this for reStructredText, I would at the very least need to be aware of a good flexible Python reStructredText module. I would possibly need someone familiar with reStructredText to verify basic syntax renders well in Sublime.

I’m not saying I will or won’t add such functionality, only that I am open to learning more about how this could theoretically be integrated. Do you have any background with working with reStructedText and Python?

[rwols]

Do you have any background with working with reStructedText and Python?

Wish I had My only experience is using the docutils library for converting RST to HTML. I can only point you in that direction; or maaybe do it myself and turn it into a PR, but those chances are slim.

[facelessuser]

There are a couple of things to consider.

1. Is docutils a pure python library? If not, we would need someone dedicated to host that package as it would require building binaries for cross platform use. That is a pain. If it is pure Python, it is no big deal and easy to maintain as a dependency.

2. Does it rely on external tools? This is a no go for me. The Python module should include everything so a user can just have Package Control install mdpopups and have everything they need. I don’t mind giving the developer options for input, but if it requires the user to jump through hoops installing external binaries just so the developer can use a different input, then this goes against my current goals.

3. It would be expected that whatever Python module is being used would be a dependency to mdpopups. I have no interest in vendoring a special RST module, but I don’t mind the idea of a derived class wrapper if small tweaks need to be made as long as we are not rewriting tons of classes.

4. It must be fairly easy to override certain things like syntax highlighting. If it is deeply embedded and the module is not extensible, this poses a problem as I would have to do excessive hacking that may be quite fragile and break on upgrade of the dependency.

I can only point you in that direction;

If I were to consider this, I would need someone to do some investigative work and answer these questions. I have no use for RST support, so I have no interest in doing this groundwork, but I am leaving it open if someone is willing to answer these questions.

If you are willing to investigate these things, and if docutils does not meet these requirements, and you find something that does, then I would be willing to look into this further and evaluate whether this is something I will add.

[facelessuser]

Mdpopups 3.0.0 has been released with support for new .sublime-color-scheme files. Should handle new color scheme overrides and conventions.

If your plugin uses Mdpopups and find issues, please let me know.

[rppn]

Thank you, this is awesome!

[mg979]

I have problems with the new version (3.0.0).
Before it looked like this (picture from not updated version 2.1.1 from a portable installation):

---

Now it looks like his:

---

The console says:

mdpopups: Failed to convert/retrieve scheme to CSS!

I can’t pass any css anymore to the popups/phantoms, it doesn’t accept them…