custom language tutorial: use <microformat> for Reference links

topics/tutorials/custom_language_support/annotator.md

@@ -2,13 +2,17 @@
 
 <!-- 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. -->
 
+<microformat>
+
+**Reference**: [](syntax_highlighting_and_error_highlighting.md#annotator)
+
+</microformat>
+
 <include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
 
 An `Annotator` helps highlight and annotate any code based on specific rules.
 This section adds annotation functionality to support the Simple Language in the context of Java code.
 
-**Reference**: [Annotator](syntax_highlighting_and_error_highlighting.md#annotator)
-
 ## Required Project Configuration Changes
 
 Classes defined in this step of the tutorial depend on `com.intellij.psi.PsiLiteralExpression` (the PSI representation for String literals in Java code) at runtime.

topics/tutorials/custom_language_support/code_style_settings.md

@@ -2,14 +2,18 @@
 
 <!-- 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. -->
 
+<microformat>
+
+**Reference**: [](code_formatting.md#code-style-settings)
+
+</microformat>
+
 <include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
 
 Code style settings enable defining formatting options.
 A code style settings provider creates an instance of the settings and also creates an options page in settings/preferences.
 This example creates a settings/preferences page that uses the default language code style settings, customized by a language code style settings provider.
 
-**Reference**: [Code Style Settings](code_formatting.md#code-style-settings)
-
 ## Define Code Style Settings
 
 Define a code style settings for Simple Language by subclassing [`CustomCodeStyleSettings`](%gh-ic%/platform/code-style-api/src/com/intellij/psi/codeStyle/CustomCodeStyleSettings.java).

topics/tutorials/custom_language_support/completion_contributor.md

@@ -2,12 +2,16 @@
 
 <!-- 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. -->
 
+<microformat>
+
+**Reference**: [](code_completion.md)
+
+</microformat>
+
 <include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
 
 Custom languages provide code completion using one of two approaches: Contributor and Reference-based (see [](reference_contributor.md)) completion.
 
-**Reference**: [](code_completion.md)
-
 ## Define a Completion Contributor
 
 For this tutorial, the `simple_language_plugin` provides custom completion for values in Simple Language property files.

topics/tutorials/custom_language_support/documentation_provider.md

@@ -2,6 +2,12 @@
 
 <!-- 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. -->
 
+<microformat>
+
+**Reference**: [](documentation.md)
+
+</microformat>
+
 <include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
 
 A [`DocumentationProvider`](%gh-ic%/platform/analysis-api/src/com/intellij/lang/documentation/DocumentationProvider.java)
@@ -9,8 +15,6 @@ helps users by showing documentation for symbols like method calls inside the ed
 For the custom language tutorial, we're implementing a version of this extension point (EP) for the Simple Language that shows the key/value,
 the file where it is defined, and any related documentation comment.
 
-**Reference:** [](documentation.md)
-
 ## Implement DocumentationProvider and Register the EP
 
 In the first step, we create an empty class that extends

topics/tutorials/custom_language_support/find_usages_provider.md

@@ -2,13 +2,17 @@
 
 <!-- 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. -->
 
+<microformat>
+
+**Reference**: [](find_usages.md)
+
+</microformat>
+
 <include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
 
 A `FindUsagesProvider` uses a word scanner to build an index of words in every file.
 A scanner breaks the text into words and defines the context for each word.
 
-**Reference**: [](find_usages.md)
-
 ## Define a Find Usages Provider
 
 The `SimpleFindUsagesProvider` implements [`FindUsagesProvider`](%gh-ic%/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java).

topics/tutorials/custom_language_support/formatter.md

@@ -2,14 +2,18 @@
 
 <!-- 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. -->
 
+<microformat>
+
+**Reference**: [](code_formatting.md)
+
+</microformat>
+
 <include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
 
 The IntelliJ Platform includes a powerful framework for implementing formatting for custom languages.
 A formatter enables reformatting code automatically based on code style settings.
 The formatter controls spaces, indents, wrap, and alignment.
 
-**Reference**: [](code_formatting.md)
-
 ## Define a Block
 
 The formatting model represents the formatting structure of a file as a tree of [`Block`](%gh-ic%/platform/code-style-api/src/com/intellij/formatting/Block.java) objects, with associated indent, wrap, alignment and spacing settings.

topics/tutorials/custom_language_support/go_to_symbol_contributor.md

@@ -2,12 +2,15 @@
 
 <!-- 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. -->
 
+<microformat>
+
+**Reference**: [](go_to_class_and_go_to_symbol.md)
+
+</microformat>
 <include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
 
 A _Go to Symbol Contributor_ helps the user to navigate to any PSI element by its name.
 
-**Reference**: [](go_to_class_and_go_to_symbol.md)
-
 ## Define a Helper Method for Generated PSI Elements
 
 To specify how a PSI element looks like in the <menupath>Navigate | Symbol</menupath> popup window, <control>Structure</control> tool window, or other components, it should implement `getPresentation()`.

topics/tutorials/custom_language_support/grammar_and_parser.md

@@ -2,15 +2,17 @@
 
 <!-- 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. -->
 
+<microformat>
+
+**Reference**: [](implementing_lexer.md), [](implementing_parser_and_psi.md)
+
+</microformat>
+
 <include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
 
 In order for the IntelliJ Platform to parse a Simple Language file, tokens and elements must be defined based on [`IElementType`](%gh-ic%/platform/core-api/src/com/intellij/psi/tree/IElementType.java).
 The Simple Language grammar must also be defined to generate a parser.
 
-**Reference**:
-- [](implementing_lexer.md)
-- [](implementing_parser_and_psi.md)
-
 ## Define a Token Type
 
 Create `SimpleTokenType` in the `org.intellij.sdk.language.psi` package (see the `simple_language_plugin` code sample) by subclassing `IElementType`.

topics/tutorials/custom_language_support/language_and_filetype.md

@@ -2,6 +2,12 @@
 
 <!-- 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. -->
 
+<microformat>
+
+**Reference**: [](registering_file_type.md)
+
+</microformat>
+
 <chunk id="custom_language_tutorial_header">
 
 > This page is part of multi step [](custom_language_support_tutorial.md).
@@ -14,8 +20,6 @@ The IntelliJ Platform determines file type by examining the name of a file.
 Each language has [Language](%gh-ic%/platform/core-api/src/com/intellij/lang/Language.java) and [LanguageFileType](%gh-ic%/platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java) objects defining the language.
 Register the `LanguageFileType` with the IntelliJ Platform in the plugin configuration file.
 
-**Reference**: [](registering_file_type.md)
-
 ## Define the Language
 
 The language implemented in this tutorial is named "Simple" - note the case of the name.

topics/tutorials/custom_language_support/lexer_and_parser_definition.md

@@ -2,13 +2,17 @@
 
 <!-- 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. -->
 
+<microformat>
+
+**Reference**: [](implementing_lexer.md)
+
+</microformat>
+
 <include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
 
 The lexical analyzer defines how the contents of a file are broken into tokens, which is the basis for supporting custom language features.
 The easiest way to create a lexer is to use [JFlex](https://jflex.de/).
 
-**Reference**: [](implementing_lexer.md)
-
 ## Define a Lexer
 
 Define a <path>Simple.flex</path> file with rules for the Simple Language lexer in package `org.intellij.sdk.language`.

topics/tutorials/custom_language_support/quick_fix.md

@@ -4,11 +4,15 @@
 
 <include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
 
-A quick fix for a custom language supports the IntelliJ Platform-based IDE feature [Intention Actions](https://www.jetbrains.com/help/idea/intention-actions.html#apply-intention-actions).
+<microformat>
-For the Simple Language, this tutorial adds a quick fix that helps to define an unresolved property from its usage.
 
 **Reference**: [](code_inspections_and_intentions.md)
 
+</microformat>
+
+A quick fix for a custom language supports the IntelliJ Platform-based IDE feature [Intention Actions](https://www.jetbrains.com/help/idea/intention-actions.html#apply-intention-actions).
+For the Simple Language, this tutorial adds a quick fix that helps to define an unresolved property from its usage.
+
 ## Update the Element Factory
 The `SimpleElementFactory` is updated to include two new methods to support the user choice of creating a new property for the Simple Language quick fix.
 The new `createCRLF()` method supports adding a newline to the end of the [`test.simple`](lexer_and_parser_definition.md#run-the-project) file before adding a new property.

topics/tutorials/custom_language_support/reference_contributor.md

@@ -2,6 +2,12 @@
 
 <!-- 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. -->
 
+<microformat>
+
+**Reference**: [](references_and_resolve.md), [](psi_references.md)
+
+</microformat>
+
 <include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
 
 The references functionality is one of the most important parts in the implementation of custom language support.
@@ -11,8 +17,6 @@ Resolving references means the ability to go from the usage of an element to its
 >
 {type="note"}
 
-**Reference**: [](references_and_resolve.md), [](psi_references.md)
-
 ## Define a Named Element Class
 
 The classes below show how the Simple Language fulfills the need to implement `PsiNamedElement`.

topics/tutorials/custom_language_support/structure_aware_navbar.md

@@ -2,6 +2,12 @@
 
 <!-- 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. -->
 
+<microformat>
+
+**Reference**: [](navbar.md)
+
+</microformat>
+
 <include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
 
 Structure aware navbar allows displaying specific file elements in the
@@ -9,8 +15,6 @@ Structure aware navbar allows displaying specific file elements in the
 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

topics/tutorials/custom_language_support/structure_view_factory.md

@@ -2,13 +2,17 @@
 
 <!-- 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. -->
 
+<microformat>
+
+**Reference**: [](structure_view.md)
+
+</microformat>
+
 <include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
 
 The structure view can be customized for a specific file type.
 Creating a structure view factory allows showing the structure of any file in a _Structure_ Tool Window for easy navigation between items in the current editor.
 
-**Reference**: [](structure_view.md)
-
 ## Define a Structure View Factory
 
 The structure view factory implements [`PsiStructureViewFactory`](%gh-ic%/platform/editor-ui-api/src/com/intellij/lang/PsiStructureViewFactory.java).

topics/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md

@@ -2,14 +2,18 @@
 
 <!-- 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. -->
 
+<microformat>
+
+**Reference**: [](syntax_highlighting_and_error_highlighting.md)
+
+</microformat>
+
 <include src="language_and_filetype.md" include-id="custom_language_tutorial_header"></include>
 
 The first level of syntax highlighting is based on the lexer output, and is provided by `SyntaxHighlighter`.
 A plugin can also define color settings based on `ColorSettingPage` so the user can configure highlight colors.
 The `SimpleSyntaxHighlighter`, `SimpleSyntaxHighlighterFactory`, and `SimpleColorSettingsPage` discussed on this page are demonstrated in the `simple_language_plugin` code sample.
 
-**Reference**: [](syntax_highlighting_and_error_highlighting.md)
-
 ## Define a Syntax Highlighter
 
 The Simple Language syntax highlighter class extends [`SyntaxHighlighterBase`](%gh-ic%/platform/editor-ui-api/src/com/intellij/openapi/fileTypes/SyntaxHighlighterBase.java).