RstExtensionRegistry
Registry for custom reStructuredText extensions. Application code can define any number of instances mixing in this trait and then pass them to Parse, Render or Transform operations:
object MyExtensions extends RstExtensionRegistry {
val spanDirectives = Seq(...)
val blockDirectives = Seq(...)
val textRoles = Seq(...)
}
object OtherExtensions extends RstExtensionRegistry {
[...]
}
val transformer = Transformer
.from(ReStructuredText)
.to(HTML)
.using(MyDirectives, OtherDirectives)
.build
In contrast to the original Python implementation, this API has been redesigned to be a more idiomatic, concise and type-safe Scala DSL. See the documentation for the methods of this trait for concrete examples on how to implement an extension.
The following extension types are available:
-
Block Directives - an extension hook for adding new block level elements to reStructuredText markup. Use the
blockDirectives
method of this class to add directive implementations to the parser. Specification entry: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#directives -
Substitution Definitions - an extension hook for adding new span level elements to reStructuredText markup that can be used by substitution references (like
|subst|
). Use thespanDirectives
method of this class to add directive implementations to the parser that can be used as substitution definitions. Specification entry: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions -
Interpreted Text Roles - an extension hook for adding new dynamic span level elements to reStructuredText markup. In contrast to substitution definitions the implementation of a text role uses the text from the occurrences in the markup referring to the role as input. Use the
textRoles
method of this class to add custom text role implementations to the parser that can be referred to by interpreted text. Specification entry: http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles
Attributes
- Graph
-
- Supertypes
- Known subtypes
-
object RawContentExtensions.typeobject StandardExtensions.type
Members list
Value members
Abstract methods
Registers the specified block directives.
Registers the specified block directives.
Example:
case class Note (title: String, content: Seq[Block]) extends Block with BlockContainer[Note]
object MyDirectives extends RstExtensionRegistry {
val blockDirectives = Seq(
BlockDirective("note") {
(argument() ~ blockContent).map { case title ~ content => Note(title, content) }
}
)
val spanDirectives = Seq()
val textRoles = Seq()
}
val transformer = Transformer
.from(ReStructuredText)
.to(HTML)
.using(MyDirectives)
.build
For more details on implementing directives see laika.rst.ext.Directives.
Attributes
Registers the specified span directives. These span directives can then be referred to by substitution references.
Registers the specified span directives. These span directives can then be referred to by substitution references.
Example:
object MyDirectives extends RstExtensionRegistry {
val spanDirectives = Seq(
SpanDirective("replace") {
spanContent map SpanSequence
}
)
val blockDirectives = Seq()
val textRoles = Seq()
}
val transformer = Transformer
.from(ReStructuredText)
.to(HTML)
.using(MyDirectives)
.build
For more details on implementing directives see laika.rst.ext.Directives.
Attributes
Registers the specified text roles. These text roles may then be used in interpreted text spans.
Registers the specified text roles. These text roles may then be used in interpreted text spans.
Example:
val textRole = TextRole("link", "http://www.company.com/main/")(field("base-url")) {
(base, text) => Link(List(Text(text)), base + text)
}
object MyDirectives extends RstExtensionRegistry {
val textRoles = Seq(textRole)
val spanDirectives = Seq()
val blockDirectives = Seq()
}
val transformer = Transformer
.from(ReStructuredText)
.to(HTML)
.using(MyDirectives)
.build
For more details on implementing directives see laika.rst.ext.TextRoles.
Attributes
Concrete methods
Overrides the name of the default text role to apply when interpreted text is used in markup without an explicit role name.
Overrides the name of the default text role to apply when interpreted text is used in markup without an explicit role name.
Attributes
Internal API usually only called by other extension bundles.
Internal API usually only called by other extension bundles.
In some cases a bundle might be an extension of another bundle and needs the opportunity to process and modify that bundle without requiring a direct reference to it. An example is a registry for directives which needs to pass all its registered directives to the bundle which deals with finally creating all the directive parsers.
The partial function should match only on the types of bundles it intends to process and is then allowed to return a new, modified instance of that bundle.
Attributes
- Definition Classes
Inherited methods
Base configuration that serves as a fallback for configuration files in the source directories and/or config headers in markup and template documents.
Base configuration that serves as a fallback for configuration files in the source directories and/or config headers in markup and template documents.
Attributes
- Inherited from:
- ExtensionBundle
Specifies the function to use for determining the document type of the input based on its path.
Specifies the function to use for determining the document type of the input based on its path.
Any path for which this function is not defined will be processed by the remaining defined bundles. The documents for paths for which none of the extensions provides a DocumentType
will be treated as static files to be copied over to the target directory in transformations by default.
Attributes
- Inherited from:
- ExtensionBundle
Extends the built-in path translator with additional functionality.
Extends the built-in path translator with additional functionality.
The internal path translator deals with aspects like applying the suffix for the output format or modifying the path for versioned documents and more.
The PathTranslatorExtensionContext
provides access to this internal path translator, to the output format it is going to be used for and the complete user configuration.
In most cases, extensions can simply be created by using either PathTranslator.preTranslate
or PathTranslator.postTranslate
to apply additional translation steps either before or after applying the internal translator.
Alternatively a completely custom implementation of the PathTranslator
trait can be provided, but this will usually not be necessary.
PathTranslator
implementations usually do not deal with the fragment part of the path. Use the slugBuilder
extension point for this purpose.
Attributes
- Inherited from:
- ExtensionBundle
Provides a version of this bundle that can be used in strict mode or None
if the entire bundle should be removed in strict mode.
Provides a version of this bundle that can be used in strict mode or None
if the entire bundle should be removed in strict mode.
When strict mode does not affect a bundle it can return Some(this)
.
Any bundle to be used in strict mode should be free from any parser extensions that adds features to markup syntax beyond their respective specifications.
Attributes
- Inherited from:
- ExtensionBundle
Indicates whether the bundle is a built-in default provided by the library, a collection of extensions installed by a markup format or user-defined.
Indicates whether the bundle is a built-in default provided by the library, a collection of extensions installed by a markup format or user-defined.
This is relevant for determining the precedence of installed bundles when merging them, as user-supplied functionality always overrides library defaults.
Attributes
- Inherited from:
- ExtensionBundle
Specifies extensions and/or replacements for parsers that deal with text markup, templates, CSS or configuration headers.
Specifies extensions and/or replacements for parsers that deal with text markup, templates, CSS or configuration headers.
Attributes
- Inherited from:
- ExtensionBundle
Provides a version of this bundle that can be used in the default run mode where raw content in markup documents (such as embedded HTML) is disabled.
Provides a version of this bundle that can be used in the default run mode where raw content in markup documents (such as embedded HTML) is disabled.
When a bundle does not add parsers for raw content it can return Some(this)
.
Any bundle to be used in the default run mode should be free from any parser extensions that allow raw content in markup. When the user switches the acceptRawContent
flag to true
then this method will not be invoked and the initial instance of the bundle is used.
Attributes
- Inherited from:
- ExtensionBundle
The overrides for renderers defined by this bundle.
The overrides for renderers defined by this bundle.
An override is always specific to a particular output format like HTML or PDF. A bundle can contain multiple overrides for the same output format which will be merged before use.
Attributes
- Inherited from:
- ExtensionBundle
Specifies rewrite rules to be applied to the document tree model between the parse and render operations.
Specifies rewrite rules to be applied to the document tree model between the parse and render operations.
The specified functions will be invoked for each document, allowing to capture information from the entire document tree before returning the actual rule, which is a partial function from Element
to Option[Element]
that allows to remove or replace elements from the tree.
Attributes
- Inherited from:
- ExtensionBundle
Function that receives the text of a headline, the name of a document or directory or a manually assigned identifier, and builds a slug from it that becomes part of the final URL or identifier (depending on output format).
Function that receives the text of a headline, the name of a document or directory or a manually assigned identifier, and builds a slug from it that becomes part of the final URL or identifier (depending on output format).
The result of the function must be:
- a valid identifier in HTML and XML
- a valid path segment in a URL
- a valid file name
Attributes
- Inherited from:
- ExtensionBundle
Returns a new extension bundle by merging the content of this bundle with the content of the base bundle.
Returns a new extension bundle by merging the content of this bundle with the content of the base bundle.
The other bundle is treated as the base of this bundle, which means that:
-
in case of optional features a feature defined in this bundle will overwrite a feature defined in the base
-
in case of features applied in sequence, the features in this bundle will be applied before the features in the base bundle
-
in case of feature collections, the features of this bundle will be merged with those of the base bundle
Attributes
- Inherited from:
- ExtensionBundle
Concrete fields
Short string describing the extension for tooling and logging.
Short string describing the extension for tooling and logging.