Skip to content

Commit

Permalink
add docs for new laikaRenderers setting
Browse files Browse the repository at this point in the history
  • Loading branch information
jenshalm committed Mar 6, 2024
1 parent 6a3081b commit 29654fd
Show file tree
Hide file tree
Showing 2 changed files with 34 additions and 4 deletions.
30 changes: 30 additions & 0 deletions docs/src/02-running-laika/01-sbt-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -418,6 +418,36 @@ By default, the port is 4242, the poll interval is 3 seconds.
With the `verbose` options the console will log all pages served.


### Installing Additional Renderers

The `laikaRenderers` setting holds the configurations for all of Laika's built-in renderers
and enables users to install their own or 3rd-party renderers.

An example for installing a custom `indexFormat` renderer:

```scala mdoc:compile-only
import laika.api.format.*
import laika.sbt.BinaryRendererConfig

def indexFormat: TwoPhaseRenderFormat[Formatter, BinaryPostProcessor.Builder] = ???

laikaRenderers += BinaryRendererConfig(
alias = "index",
format = indexFormat,
targetDirectory = (laikaSite / target).value / "search",
artifactBaseName = "searchIndex",
fileSuffix = "dat",
includeInSite = true,
supportsSeparations = false
)
```

With the configuration above, the search index can be generated by calling `laikaGenerate index`
(or together with other formats in one transformation - e.g. `laikaGenerate html index`).

When the includeInSite property is true, the index will also be generated when calling `laikaSite`.


### Inspecting Laika's Configuration

Run `show laikaDescribe` to get a formatted summary of the active configuration,
Expand Down
8 changes: 4 additions & 4 deletions sbt/src/main/scala/laika/sbt/LaikaPlugin.scala
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,6 @@ import sbt.*
*
* - `Laika / excludeFilter`: files in the source directories to be excluded (default `HiddenFileFilter`)
*
* - `laikaArtifactNameBuilder`: function that builds the name for artifacts (EPUB, PDF, ZIP) based on the provided
* context info
*
* - `laikaExtensions`: the main extension hook that allows to add one or more `ExtensionBundle` instances for adding
* directives, parser extensions, rewrite rules or custom renderers. See the API of `laika.api.bundle.ExtensionBundle`.
*
Expand All @@ -58,8 +55,11 @@ import sbt.*
* - `laikaTheme`: configuration for the theme to use for all transformations, if not specified the default
* `Helium` theme with all default colors and fonts will be used.
*
* - `laikaRenderers`: contains the configurations for all of Laika's built-in renderers and enables users
* to install their own or 3rd-party renderers.
*
* - `laikaIncludeAPI`, `laikaIncludeEPUB` and `laikaIncludePDF`:
* specifies whether to include scaladoc and/or PDF output in the generated site.
* specifies whether to include scaladoc and/or PDF/EPUB output in the generated site.
*
* - `laikaDescribe`: inspects your setup and prints information about your inputs, outputs and installed extensions.
*
Expand Down

0 comments on commit 29654fd

Please sign in to comment.