MPS 2023.3 Help

Documentation Facet


The documentation language allows you to document your language structure. The documentation will be instantly available to the users of your language's structure model through information popup dialogs (aka tootips) and a dedicated Documentation Tool window. Additionally, the documentation can be also generated into HTML javadoc-style documentation.

How to start

Enabling documentation for your language is fairly easy:

  1. Navigate to Module Properties of your language.

  2. Enable the Documentation facet in the Facets tab.

    Facets tab
  3. Choose the desired output directory for your generated documentation and close the dialog with either "Apply" or "OK".

    The Facet
  4. Now you are set up to add documentation to any concept definition in the structure model of your language. Use the Add Documentation intention from the intention menu while the concept is open in the editor.

Writing documentation

There are several languages involved in documenting languages. Namely the jetbrains.mps.lang.core.doc language, the jetbrains.mps.lang.docText language and mostly the jetbrains.mps.lang.text language, in which the actual text of the documentation is expressed. This language consists of several concepts:


Represent individual words. You can change the style of a word (bold, italic, or underlined) and optionally add a URL link. This is all set in the Inspector tool window for an individual word.

Word styling in Inspector

Shortcuts and MarkDown syntax are also available to set styles on individual words as well as on larger portions of text (press Enter to have the MarkDown style applied to a word).

  • Italics (Control + I) - *word* or _word_

  • Bold (Control + B) - **word** or __word__

  • Bold Italics - ***word*** or ___word___

  • Underlined (Control + U) - ~~word~~

The URL can be added to a word either in the Inspector tool window or using the Add URL intention.

References to nodes can also be inserted into the documentation text. Simply type the name of the node to reference and the completion menu will offer you all the matching available nodes:

Completing a node reference

To insert code into the documentation text, type ``` and then press space. You will see an empty field that can hold code (aka an MPS node).

Empty field to insert code

Then press Control + Space and select the desired node from the completion menu.


You have the flexibility to select from various line types:

Line types

To change the line type, you can pick one from the Intentions menu or employ a specific syntax or a shortcut.


MarkDown Syntax



# H1

Control + 1


## H2

Control + 2


### H3

Control + 3


#### H4

Control + 4


##### H5

Control + 5


###### H6

Control + 6


Control + 0

Header styles applied


Both bullet and numbered lists are available. You can use MarkDown or intentions to set or change the list style to a line.


MarkDown Syntax

Bullet line

- line

Numbered line

1. line

List styles applied

Viewing documentation

To see a popup dialog with documentation simply hower your mouse over a reference to the concept or press F1 when the cursor is on the reference.

Quick view

A Documentation Tool Window is also available. It instantly shows the documentation for the concepts under the cursor.

Documentation tool window

Generating documentation

Click on the structure aspect model in the Logical View and select Preview Generated Documentation from the list.

Preview Generated Documentation

All the generated html and css files will be saved in the folder selected in the Documentation Facet tab of the language's Module Properties dialog.

The generated documentation will contain one index file and then html files for all concepts in the language's structure model.

Generated index.html
Generated concept documentation
Last modified: 07 March 2024