New API for installing ExtensionBundles

[jenshalm]

Bundles can define any of the available customizations:

• Directives
• Markup parser extensions
• Rewrite rules
• Custom renderers
• Document type matchers
• Alternative parsers for stylesheets, templates or configuration headers
• Default templates per output format.

These options were previously scattered throughout the API.

See the scaladoc for the new ExtensionBundle API for details:
https://github.com/planet42/Laika/blob/master/core/src/main/scala/laika/bundle/ExtensionBundle.scala

Migrating from 0.8 to 0.9

If you only used the plain Transform API without any customization hooks, then your code should still work.

If you did customize Laika, this list shows you how to adapt your code for the new version:

Rewrite Rules or Custom Renderers

For the two most common options, the old API has been kept:

Transform.from(Markdown).to(HTML)
    .rendering(...) // pass custom render function - existing API
    .usingRule(...) // pass rewrite rule - existing API

Registering Directives

These were previously passed to the text markup instance:

Transform.from(Markdown
    .withBlockDirectives(...)
    .withSpanDirectives(...)
).to(HTML)

They can now be defined as part of a DirectiveRegistry (a subtype of ExtensionBundle)

object MyDirectives extends DirectiveRegistry {
    val spanDirectives = Seq(...)
    val blockDirectives = Seq(...)
    val templateDirectives = Seq(...)
}

Transform.from(Markdown).to(HTML).using(MyDirectives)

Other Extension Hooks

Some more low-level options were available via the Transform API:

Transform.from(Markdown).to(HTML)
    .withConfigFile(...)
    .withTemplateParser(...)
    .withStyleSheetParser(...)
    .withDocTypeMatcher(...)

These have all moved to the new ExtensionBundle API (plus a lot of new options):

object MySetup extends ExtensionBundle {
    override val baseConfig = ...
    override val docTypeMatcher = ...
    override val parsers = ParserBundle(
        styleSheetParser = ...
        templateParser = ...
    }
}

Transform.from(Markdown).to(HTML).using(MySetup)

Runtime Flags

Finally some flags which were available on the instances for the input and output formats also moved up to the top Transform API to avoid repeating the options on each format:

Transform.from(Markdown
    .strict
    .withRawContent
).to(HTML
    .unformatted
    .withMessageLevel(...)
)

has become

Transform.from(Markdown).to(HTML)
    .strict
    .withRawContent
    .unformatted
    .withMessageLevel(...)

Task List:

• Define new API for ExtensionBundles
• Use the new API with Laika's Parse, Render and Transform APIs
• Process base config through ExtensionBundle
• Process docTypeMatcher through ExtensionBundle
• Process stylesheet parser through ExtensionBundle
• Process rewrite rules through ExtensionBundle
• Process default template and styles rules through ExtensionBundle
• Process custom renderers through ExtensionBundle
• Add Builder API for creating parser definitions
• Implement Markdown's VerbatimHTML as an extension
• Implement reStructuredText's ExtendedHTML as an extension
• Implement Laika's Directives as an extension
• Remove some of the old extension hooks, e.g. for TemplateParser, StylesheetParser
• Allow to merge static files from a theme to the output tree
• Centralize management of parsers for configuration headers
• Refactor Markdown's core parsers to use the new Builder API
• Refactor reStructuredText's core parsers to use the new Builder API
• Implement reStructuredText's Directives as an extension
• Simplify or remove old RootParsers
• Add documentation for creating ExtensionBundles to the manual