jGleitz/markdown-it-kbd

Allow pymdown-extensions syntax for kbd

Closed this issue · 3 comments

alkisg commented

I've started using your extension for live previewing of my mkdocs-based documentation. It's awesome, thank you!

I bumped into a small issue with kbd. The pymdown-extensions syntax is ++Ctrl+Esc++, while yours is [[Ctrl+Esc]].
I didn't find any other syntaxes online regarding kbd, so I can't say which one is better.
But currently I can either preview in vscode, OR have the correct results in mkdocs.

Would it be possible to either agree in a common syntax for this, or to support both of them?
I also filed a similar issue in pymdown-extensions: facelessuser/pymdown-extensions#1517

kgidarakos commented

This feature affects me too. I hope it will be added soon!
Thank you in advance.

jGleitz commented

Hi, thank you for your request! Before I created this plugin, I made sure to search the web for any existing syntax, to avoid exactly the situation of ‘competing standards’ that we have right now. Seem like that did not work out.

I would be willing to add an option to this plugin that allows modifying the delimiters. I think the required changes would me rather small. However, that would not improve your situation much, would it? Since you are consuming this plugin through a VSCode extension, you won’t be able to set the setting, even if I added it, will you?

Generally speaking, I think the best course of action would be to try to standardize the syntax somewhere. I would consider making a breaking change to adapt to an established standard. If you do, please don’t use the ++ syntax. For starters, I don’t think it fulfills mardown’s goal of being easy to understand. [[x]] looks at least somewhat like a key with an x in it. Furthermore, something like ++Ctrl+T++ (or even ++Ctrl++ + ++T++) is just hard to parse for a human.

alkisg commented

Thank you @jGleitz. Seeing that it's hard to end up in a common convention, we ended up using this syntax:
**`Ctrl`**+**`Alt`**+**`Del`**

Benefits:

  • It renders nicely anywhere, even here on Github: Ctrl+Alt+Del
  • With a custom css for strong > code we are able to add a shadow etc to make it look even more like a key

Drawbacks:

  • The markdown source code is a big long and ugly.

Then we started extending that idea to other areas, e.g. we're now using *** (=strong>em) for menus and GUI labels:
Launch Applications ▸ Utilities ▸ Calculator and then press the OK button.

This displays nicely in any markdown environment, and with a custom css we're giving them a button-like appearance.