SDK Docs Style Guide

Each Markdown file must start with a copyright notice, formatted using HTML comment notation:

<!-- Copyright 2000-2025 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->

It must be followed by a header defining its title using a level 1 heading:

# Contributing to the IntelliJ Platform SDK

The page title should be as concise as possible, so it can be reused in the Table of Contents as is.

<link-summary>Defining groups of related settings.</link-summary>

Consistent terminology helps the reader grasp new concepts more quickly:

• The open-source code in the GitHub repository intellij-community is known as the IntelliJ Platform. Use the full phrase in the SDK documentation.

• IDEs based on the IntelliJ Platform are described as IntelliJ Platform-based IDEs. Once that term is used on a page, authors may use IDEs.

• When referring to JetBrains products, always use the full name such as IntelliJ IDEA Ultimate Edition. However, only use product names when extensibility or functionality is particular to a product.

tip

Do not use TODOs

TODO/todo comments are discouraged in the main branch of intellij-sdk-docs. There are always exceptions, but the best practice is to resolve all TODOs before the final review. If immediate resolution isn't possible, write a YouTrack SDK Issue that captures the TODO and remove the comment from the document.

Start every sentence on a new line. For very long sentences, add additional line breaks after ,, : or other sensible places. Very long links should also be on a separate line.

Consistent text styles are used to standardize references and keywords:

• Menu paths are wrapped using <ui-path> with pipe characters separating each level: <ui-path>Settings | Editor</ui-path>: Settings | Editor Inside tables, use | instead of | to prevent escaping problems.

• User interface element names like labels, buttons, checkboxes, etc. are wrapped using <control>: Press <control>Continue</continue>: Press Continue

• Non-code keywords and quotations, or the names of non-code files are formatted as italic style: _Theme_ (Theme), _README.md_ (README.md.) Examples of this file type include LICENSE.txt and README.md.

• Code keywords and class names are formatted as code style: `interface`: interface, `AnAction`: AnAction, `name` attribute: name attribute.

• Filenames are wrapped using <path>: <path>build.gradle.kts</path> build.gradle.kts.

• File formats are shown as all capital letters: PNG and XML.

• Filename extensions are not capitalized when part of a full filename, path, or URL: plugin.xml.

• When using $PLACEHOLDER$ in non-code parts, it must be escaped: <path>\$PLACEHOLDER\$/somePath</path>.

• Keyboard shortcuts are wrapped using <shortcut>: press <shortcut>Alt+Insert</shortcut> becomes "press Alt+Insert ".

• See Guidelines for Highlighting Syntax for best practices for representing code fragments.

• See Links to IntelliJ Platform Source for more details about representing names of source files in links.

Links are handled as standard Markdown links and can be anchored to external sites, pages within the site, or headings in the pages.

When a Markdown header is converted to an HTML header, it is assigned an ID so that it can be linked. For example, ## Basics gets the ID of basics, and can be linked either on the same page or cross-page as described below.

In some cases (e.g., the same heading text appears multiple times on the same page), it is necessary to specify a distinct ID manually:

## Task 1
### Properties
{#task1-properties}
[...]

## Task 2
### Properties
{#task2-properties}
[...]

In-paragraph code fragments and IntelliJ Platform APIs are formatted according to the following rules.

Source code is represented by using code fences, which are three backticks.

Syntax highlighting is applied by specifying the language after the first set of ticks:

```xml
<tagName attribute="value">XML Text</tagName>
```

Supported languages include xml, java, kotlin, groovy, bash, md, php, and text for plaintext.

note

Source code blocks must have one blank line before and after them and must have a language specification for highlighting (use text as fallback).

Whole files can be imported on a page using the src attribute after code fences specifying the full path relative to the code_samples root folder.

{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleFoldingBuilder.java"}

The advantage is the code can come from the code_samples directory, so it will be live code that isn't silently stale.

The disadvantage is the file may contain a large class, too large for the documentation page to be useful. If possible, use include-symbol="ClassName" to show only the class body without any headers and imports. To include only a specific method, specify include-symbol="methodName" additionally.

In any case, keep code samples concise and avoid any unnecessary "surrounding" code or import statements.

The syntax is to use the pipe (|) and minus symbols:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Blah     | Blah     | Blah     |

Use & #124; (remove space before #!) instead of | to prevent escaping problems for <ui-path> elements inside cells.

Use <p>Line 1</p><p>Line 2</p> for multi-line content in a cell.

Notes and callouts can be specified using the blockquote syntax. The converter looks at the type attribute specified after the text block. If so, it applies a callout style. The example below will be displayed as a callout, styled as a "note":

> This is a simple note.
>
{style="note"}

note

This is a simple note.

The styles available for callouts are:

• tip—Information that makes the reader more productive (Default).

• note—Information that is important for the reader to understand. This callout is reserved for essential points and concepts.

• warning—Information that is critical for the user to understand to prevent failures or errors.

Complex callouts can also specify the title attribute:

> This is a note.
> We have a lot of text.
> Don't make everyone read it fully by adding a good title.
>
{title="A useful title"}

tip

A useful title

This is a note. We have a lot of text. Don't make everyone read it fully by adding a good title.

Every page typically has a dedicated subdirectory within root /images.

Images in this documentation are generally screenshots. For consistency, images should be 296, 460, or 706 pixels wide. The preferred image format is PNG at a resolution of 144 DPI. A resolution of 72 DPI is acceptable but may look blurry on high-resolution monitors.

Use Window Resizer plugin for exact resizing of the IDE application window.

It is crucial to reduce the size of image files to prevent bloating the repository and impacting the performance of the documentation site. Optimize the image files using a tool such as the PNG optimizer plugin.

Images are embedded in a document by adding a Markdown link to the image like so:

![Alt text](image.png)

If the width of an image needs to be adjusted, it can be specified as follows:

![Alt text](image.png){width="42"}

![Alt text](image.png){thumbnail="true"}

![Alt text](image.svg){thumbnail-same-file="true"}

1. Use a concise and neutral voice when describing topics:

   • Avoid: "A custom icon for files with a substituted language would be a great addition to the plugin. It is easy as implementing the xyz extension point."

   • Prefer: "To add a custom icon for files with a substituted language, implement the xyz extension point."

2. Avoid directly addressing the reader and the author with "you", "your", "we", etc.

   • Avoid: "Add a dependency in your plugin descriptor."

   • Prefer: "Add a dependency in the plugin descriptor."

If a node does not have its id attribute specified, it will still appear in the table of contents but will be greyed out and not clickable. It acts as a placeholder for a documentation item. A placeholder is useful to keep track of what should be documented but hasn't yet, and can be helpful to show readers that the topic exists but isn't yet documented (Pull Requests always welcome!).

When renaming pages, redirects must be configured so existing bookmarks continue working. All existing links in other topics must be updated.

Specify the previous path(s) including .html extension in accepts-web-file-names attribute:

<toc-element
        id="themes_getting_started.md"
        accepts-web-file-names="themes.html,themes-intro.html"/>