anchor.diff:  Once you add a new token you will need to add it to `AsciiDocColorSettingsPage` so users can customize the colors of their theme.
   This class references also `SampleDocument.adoc` and `AsciiDocBundle.properties`, therefore you'll probably need to change these two files as well.
   
  +[[parsing]]
   === Parsing
   
  -TODO: parsing, refactoring, folding, linking, autocompletion, finding references
  +==== Why
  +
  +Parsing gives a hierarchical structure and meaning to the tokens created in the parsing phase.
  +
  +It can define `PsiElements` inside the tree to allow interactions with the user like renaming of elements and autocompletion.
  +The structure is the foundation of the structure outline view and the folding capabilities.
  +
  +==== How
  +
  +The `AsciiDocParserDefinition` separates white space and comments from functional tokens.
  +It also serves as a factory for all `PsiElement`s like `AsciiDocSection` for sections and `AsciiDocBlock` for blocks.
  +
  +`AsciiDocParserImpl` encodes the logic how to group the tokens to a tree.
  +To do this, it has several strategies. This outline summaries the most distinct strategies:
  +
  +References::
  ++
  +--
  +Once it sees the start token `REFSTART` (usually two opening pointy brackets, like `<<`), it sets a marker.
  +Then it reads all tokens that are valid inside a reference.
  +Once the are no more valid tokens for a reference, it marks this block as a `AsciiDocElementTypes.REF`.
  +--
  +
  +Blocks::
  ++
  +--
  +A block starts for example with a LISTING_BLOCK_DELIMITER (usually four dashes in a line, like `----`).
  +Then the block continues up to the point where the same marker occurs again.
  +
  +But the block can be preceded for example by a title (it starts with a dot, following by the title itself, like `.Title`).
  +This title is part of the block.
  +To support this `TITLE` and several other elements call `markPreBlock()` to memorize the first token that is part of a following block. It is stored in a variable `myPreBlockMarker`.
  +
  +When parsing of the block starts and the `myPreBlockMarker` is set, it uses this marker.
  +If the marker is not set, is creates a new marker at the start of the block delimiter.
  +When the block doesn't start on one of the following lines, `dropPreBlock()` drops the marker.
  +--
  +
  +Sections::
  ++
  +--
  +Sections build on top of blocks.
  +They can have pre-block elements as well.
  +
  +In addition to standard blocks they build a hierarchy:
  +Each section has a level determined by the number of equal signs at the start (or, if it is an old style heading by the character underlining the heading).
  +
  +Whenever a section with the same level like the one before starts, the previous section needs to be closed.
  +Whenever a section of a higher order (let's say two equal signs at the start, like `==`) starts, all open sections with a lower order must be closed (in this case with three or more equal signs at the start).
  +This logic is encapsulated in `closeSections()`.
  +It is also called at the end of the document to close all sections at the end of the document.
  +--
  +
  +==== Debugging
  +
  +To analyze the structure interactively install the PsiViewer plugin. You can install it in the IDE you develop in, but most likely you'll also install it in the sandbox IDE you start from the IDE you develop in.
  +
  +Right-click on the AsciiDoc editor and choose "PsiViewer | View PSI for enire file" to browse the tree.
  +There is also a keyboard shortcut for this.
  +
  +==== Testing
  +
  +The are unit tests for the parser.
  +You can run them from your IDE.
  +The tests come in two variants:
  +
  +AsciiDocPsiTest::
  ++
  +--
  +This test parses a minimal snippet of AsciiDoc, creates the PSI tree, and the lets you apply assertions like in normal unit tests.
  +
  +Use this to write specific tests.
  +Consider a given/when/then structure to write tests that are comprehensible for other developers.
  +As you test only specific elements in the created tree, your tests will not break when parts of the tree change that are irrelevant to the tested functionality.
  +--
  +
  +AsciiDocParserTest::
  ++
  +--
  +This test acts on example files in `/testData/parser` together with a golden master file.
  +
  +To write a new test, create a new method in the class (like `testSectionsWithPreBlock()`).
  +Then put a matching AsciiDoc file to the example file directory (like `sectionsWithPreBlock.adoc`).
  +When you run the test for the first time, it will create a golden master file (like `sectionsWithPreBlock.txt`).
  +Check the contents of the golden master file if the result matches your expectations.
  +
  +On consecutive runs the test will compare the parser result with the contents of the golden master file.
  +If the content matches, the test will pass.
  +If there are differences, the test will fail.
  +If you expected these differences for example because you changed the parser or lexer, copy the result shown in your IDE to the golden master file.
  +
  +NOTE: Please check in the golden master file to the Git repository!
  +--
  +
  +So why are there two types of tests? Each has its own strengths!
  +
  +The golden master approach will trigger even on minor changes to the output and gives you the chance to approve or reject the changes.
  +The downside is that these tests will fail when there are unrelated changes because they check too many things.
  +For a golden master test it is also hard to see the parts of the golden master that are relevant for the expected behavior and must not change.
  +
  +The test with single assertions will be most specific to the described functionality, and will leave out parts that are unrelated to the test.
  +Therefore, it will not break for unrelated changes.
  +Meaningful assertions allow fellow developers to understand the expected functionality.
  +Writing such a test is often slower as it requires more code and skill, but it will pay off as it will break less often due to unrelated changes.
  +
  +=== Interacting with PsiElements
  +
  +TODO: refactoring, folding, linking, autocompletion, finding references
   
   == Preview rendering
   
  
positive.code: ----
    // regular
    {REFSTART} / [^>\n]+ {REFEND} { yybegin(REF); return AsciiDocTokenTypes.REFSTART; }
    // autocomplete
    {REFSTART} / [^>\n ]* {AUTOCOMPLETE} { yybegin(REFAUTO); return AsciiDocTokenTypes.REFSTART; }
  ----
  --
  
negative.code: To work around this issue blocks are parsed first in state `MULTILINE`, then in state `SINGLELINE`, and finally `INSIDE_LINE` to implement a hierarchy and some ordering of matches.
  --
  
  auto-completion::
  +
  --
  Expressions described above match expressions once they have their closing syntax completed and it is essential for the correct highlighting.
  To support autocomplete the matching must handle an expression where only the left part of the expression exists.
  
  A special case is in the parser to support autocompletion, as IntelliJ inserts a special string when parsing the content for autocompletion (named `auto-complete` in our parser).
  
  In the case for references (`\<<ref>>`) there are two rules, one for regular parsing and highlighting, one without:
  
  