laika-core/laika.directive.std/StandardDirectives

StandardDirectives

object StandardDirectives extends DirectiveRegistry

Provides the implementation for the standard directives included in Laika.

These include:

'''Navigation'''

  • navigationTree: Generates a navigation tree either automatically from specified root nodes of the input tree or by specifying entries manually (or a combination of both).
  • breadcrumb: Builds a navigation list from the root node of the input tree to the current document.
  • api: Convenience directive that allows to reference an api documentation entry (e.g. scaladoc, javadoc)
  • source: Convenience directive that allows to reference a hosted source (e.g. on GitHub)

'''Inclusions'''

  • include: Includes one template or markup document inside another, with the options to pass attributes that can be referenced in the included document.
  • embed: All the features of include, but also allows to pass a parsed directive body that can be referenced in the included document.

'''Applying Styles'''

  • style: Adds one or more style properties to the body element (markup block or span).

'''Markup Blocks'''

  • image: Alternative to native markup syntax for including images that supports additional attributes, like intrinsicWidth and intrinsicHeight to avoid layout shift, as well as alt and title.
  • callout: A decorated block element that stands out from the surrounding paragraphs; the default Helium theme renders the content with background color and icon.
  • select: Allows to create alternative versions of the same documentation, for example one with Scala code examples and one with Java.
  • fragment: Marks a block in a markup document as being separate from the main content, so that it can be placed independently in templates, e.g. in headers, footers or sidebars.
  • format: Process the body element only when the output format matches the format specified in the directive (e.g. pdf or html).

'''HTML Templates'''

  • linkCSS: Adds link elements to HTML/EPUB output for all or selected CSS files found in the document tree
  • linkJS: Adds link elements to HTML/EPUB output for all or selected JavaScript files found in the document tree
  • target: Translates a link target. External targets will be rendered verbatim, internal targets (absolute or relative paths) will be resolved from the perspective of a template to a path relative to the document the template had been applied to.
  • path: Deprecated, use the newer target directive instead which is a superset of its functionality
  • date: renders a date with a specified formatting pattern
  • attribute: renders an HTML attribute if the specified config value is defined

'''Conditionals and Loops'''

  • for: Accesses a value from the context and sets it as the reference context for its body elements, executing the body if the referenced value is non-empty and executing it multiple times when it is a collection.
  • if: Accesses a value from the context and processes the body element only when it is a value recognized as true.

'''PDF Output'''

  • pageBreak: Inserts a page break element into the tree (will only be rendered by page-based output, like XSL-FO or PDF.

'''Comments'''

  • todo: simple directive that accepts a string argument that will be ignored by renderers, overcoming the limitation that Markdown does not have a native comment syntax.

For extensive documentation see Standard Directives in the manual.

class Object
trait Matchable
class Any

Value members

Inherited methods

def baseConfig: Config

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.

Inherited from:
ExtensionBundle
def docTypeMatcher: PartialFunction[Path, DocumentType]

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.

Inherited from:
ExtensionBundle
def extendPathTranslator: PartialFunction[PathTranslatorExtensionContext, PathTranslator]

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.

Inherited from:
ExtensionBundle
override def forStrictMode: Option[ExtensionBundle]
Definition Classes
Inherited from:
DirectiveRegistry
def parsers: ParserBundle

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.

Inherited from:
ExtensionBundle
override def processExtension: PartialFunction[ExtensionBundle, ExtensionBundle]
Definition Classes
Inherited from:
DirectiveRegistry
def rawContentDisabled: Option[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.

Inherited from:
ExtensionBundle
def renderOverrides: Seq[RenderOverrides]

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.

Inherited from:
ExtensionBundle
def rewriteRules: RewritePhaseBuilder

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.

Inherited from:
ExtensionBundle
def slugBuilder: Option[String => String]

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
Inherited from:
ExtensionBundle
def withBase(base: ExtensionBundle): 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

Inherited from:
ExtensionBundle

Concrete fields

lazy val attr: Directive
lazy val blockDirectives: Seq[Directive]

The complete list of standard directives for block elements in markup documents.

The complete list of standard directives for block elements in markup documents.

lazy val blockFragment: Directive

Implementation of the fragment directive for block elements in markup documents.

Implementation of the fragment directive for block elements in markup documents.

lazy val blockStyle: Directive

Implementation of the style directive for block elements in markup documents.

Implementation of the style directive for block elements in markup documents.

lazy val callout: Directive

Implementation of the callout directive for block elements in markup documents. The body of such a directive will get two styles assigned: callout and the argument passed to the directive (e.g. @:callout(info)).

Implementation of the callout directive for block elements in markup documents. The body of such a directive will get two styles assigned: callout and the argument passed to the directive (e.g. @:callout(info)).

lazy val date: Directive
override val description: String
lazy val format: Directive

Implementation of the format directive for block elements in markup documents. The content of such a block will only be rendered for the corresponding output format (e.g. pdf or html).

Implementation of the format directive for block elements in markup documents. The content of such a block will only be rendered for the corresponding output format (e.g. pdf or html).

lazy val iconSpan: Directive

Implementation of the icon directive for span elements in markup documents.

Implementation of the icon directive for span elements in markup documents.

lazy val iconTemplate: Directive

Implementation of the icon directive for span elements in templates.

Implementation of the icon directive for span elements in templates.

lazy val linkDirectives: Seq[Directive]

The complete list of standard directives for links.

The complete list of standard directives for links.

override val origin: BundleOrigin
lazy val pageBreak: Directive

Implementation of the pageBreak directive.

Implementation of the pageBreak directive.

lazy val spanDirectives: Seq[Directive]

The complete list of standard directives for span elements in markup documents.

The complete list of standard directives for span elements in markup documents.

lazy val spanStyle: Directive

Implementation of the style directive for span elements in markup documents.

Implementation of the style directive for span elements in markup documents.

lazy val target: Directive
@nowarn("cat=deprecation")
lazy val templateDirectives: Seq[Directive]

The complete list of standard directives for templates.

The complete list of standard directives for templates.

lazy val templateFragment: Directive

Implementation of the fragment directive for templates.

Implementation of the fragment directive for templates.

val todoBlock: Directive

Implementation of the todo directive for block elements.

Implementation of the todo directive for block elements.

val todoSpan: Directive

Implementation of the todo directive for inline elements.

Implementation of the todo directive for inline elements.

Deprecated fields

@deprecated("use target directive instead", "0.19.0")
lazy val path: Directive
Deprecated