How to get nice <kbd> formatting in my documentation

Keyman
1

Hi there,

I have noticed that <kbd></kbd> is a popular HTML marker on the web for representing keystrokes, and that different websites use CSS to format them in different ways.

I would really like to use this in the documentation for my keyboard. I anticipate it to show up at:

I really like the formatting on this page:
Step 5: Rules with Context

Screenshot_20240330-192933_Chrome
Screenshot_20240330-192933_Chrome1080×2081 322 KB

In the documentation of the most poplar keyboards I have only been able to find this formatting, which is similar but not quite as easy to read:

https://help.keyman.com/keyboard/ekwtamil99uni/2.0.5/ekwtamil99uni

Screenshot_20240330-193120_Chrome
Screenshot_20240330-193120_Chrome1080×1330 257 KB

Peaking under the hood it looks like it was also implemented with a different strategy, not with <kbd> tags.

In yet another documentation which I looked up on GitHub, it looks like the formatting was done with markdown.

What is the best way to create nice formatting for keystrokes?

What markup language should I use as I write the documentation?

Thanks so much for your help!

2

This video is gold:

Here’s his custom CSS:

image

When I upload the documentation to keyman.com/keyboards, would that page access the same CSS that formatted <kbd> in the first example? Or, would I be able to add my own custom CSS?

On a related note, I wonder if there is a way to modify the CSS so that the key shows as white normally, but dark gray with white text if the device is in dark mode? How could that be implemented?

3

Quite a lot of questions here!

Markdown is not yet supported for keyboard documentation. The documentation should be in HTML (and the PHP version should have the HTML header and closing body/html elements removed and replaced with the standard PHP preamble. See #9477 as we want to implement Markdown support a future feature – and a large part of the aim is to allow merging the .php and welcome.htm sources.

<kbd> is the best way forward.

The keyboard pages inherit the site CSS on help.keyman.com, so it’s best not to add custom CSS to the .php file as it can conflict with the site CSS – especially as we change the site CSS in the future.

You may wish to copy the CSS specifically for the kbd elements from help.keyman.com into your local welcome.htm. (Note, when we implement #9477, we will definitely include CSS for kbd elements).

CSS supports dark mode media selectors with prefers-color-scheme.

We don’t yet have dark mode theming for help.keyman.com – I don’t think we have an issue open for it, but we accept pull requests!

4

Thanks so much Marc for all of the answers and info!

I play around with HTML and CSS some, but have never gone so far as submitting a pull request! Although as I think about it a bit more, the keys implemented with <kbd></kbd> are a nice midtone gray, so maybe that extra dark mode complexity isn’t needed after all.

Sounds like when I do my HTML documentation I just need to use <kbd></kbd> and trust Keyman’s CSS to take care of the formatting.

I will also copy the CSS specifically for the kbd elements from help.keyman.com into my local welcome.htm.

Just for reference, this is the related CSS I found on help.keyman.com as of today, in case any future reader is looking for it:

kbd {
    background: none repeat scroll 0 0 #CCCCD0;
    border: 1px solid #808080;
    border-right: 2px solid #606060;
    border-bottom: 2px solid #606060;
    border-radius: 4px;
    color: #000000;
    font-family: "NotoSans-Regular-Ascii";
    font-size: 13px;
    font-weight: bold;
    margin: 0;
    padding: 1px 4px;
    min-width: 1.5em;
    text-align: center;
    display: inline-block;
}

In Chrome I right-clicked a key from this page and hit Inspect. On the far right, under Styles, it shows the relevant CSS.

Thanks again!

1 Like