Add article and tutorial about Navigation Bar

* add docs about navigation bar for Custom Language Support topic
* add info in `topics/intro/content_updates.md`
* renumber articles after the added tutorial
* add `custom_language_tutorial_header` to `structure_aware_navbar.md`

code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleStructureAwareNavbar.java

@@ -0,0 +1,44 @@
+// Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
+
+package org.intellij.sdk.language;
+
+import com.intellij.icons.AllIcons;
+import com.intellij.ide.navigationToolbar.StructureAwareNavBarModelExtension;
+import com.intellij.lang.Language;
+import org.intellij.sdk.language.psi.SimpleFile;
+import org.intellij.sdk.language.psi.SimpleProperty;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import javax.swing.Icon;
+
+public class SimpleStructureAwareNavbar extends StructureAwareNavBarModelExtension {
+    @NotNull
+    @Override
+    protected Language getLanguage() {
+        return SimpleLanguage.INSTANCE;
+    }
+
+    @Override
+    public @Nullable String getPresentableText(Object object) {
+        if (object instanceof SimpleFile) {
+            return ((SimpleFile) object).getName();
+        }
+        if (object instanceof SimpleProperty) {
+            return ((SimpleProperty) object).getName();
+        }
+
+        return null;
+    }
+
+    @Override
+    @Nullable
+    public Icon getIcon(Object object) {
+        if (object instanceof SimpleProperty) {
+            return AllIcons.Nodes.Property;
+        }
+
+        return null;
+    }
+
+}

code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleStructureViewFactory.java

@@ -1,4 +1,4 @@
-// Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+// Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
 
 package org.intellij.sdk.language;
 
@@ -20,7 +20,7 @@ public class SimpleStructureViewFactory implements PsiStructureViewFactory {
       @NotNull
       @Override
       public StructureViewModel createStructureViewModel(@Nullable Editor editor) {
-        return new SimpleStructureViewModel(psiFile);
+        return new SimpleStructureViewModel(editor, psiFile);
       }
     };
   }

code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleStructureViewModel.java

@@ -1,4 +1,4 @@
-// Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+// Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
 
 package org.intellij.sdk.language;
 
@@ -6,15 +6,17 @@ import com.intellij.ide.structureView.StructureViewModel;
 import com.intellij.ide.structureView.StructureViewModelBase;
 import com.intellij.ide.structureView.StructureViewTreeElement;
 import com.intellij.ide.util.treeView.smartTree.Sorter;
+import com.intellij.openapi.editor.Editor;
 import com.intellij.psi.PsiFile;
 import org.intellij.sdk.language.psi.SimpleProperty;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 public class SimpleStructureViewModel extends StructureViewModelBase implements
         StructureViewModel.ElementInfoProvider {
 
-  public SimpleStructureViewModel(PsiFile psiFile) {
-    super(psiFile, new SimpleStructureViewElement(psiFile));
+  public SimpleStructureViewModel(@Nullable Editor editor, PsiFile psiFile) {
+    super(psiFile, editor, new SimpleStructureViewElement(psiFile));
   }
 
   @NotNull
@@ -33,4 +35,8 @@ public class SimpleStructureViewModel extends StructureViewModelBase implements
     return element.getValue() instanceof SimpleProperty;
   }
 
+  @Override
+  protected Class<?> @NotNull [] getSuitableClasses() {
+    return new Class[]{SimpleProperty.class};
+  }
 }

code_samples/simple_language_plugin/src/main/resources/META-INF/plugin.xml

@@ -63,6 +63,7 @@
     <gotoSymbolContributor implementation="org.intellij.sdk.language.SimpleChooseByNameContributor"/>
     <lang.psiStructureViewFactory language="Simple"
                                   implementationClass="org.intellij.sdk.language.SimpleStructureViewFactory"/>
+    <navbar implementation="org.intellij.sdk.language.SimpleStructureAwareNavbar"/>
     <lang.formatter language="Simple" implementationClass="org.intellij.sdk.language.SimpleFormattingModelBuilder"/>
     <codeStyleSettingsProvider implementation="org.intellij.sdk.language.SimpleCodeStyleSettingsProvider"/>
     <langCodeStyleSettingsProvider implementation="org.intellij.sdk.language.SimpleLanguageCodeStyleSettingsProvider"/>

ijs.tree

@@ -245,6 +245,7 @@
       <toc-element id="code_formatting.md"/>
       <toc-element id="code_inspections_and_intentions.md"/>
       <toc-element id="structure_view.md"/>
+      <toc-element id="navbar.md"/>
       <toc-element toc-title="Code Hierarchy"/>
       <toc-element id="surround_with.md"/>
       <toc-element id="go_to_class_and_go_to_symbol.md"/>
@@ -268,6 +269,7 @@
       <toc-element id="folding_builder.md"/>
       <toc-element id="go_to_symbol_contributor.md"/>
       <toc-element id="structure_view_factory.md"/>
+      <toc-element id="structure_aware_navbar.md"/>
       <toc-element id="formatter.md"/>
       <toc-element id="code_style_settings.md"/>
       <toc-element id="commenter.md"/>

topics/intro/content_updates.md

