myst-gui-text

A MyST plugin for referring to GUI elements in prose: buttons, menu items, tabs, and fields. It brings back Sphinx’s {guilabel} and {menuselection} roles, which don’t exist in MyST.

Enable it in your myst.yml plugins list:

project:
  plugins:
    - https://github.com/myst-contrib/myst-gui-text/releases/latest/download/index.mjs

Buttons and labels¶

Wrap any on-screen label in the {gui} role:

Click {gui}`Add secret` to confirm.

Role bodies are plain text, so an icon can’t go inside a chip. To pair an icon with a label, put an icon role such as myst-iconify’s {icon} right before {gui}:

Open {icon}`cog` {gui}`Administration > Service accounts`.

Menu paths¶

Describe a sequence of clicks in a single role. Separate the steps with -->, ->, →, ›, or a spaced >. They all render the same way:

Go to {gui}`Settings > Secrets and variables > Actions`.

Navigate to {gui}`Dashboards --> JupyterHub Default Dashboards -> Home Directory Usage`.

A > without spaces around it is not a separator, so placeholder labels stay intact:

Open {gui}`<Username dropdown> --> Organizations`.

A separator always splits, even if the on-screen label itself contains one. There is no escape syntax.

Migrating from Sphinx¶

{guilabel} and {menuselection} are aliases of {gui}, so content written for Sphinx renders without changes:

Click {guilabel}`Use this template`, then go to {menuselection}`Admin --> Automation Rules`.

Keyboard shortcuts¶

For keyboard shortcuts, use MyST’s built-in {kbd} role:

Press {kbd}`Ctrl + Shift + P` to open the command palette.