Roles¶

This page provides an overview of the features Esbonio provides to make working with MyST Roles easier.

Completion¶

The most obvious feature is the completion suggestions, try inserting a {ref} role on the next line that links to the myst-roles-completion label defined above.

In addition to :ref: labels, esbonio supports suggesting values for many other types of target

Local docnames for the doc role
Local filenames for the download role
Python objects for roles like py:class, py:func and more!
Targets defined in other Sphinx documentation sites for the external role! See sphinx.ext.intersphinx – Link to other projects’ documentation for more details

Feel free to experiment with each of the roles mentioned above!

Document Links¶

Many text editors will automatically detect links to webpages e.g. https://sphinx-doc.org and make them clickable. The textDocument/documentLink request allows language servers to do the same.

When it makes sense to, esbonio will add clickable links to many role targets, including

Local docname references
Local files ./roles.md
Intersphinx references e.g. Exceptions raised during logging

See for yourself by pressing Ctrl +Clicking one of the above references

GoTo …¶

… Definition¶

Esbonio supports GoTo Definition requests for role targets, including

Local files ./roles.md
Documents Roles
References Completion
Python objects counters.pattern.PatternCounter

Try invoking GoTo Definition on any of the above targets.

Hover¶

Esbonio provides documentation hovers for role targets, including:

Local Python objects, for example:

Hover over any of the above targets to see their associated content.