@@ -14,6 +14,9 @@ See [GitHub Changelog](https://github.com/JetBrains/intellij-sdk-docs/commits/ma
 
 ### May-22
 
+Navigation Bar
+: Add [](navbar.md) section with an [accompanying tutorial](structure_aware_navbar.md) showing how to implement a custom navigation bar for a custom language.
+
 Rename Refactoring
 : Add [](rename_refactoring.md) paragraphs mentioning `RenameInputValidator` and `RenameInputValidatorEx`.
 

topics/reference_guide/custom_language_support/navbar.md

@@ -0,0 +1,47 @@
+[//]: # (title: Navigation Bar)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+
+The navigation bar implementation is used to customize and extend the
+[navigation bar](https://www.jetbrains.com/help/idea/guided-tour-around-the-user-interface.html#navigation-bar)
+structure.
+
+The starting point for the navigation bar extension is the
+[`NavBarModelExtension`](upsource:///platform/lang-impl/src/com/intellij/ide/navigationToolbar/NavBarModelExtension.java)
+interface, which is registered in the `com.intellij.navbar` extension point.
+
+To reuse the IntelliJ Platform implementation, you can extend one of two classes:
+
+- [`DefaultNavBarExtension`](upsource:///platform/lang-impl/src/com/intellij/ide/navigationToolbar/DefaultNavBarExtension.java)
+- [`StructureAwareNavBarModelExtension`](upsource:///platform/lang-impl/src/com/intellij/ide/navigationToolbar/StructureAwareNavBarModelExtension.kt)
+
+## Default Navigation Bar
+
+`DefaultNavBarExtension` is the basic implementation of the navigation bar for any files.
+Inherit from this class if you want to create a simple navigation bar where you can change the display of folders or files for your language.
+
+In this case, you probably only need to override the following two methods:
+
+- `getPresentableText()` – returns a string representation of the navigation bar part element passed to it.
+- `getIcon()` – returns the icon for the navigation bar part passed to it.
+
+## Structure Aware Navigation Bar
+
+`StructureAwareNavBarModelExtension` is an advanced implementation that provides the ability to display specific file elements (e.g., the name of classes, functions, etc.) in a bar e.g.,
+the name of the class at the current caret position.
+Inherit from it if you want to add navigation bar support to your language with support for specific file elements.
+
+> Don't forget to implement [](structure_view.md), this is necessary to build a file structure model based on which the navigation bar displays a specific element.
+{type="note"}
+
+In this case, you will also need to override the `getLanguage()` in addition to the two methods described earlier, this method returns the language instance for which this extension will work.
+
+The `adjustElement()` method allows you to modify the navigation bar element.
+It can be used, for example, when you want to show a class in the navigation bar when the caret is located in a comment that is attached to the class.
+
+You probably won't need to override other methods unless you want to write your own implementation of the entire `NavBarModelExtension` interface.
+
+Note that the `getSuitableClasses()` method on the structure view model class that implements `com.intellij.ide.structureView.TextEditorBasedStructureViewModel` (see [](structure_view.md))
+must return all the element types you want to display in the navigation bar.
+
+**Example**: [Custom Language Support Tutorial: Structure Aware Navigation Bar](structure_aware_navbar.md)

topics/tutorials/custom_language_support/code_style_settings.md

@@ -1,4 +1,4 @@
-[//]: # (title: 16. Code Style Settings)
+[//]: # (title: 17. Code Style Settings)
 
 <!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
 

topics/tutorials/custom_language_support/commenter.md

@@ -1,4 +1,4 @@
-[//]: # (title: 17. Commenter)
+[//]: # (title: 18. Commenter)
 
 <!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
 

topics/tutorials/custom_language_support/documentation_provider.md

@@ -1,4 +1,4 @@
-[//]: # (title: 19. Documentation)
+[//]: # (title: 20. Documentation)
 
 <!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
 

topics/tutorials/custom_language_support/formatter.md

@@ -1,4 +1,4 @@
-[//]: # (title: 15. Formatter)
+[//]: # (title: 16. Formatter)
 
 <!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
 

topics/tutorials/custom_language_support/quick_fix.md

@@ -1,4 +1,4 @@
-[//]: # (title: 18. Quick Fix)
+[//]: # (title: 19. Quick Fix)
 
 <!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
 

topics/tutorials/custom_language_support/structure_aware_navbar.md

@@ -0,0 +1,42 @@
+[//]: # (title: 15. Structure Aware Navigation Bar)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+
+<include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
+
+Structure aware navbar allows displaying specific file elements in the
+[navigation bar](https://www.jetbrains.com/help/idea/guided-tour-around-the-user-interface.html#navigation-bar),
+depending on the location of the caret in it.
+For example, in Java this is used to display the class and method in which the caret is currently located.
+
+**Reference**: [](navbar.md)
+
+## Define a SimpleStructureAwareNavbar
+
+The simple structure aware navbar implements
+[`StructureAwareNavBarModelExtension`](upsource:///platform/lang-impl/src/com/intellij/ide/navigationToolbar/StructureAwareNavBarModelExtension.kt).
+
+```java
+```
+{src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleStructureAwareNavbar.java"}
+
+## Register the SimpleStructureAwareNavbar
+
+The `SimpleStructureAwareNavbar` implementation is registered with the IntelliJ Platform in the plugin
+configuration file using the `com.intellij.navbar` extension point.
+
+```xml
+<extensions defaultExtensionNs="com.intellij">
+  <navbar implementation="org.intellij.sdk.language.SimpleStructureAwareNavbar"/>
+</extensions>
+```
+
+## Run the Project
+
+Run the project by using the Gradle
+[runIde task](https://plugins.jetbrains.com/docs/intellij/gradle-prerequisites.html#running-a-simple-gradle-based-intellij-platform-plugin).
+
+Open the <path>test.simple</path> file and position the caret on any property.
+The navigation bar displays the name and icon of this property.
+
+![Structure Aware Navbar](structure_aware_navbar.png)