introduce a more fine-grained rewrite phase model

[jenshalm]

This refactoring addresses a long-standing issue where the internal AST rewriting that happens between parsing and rendering introduced chicken-and-egg scenarios that led to unexpected results for users in some edge cases. In the past there were always options to introduce workarounds when a related issue surfaced (like in #263). However, a new issue was reported recently (#289) where applying duct tape was no longer possible, and it was time for a bigger refactoring.

The key ideas that should solve the vast majority of related issues for users without the need for them to do anything or even understand the underlying topics were the following two:

• Introduce a third rewrite phase in addition to the existing two. The phase model now consists of:

  • RewritePhase.Build the first phase run after parsing and the only phase where new link targets can be introduced safely.
  • RewritePhase.Resolve the second phase which is mostly reserved for internal use (e.g. running the link resolver).
  • RewritePhase.Render(OutputContext) the final phase run before rendering, which is specific to the selected output format and therefore parameterized. Rules and directives run in this phase get to see an "almost complete" AST. It is therefore the best place for extensions that produce navigation artefacts for example.

• Adapt the default phases that user-defined rules and directives are run in. The default depends on how a rule or directive is constructed and primarily distinguishes between rules and directives that have access to a DocumentCursor and those that don't (the distinction is easy to make by the APIs that users call to create them).

  • If a rule or directive does not have access to a DocumentCursor it is impossible that it is used for tasks like generation of navigation structures and therefore it is run in the first phase by default. This means it is free to introduce new structure elements (even headers) itself.
  • If the rule or directive does have access to a DocumentCursor it is treated differently and run in the last phase by default. This way the extension gets to see an "almost complete" version of the AST which is the best phase for tasks like generating navigation. Issues like Headers created in custom directives disappear #289 existed as previously all rules and directives were run in this phase even when there clearly was no need to.

Fixes #289