` tags, converting special characters to HTML entities.
```markdown
This is a normal paragraph:
This is a code block.
```
```html
This is a normal paragraph:
This is a code block.
```
--------------------------------
### Minimal HTML Template Example in Laika
Source: https://github.com/typelevel/laika/blob/main/docs/src/04-customizing-laika/03-creating-templates.md
A basic example of an HTML template using Laika's syntax. It includes a title, navigation tree directive, and content insertion. This showcases substitution variables for dynamic content and directives for structured elements.
```laika-html
${cursor.currentDocument.title}
@:navigationTree { entries = [{ target = "/" }] }
${cursor.currentDocument.content}
```
--------------------------------
### AppleScript Code Block Example in Markdown
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Syntax.html
Illustrates an AppleScript code block within a Markdown document. The indentation is preserved, and the code is presented literally within `` tags, showing how to include programming language examples.
```markdown
Here is an example of AppleScript:
tell application "Foo"
beep
end tell
```
```html
Here is an example of AppleScript:
tell application "Foo"
beep
end tell
```
--------------------------------
### Ordered Lists in Markdown
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Syntax.html
Shows how to create ordered lists using numbers followed by periods. The actual numbers used do not affect the HTML output, though starting with '1' is recommended.
```markdown
1. Bird
2. McHale
3. Parish
```
```markdown
1. Bird
1. McHale
1. Parish
```
```markdown
3. Bird
1. McHale
8. Parish
```
--------------------------------
### Code Block HTML Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Inline HTML (Simple).md
An HTML block explicitly formatted as a code block. This preserves the literal representation of the HTML.
```html
foo
```
--------------------------------
### Option List Formatting Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Demonstrates the syntax for defining option lists, which document command-line options and their descriptions. This includes single-line and multi-line descriptions, as well as options with arguments.
```text
-a Output all.
-b Output both (this description is
quite long).
-c arg Output just arg.
--long Output all day long.
-p This option has two paragraphs in the description.
This is the first.
This is the second. Blank lines may be omitted between
```
--------------------------------
### Markdown Lists
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Basics.md
Shows the syntax for creating unordered (bulleted) lists using asterisks, pluses, or hyphens, and ordered (numbered) lists. Includes examples of multi-paragraph list items and their HTML output.
```Markdown
* Candy.
* Gum.
* Booze.
+ Candy.
+ Gum.
+ Booze.
- Candy.
- Gum.
- Booze.
1. Red
2. Green
3. Blue
* A list item.
With multiple paragraphs.
* Another item in the list.
```
```HTML
- Candy.
- Gum.
- Booze.
- Red
- Green
- Blue
A list item.
With multiple paragraphs.
Another item in the list.
```
--------------------------------
### HOCON Named Attributes Example
Source: https://github.com/typelevel/laika/blob/main/docs/src/05-extending-laika/03-implementing-directives.md
Demonstrates the syntax for defining named attributes in HOCON format within a Laika markup example. These attributes are enclosed in braces and allow for flexible configuration using HOCON features.
```laika-html
@:image { intrinsicWidth = 280px, intrinsicHeight = 220px }
```
--------------------------------
### HTML Code Block Example in Markdown
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Syntax.html
Shows how Markdown handles embedding HTML source code within an indented code block. Special characters like '&', '<', and '>' are automatically converted to their corresponding HTML entities for correct display.
```markdown
```
```html
<div class="footer">
© 2004 Foo Corporation
</div>
```
--------------------------------
### Configure Source Code Links in sbt
Source: https://github.com/typelevel/laika/blob/main/docs/src/03-preparing-content/02-navigation.md
This sbt configuration example sets up source code links by defining a base URI and a suffix for locating source files. It uses `laikaConfig` to apply `LinkConfig` with `SourceLinks`.
```scala
import laika.config.{ LinkConfig, SourceLinks }
laikaConfig := LaikaConfig.defaults
.withConfigValue(LinkConfig.empty
.addSourceLinks(
SourceLinks(baseUri = "https://github.com/team/project", suffix = "scala")
)
)
```
--------------------------------
### Nested HTML Structure
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Inline HTML (Simple).md
Demonstrates deeply nested HTML elements. This example shows how indentation is maintained in code blocks.
```html
foo
```
--------------------------------
### Absolute URI Example (FTP)
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Provides an example of an absolute URI with an FTP scheme, demonstrating hierarchical identifiers with path components.
```rst
ftp://ftp.python.org/pub/python
```
--------------------------------
### Markdown Headers, Paragraphs, and Blockquotes Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Basics.html
Demonstrates the creation of Setext and atx-style headers, regular paragraphs, and email-style blockquotes in Markdown. This showcases basic structural elements of document formatting.
```markdown
A First Level Header
====================
A Second Level Header
---------------------
Now is the time for all good men to come to
the aid of their country. This is just a
regular paragraph.
The quick brown fox jumped over the lazy
dog's back.
### Header 3
> This is a blockquote.
>
> This is the second paragraph in the blockquote.
>
> ## This is an H2 in a blockquote
```
```html
A First Level Header
A Second Level Header
Now is the time for all good men to come to
the aid of their country. This is just a
regular paragraph.
The quick brown fox jumped over the lazy
dog's back.
Header 3
This is a blockquote.
This is the second paragraph in the blockquote.
This is an H2 in a blockquote
```
--------------------------------
### Horizontal Rule (HR) Variations
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Inline HTML (Simple).md
Examples of various syntaxes for the HTML horizontal rule element (
). Includes self-closing and empty variations.
```html
```
```html
```
--------------------------------
### Apply Basic Laika Configuration
Source: https://github.com/typelevel/laika/blob/main/docs/src/02-running-laika/01-sbt-plugin.md
Sets basic configuration options for Laika using a builder-style API. This example enables strict mode and raw content processing via the `laikaConfig` sbt setting.
```scala
laikaConfig := LaikaConfig.defaults.strict.withRawContent
```
--------------------------------
### HTML Output for Ordered Lists
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Syntax.html
Illustrates the HTML structure generated by Markdown for ordered lists, highlighting that the source numbering does not impact the output.
```html
- Bird
- McHale
- Parish
```
--------------------------------
### Directive Body Markup Example (Laika HTML)
Source: https://github.com/typelevel/laika/blob/main/docs/src/05-extending-laika/03-implementing-directives.md
An example of a directive body in Laika HTML markup. The body content is demarcated by a closing fence `@:@`. This allows for regular markup content to be included within a directive.
```html
@:callout(warning)
This is the content of the body.
It is just regular markup.
@:@
```
--------------------------------
### Doctest Block Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.orig.html
Shows a doctest block in reStructuredText, used for Python-specific usage examples. Lines starting with '>>>' represent Python interactive session input, and subsequent lines represent the expected output.
```rst
Doctest blocks are for Python-specific usage examples; begun with ">>>"
>>> print 'Python-specific usage examples; begun with ">>>"'
Python-specific usage examples; begun with ">>>"
>>> print '(cut and pasted from interactive Python sessions)'
(cut and pasted from interactive Python sessions)
```
--------------------------------
### Use Laika Preview Server
Source: https://github.com/typelevel/laika/blob/main/docs/src/02-running-laika/01-sbt-plugin.md
This command starts the Laika preview server, which allows you to browse your generated site locally at `localhost:4242`. The server automatically refreshes when changes to input documents are detected. It also supports previewing the Document AST by appending `/ast` to the URL.
```bash
laikaPreview
```
--------------------------------
### Markdown Headers and Paragraphs
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Basics.md
Demonstrates Setext and atx-style headers, regular paragraphs, and blockquotes in Markdown. Shows the corresponding HTML output.
```Markdown
A First Level Header
====================
A Second Level Header
---------------------
Now is the time for all good men to come to
the aid of their country. This is just a
regular paragraph.
The quick brown fox jumped over the lazy
dog's back.
### Header 3
> This is a blockquote.
>
> This is the second paragraph in the blockquote.
>
> ## This is an H2 in a blockquote
```
```HTML
A First Level Header
A Second Level Header
Now is the time for all good men to come to
the aid of their country. This is just a
regular paragraph.
The quick brown fox jumped over the lazy
dog's back.
Header 3
This is a blockquote.
This is the second paragraph in the blockquote.
This is an H2 in a blockquote
```
--------------------------------
### Unordered Lists in Markdown
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Syntax.html
Demonstrates the use of asterisks, pluses, and hyphens for creating unordered lists in Markdown. These markers can be used interchangeably.
```markdown
* Red
* Green
* Blue
```
```markdown
+ Red
+ Green
+ Blue
```
```markdown
- Red
- Green
- Blue
```
--------------------------------
### Register Laika Extensions
Source: https://github.com/typelevel/laika/blob/main/docs/src/02-running-laika/01-sbt-plugin.md
Registers custom extensions for Laika transformations. This example adds GitHub Flavored Markdown support and syntax highlighting using the `laikaExtensions` sbt setting.
```scala
import laika.format.Markdown
import laika.config.SyntaxHighlighting
laikaExtensions := Seq(Markdown.GitHubFlavor, SyntaxHighlighting)
```
--------------------------------
### Build Laika Preview Server with Default Configuration
Source: https://github.com/typelevel/laika/blob/main/docs/src/02-running-laika/02-library-api.md
This code snippet demonstrates how to build a Laika preview server using its default configuration. It sets up a parser for Markdown with GitHub flavor and defines input directories. The server is then built and kept running indefinitely. This is useful for development and testing.
```scala
import laika.preview.ServerBuilder
import laika.markdown.Markdown
import laika.api.MarkupParser
import laika.ast.InputTree
import cats.effect.IO
val parser = MarkupParser
.of(Markdown)
.using(Markdown.GitHubFlavor)
.parallel[IO]
.build
val inputs = InputTree[IO]
.addDirectory("/path/to/your/inputs")
ServerBuilder[IO](parser, inputs)
.build
.use(_ => IO.never)
```
--------------------------------
### reStructuredText Option List Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Demonstrates the format for option lists, used to specify command-line options. Options can have arguments and long descriptions, and can include DOS/VMS-style options.
```rst
-a command-line option "a"
-b file options can have arguments
and long descriptions
--long options can be long also
--input=file long options can also have
arguments
/V DOS/VMS-style options too
There must be at least two spaces between the option and the
description.
```
--------------------------------
### Describe Laika Configuration using CLI
Source: https://github.com/typelevel/laika/blob/main/docs/src/02-running-laika/01-sbt-plugin.md
The `laikaDescribe` command outputs a formatted summary of the active Laika configuration. This includes details about parsers, renderers, extension bundles, settings, source files (markup, templates, CSS, copied files), and target directories. No specific inputs are required beyond running the command in a project context.
```shell
laikaDescribe
```
--------------------------------
### Setup Laika Parser for Multiple Output Formats (Scala)
Source: https://github.com/typelevel/laika/blob/main/docs/src/02-running-laika/02-library-api.md
This snippet demonstrates setting up a Laika parser for Markdown input, specifically using the GitHub flavor. It configures a parallel parser capable of reading from a directory and extracts its configuration for shared use with renderers. Dependencies include Laika's core modules and cats-effect.
```scala
val parserBuilder = MarkupParser.of(Markdown).using(Markdown.GitHubFlavor)
val parser = parserBuilder.parallel[IO].build
val config = parserBuilder.config
```
--------------------------------
### Indented Literal Block Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec-tidy.html
Demonstrates an indented literal block where code is preserved as-is. The block starts after a '::' marker and ends when the indentation stops. Blank lines before and after are not part of the block.
```text
This is a typical paragraph. An indented literal block follows.
::
for a in [5,4,3,2,1]: # this is program code, shown as-is
print a
print "it's..."
# a literal block continues until the indentation ends
This text has returned to the indentation of the first paragraph,
is outside of the literal block, and is therefore treated as an
ordinary paragraph.
```
--------------------------------
### HTML Output for Separated List Items
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Syntax.html
Compares the HTML output for list items separated by a blank line versus those that are not, showing the addition of `` tags when separated.
```html
- Bird
- Magic
```
```html
Bird
Magic
```
--------------------------------
### Example Option List Structure
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.orig.html
Demonstrates the basic two-column format of an option list, showing various option types, argument placeholders, and multi-paragraph descriptions. It highlights spacing requirements and how descriptions are indented.
```plaintext
-a Output all.
-b Output both (this description is
quite long).
-c arg Output just arg.
--long Output all day long.
-p This option has two paragraphs in the description.
This is the first.
This is the second. Blank lines may be omitted between
options (as above) or left in (as here and below).
--very-long-option A VMS-style option. Note the adjustment for
the required two spaces.
--an-even-longer-option
The description can also start on the next line.
-2, --two This option has two variants.
-f FILE, --file=FILE These two options are synonyms; both have
arguments.
/V A VMS/DOS-style option.
```
--------------------------------
### Example HTML Renderer Function
Source: https://github.com/typelevel/laika/blob/main/docs/src/05-extending-laika/07-new-markup-output-formats.md
A minimal Scala example demonstrating how to implement a render function for HTML elements using the TagFormatter. It shows pattern matching on AST nodes like Paragraph and Emphasized, and delegates rendering to the formatter.
```scala
import laika.ast._
import laika.api.format.TagFormatter
def renderElement (fmt: TagFormatter, elem: Element): String = {
elem match {
case p: Paragraph => fmt.element("p", p)
case e: Emphasized => fmt.element("em", e)
/* [other cases ...]
/* [fallbacks for unknown elements]
}
}
```
--------------------------------
### Configure Laika Preview Server with Custom Settings
Source: https://github.com/typelevel/laika/blob/main/docs/src/02-running-laika/02-library-api.md
This Scala code snippet shows how to create a Laika preview server with custom configurations. It overrides the default port to 8080, sets the polling interval to 5 seconds, enables EPUB and PDF downloads, and activates verbose logging. This allows for more tailored preview environments.
```scala
import laika.preview.ServerBuilder
import laika.preview.ServerConfig
import com.comcast.ip4s._
import scala.concurrent.duration.DurationInt
import laika.api.MarkupParser
import laika.markdown.Markdown
import laika.ast.InputTree
import cats.effect.IO
// Assuming parser and inputs are defined as in the previous example
val parser = MarkupParser
.of(Markdown)
.using(Markdown.GitHubFlavor)
.parallel[IO]
.build
val inputs = InputTree[IO]
.addDirectory("/path/to/your/inputs")
val serverConfig =
ServerConfig.defaults
.withPort(port"8080")
.withPollInterval(5.seconds)
.withEPUBDownloads
.withPDFDownloads
.verbose
ServerBuilder[IO](parser, inputs)
.withConfig(serverConfig)
.build
.use(_ => IO.never)
```
--------------------------------
### Inline Internal Target Syntax Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Demonstrates the syntax for inline internal targets, which are equivalent to explicit hyperlink targets but can appear within running text. The syntax starts with an underscore and backquote, followed by the hyperlink name or phrase, and ends with a backquote.
```rst
Oh yes, the _`Norwegian Blue`. What's, um, what's wrong with it?
```
--------------------------------
### Configure Source Code Links with Package Prefixes in sbt
Source: https://github.com/typelevel/laika/blob/main/docs/src/03-preparing-content/02-navigation.md
This sbt configuration example demonstrates setting up source code links with a default base URI and specific base URIs for packages matching a prefix. It uses `LinkConfig` and `SourceLinks` within `laikaConfig`.
```scala
import laika.config.{ LinkConfig, SourceLinks }
laikaConfig := LaikaConfig.defaults
.withConfigValue(LinkConfig.empty
.addSourceLinks(SourceLinks(
baseUri = "https://github.com/team/project",
suffix = "scala"
))
.addSourceLinks(SourceLinks(
baseUri = "https://github.com/elsewhere/project",
suffix = "scala"
).withPackagePrefix("com.lib42"))
)
```
--------------------------------
### Python Doctest Block Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Illustrates the usage of Python Doctest blocks, which are interactive Python sessions embedded in docstrings. These blocks start with '>>> ' and are treated as literal blocks unless explicitly formatted otherwise. They are processed by Python's `doctest` module.
```text
>>> print 'this is a Doctest block'
this is a Doctest block
```
--------------------------------
### Multiline HTML Comment
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Inline HTML (Simple).md
A multi-line HTML comment. This demonstrates how comments spanning multiple lines are handled.
```html
```
--------------------------------
### Python Indented Literal Block Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.orig.html
Demonstrates a Python code snippet within an indented literal block. Literal blocks are displayed as-is without markup processing and are typically rendered in a monospaced typeface. Indentation signifies the start and end of the block.
```python
for a in [5,4,3,2,1]: # this is program code, shown as-is
print a
print "it's..."
# a literal block continues until the indentation ends
```
--------------------------------
### Haskell Literate Programming Quoted Literal Block Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.orig.html
Illustrates a quoted literal block, often used for literate programming or email quoting. Each line starts with a specific quoting character (e.g., '>'). Blank lines terminate the block. Quoting characters are preserved.
```haskell
>> Great idea!
>
> Why didn't I think of that?
```
--------------------------------
### Compose Flexible Inputs with InputTree
Source: https://github.com/typelevel/laika/blob/main/docs/src/02-running-laika/02-library-api.md
This example illustrates the use of Laika's `InputTree` builder for highly flexible input composition. It allows adding directories, classpath resources, strings (like CSS), and AST nodes, providing fine-grained control over the input for transformation.
```scala
import laika.io.model._
import laika.ast.DefaultTemplatePath
import laika.ast.Path.Root
def generateStyles: String = "???"
val inputs = InputTree[IO]
.addDirectory("/path-to-my/markup-files")
.addDirectory("/path-to-my/images", Root / "images")
.addClassResource("templates/default.html", DefaultTemplatePath.forHTML)
.addString(generateStyles, Root / "css" / "site.css")
```
--------------------------------
### Markdown Inline Link Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Basics.md
Demonstrates how to create an inline-style link in Markdown, optionally including a title attribute. The output shows the generated HTML anchor tag.
```markdown
This is an [example link](http://example.com/).
This is an [example link](http://example.com/ "With a Title").
```
--------------------------------
### Absolute URI Example (Mailto)
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Shows an example of an absolute URI with a 'mailto:' scheme, representing an opaque identifier for an email address.
```rst
mailto:someone@somewhere.com
```
--------------------------------
### Indentation and Hanging Indents for Lists
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Syntax.html
Explains how to indent list items for better readability, including wrapping items with hanging indents and lazy alternatives.
```markdown
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.
```
```markdown
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.
```
--------------------------------
### Markdown Atx-style Headers
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Syntax.html
Demonstrates the syntax for Atx-style headers in Markdown, using 1 to 6 hash characters at the beginning of a line to denote header levels. Optionally, headers can be closed with hashes for cosmetic purposes.
```Markdown
# This is an H1
## This is an H2
###### This is an H6
# This is an H1 #
## This is an H2 ##
### This is an H3 ######
```
--------------------------------
### reStructuredText Definition List Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec-tidy.html
Provides an example of a definition list in reStructuredText, used to associate terms with their definitions. It demonstrates the indentation required for the definition paragraphs.
```rst
what
Definition lists associate a term with a definition.
how
The term is a one-line phrase, and the definition is one
or more paragraphs or body elements, indented relative to
the term.
```
--------------------------------
### Configure Download Page in Laika Helium
Source: https://github.com/typelevel/laika/blob/main/docs/src/03-preparing-content/03-theme-settings.md
Adds a download page to the Laika website, offering EPUB and PDF versions of the documentation. Options include setting the page title, description, download path, and whether to include EPUB/PDF.
```scala
import laika.ast.Path.Root
Helium.defaults
.site.downloadPage(
title = "Documentation Downloads",
description = Some("Optional Text Below Title"),
downloadPath = Root / "downloads",
includeEPUB = true,
includePDF = true
)
```
--------------------------------
### reStructuredText Option List Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec-tidy.html
Shows how to format command-line options within a reStructuredText document using an option list. It illustrates different option formats and how to associate them with descriptions.
```rst
-a command-line option "a"
-b file options can have arguments
and long descriptions
--long options can be long also
--input=file long options can also have
arguments
/V DOS/VMS-style options too
There must be at least two spaces between the option and the description.
```
--------------------------------
### Configure Syntax Highlighting with Library API
Source: https://github.com/typelevel/laika/blob/main/docs/src/03-preparing-content/05-syntax-highlighting.md
Activates Laika's syntax highlighting using the Library API by building a transformer. This example configures the transformer to use Markdown input and HTML output, including GitHub Flavor and SyntaxHighlighting extensions.
```scala
import laika.api._
import laika.format._
import laika.config.SyntaxHighlighting
val transformer = Transformer
.from(Markdown)
.to(HTML)
.using(Markdown.GitHubFlavor, SyntaxHighlighting)
.build
```
--------------------------------
### Generate Project Navigation Tree (Laika Markdown)
Source: https://github.com/typelevel/laika/blob/main/docs/src/03-preparing-content/02-navigation.md
This Laika Markdown snippet demonstrates how to generate a navigation tree for the entire project by referring to the virtual root (`/`). It inserts a `NavigationList` node into the AST.
```laika-md
@:navigationTree {
entries = [ { target = "/" } ]
}
```
--------------------------------
### RCS Keyword Expansion Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Illustrates how RCS keywords within bibliographic fields are processed and expanded. The example shows the raw input with a keyword and the expected processed output.
```text
:Status: $keyword: expansion text $
Processed, the "status" element's text will become simply "expansion text".
```
--------------------------------
### Markdown Image Syntax
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Basics.md
Shows the Markdown syntax for including images, both inline and reference-style. The provided examples demonstrate how to specify alt text, image source, and an optional title, along with the resulting HTML img tag.
```markdown
Inline:
Reference-style:
![alt text][id]
[id]: /path/to/img.jpg "Title"
```
--------------------------------
### Valid Length Unit Examples
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.orig.html
Presents examples of valid length values, including different units like em, mm, and in. These values consist of a floating-point number and a unit.
```text
1.5em
```
```text
20 mm
```
```text
.5in
```
--------------------------------
### Include EPUB and PDF Generation
Source: https://github.com/typelevel/laika/blob/main/docs/src/02-running-laika/01-sbt-plugin.md
Enables the generation of EPUB and PDF versions of your documentation in addition to the HTML site. These files will be placed in the configured download directory.
```scala
laikaIncludeEPUB := true
laikaIncludePDF := true
```
--------------------------------
### Python Doctest Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec-tidy.html
Demonstrates the use of doctest blocks in Python. These blocks are used for writing interactive Python session examples directly within documentation. They are recognized by the '>>>' prefix.
```python
>>> print 'Python-specific usage examples; begun with ">>>"'
Python-specific usage examples; begun with ">>>"
>>> print '(cut and pasted from interactive Python sessions)'
(cut and pasted from interactive Python sessions)
```
--------------------------------
### Block Styling Example (Commented Out)
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Shows an alternative block styling syntax using 'style::', commented out due to potential rethinking. It demonstrates styling a block of text with a specific role.
```rst
.. style:: motto
At Bob's Underwear Shop, we'll do anything to get in
your pants.
.. style:: disclaimer
All rights reversed. Reprint what you like.
```
--------------------------------
### Configure E-book Download Path and Artifact Name
Source: https://github.com/typelevel/laika/blob/main/docs/src/02-running-laika/01-sbt-plugin.md
Allows customization of the download path for e-books and the base name for the generated artifact files (e.g., my-book.epub).
```scala
import laika.ast.Path.Root
import laika.config.LaikaKeys
laikaConfig := LaikaConfig.defaults
.withConfigValue(LaikaKeys.site.downloadPath, Root / "e-books")
.withConfigValue(LaikaKeys.artifactBaseName, "my-book")
```
--------------------------------
### Laika Substitution Definition: Function Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
An example of using substitution definitions to reference a specific programming function, including its module and class. This aids in referencing code elements within documentation.
```rst
4XSLT has the convenience method |runString|, so you don't
have to mess with DOM objects if all you want is the
transformed output.
.. |runString| function:: module=xml.xslt class=Processor
```
--------------------------------
### Configure API Links with Package Prefixes in sbt
Source: https://github.com/typelevel/laika/blob/main/docs/src/03-preparing-content/02-navigation.md
This sbt configuration example shows how to set up API links with a default base URI and specific base URIs for packages matching a prefix. It utilizes `LinkConfig` and `ApiLinks` within `laikaConfig`.
```scala
import laika.config.{ LinkConfig, ApiLinks }
laikaConfig := LaikaConfig.defaults
.withConfigValue(LinkConfig.empty
.addApiLinks(ApiLinks("https://example.com/api"))
.addApiLinks(ApiLinks("https://somewhere-else/").withPackagePrefix("com.lib42"))
)
```
--------------------------------
### Creating Decoders and Encoders
Source: https://github.com/typelevel/laika/blob/main/docs/src/06-sub-modules/03-laikas-hocon-api.md
Explains the necessity of decoders for reading configuration values and encoders for programmatically building configuration instances.
```APIDOC
## Creating Decoders and Encoders
### Description
Decoders are essential for translating configuration values into specific types when reading from `Config` instances. Encoders are used when you need to populate a `Config` instance programmatically.
### Key Concepts
- **`ConfigDecoder[T]`**: An implicit type class that defines how to decode a configuration value into a type `T`. Laika provides built-in decoders for basic types (String, Int, Boolean, Path, Date) and their collections.
- **`ConfigEncoder[T]`**: A type class that defines how to encode a value of type `T` into a configuration representation, used for programmatic building.
### Usage
- **Decoders**: Automatically used by `config.get[T](...)` when a `ConfigDecoder[T]` is in implicit scope.
- **Encoders**: Used in methods like `Config.set(...)` or during programmatic configuration building (e.g., using `ConfigBuilder`).
### Further Information
Refer to the @:api(laika.config.Config) documentation for detailed API information on creating and using decoders and encoders.
```
--------------------------------
### Standalone Hyperlink Syntax Example (HTTP)
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Demonstrates how standalone URIs within text blocks are treated as external hyperlinks, using the URI itself as the link text. This example shows an absolute HTTP URI.
```rst
See http://www.python.org for info.
```
--------------------------------
### Helium Theme Configuration Example (Scala)
Source: https://github.com/typelevel/laika/blob/main/docs/src/05-extending-laika/02-creating-themes.md
Demonstrates how to configure a Laika theme using the Helium API. It shows setting metadata for all formats, and navigation depth for EPUB and PDF outputs. This configuration allows users to customize various aspects of the theme's appearance and behavior.
```scala
import laika.helium.Helium
val theme = Helium.defaults
.all.metadata(
title = Some("Project Name"),
language = Some("de"),
)
.epub.navigationDepth(4)
.pdf.navigationDepth(4)
.build
```
--------------------------------
### Substitution Reference Syntax Examples
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Presents examples of substitution references, enclosed in vertical bars. These can optionally be followed by '_' or '__' to act as hyperlink references. The system replaces these with corresponding substitution definition content.
```rst
This is a simple |substitution reference|. It will be replaced by
the processing system.
This is a combination |substitution and hyperlink reference|_. In
addition to being replaced, the replacement text or element will
refer to the "substitution and hyperlink reference" target.
```
--------------------------------
### Laika Substitution Definition: List Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Provides an example of using substitution definitions for simple inline text replacements, like traffic light signals. This demonstrates the flexibility for various inline content.
```rst
* |Red light| means stop.
* |Green light| means go.
```
--------------------------------
### Setup Laika Renderers for Multiple Output Formats (Scala)
Source: https://github.com/typelevel/laika/blob/main/docs/src/02-running-laika/02-library-api.md
This snippet shows how to create parallel renderers for HTML, EPUB, and PDF formats using a shared configuration obtained from a Laika parser. It utilizes cats-effect for parallel processing capabilities. Dependencies include Laika's renderer modules and cats-effect.
```scala
val htmlRenderer = Renderer.of(HTML).withConfig(config).parallel[IO].build
val epubRenderer = Renderer.of(EPUB).withConfig(config).parallel[IO].build
val pdfRenderer = Renderer.of(PDF).withConfig(config).parallel[IO].build
```
--------------------------------
### Laika Substitution Definition: Book Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Shows a substitution definition example linking a book title to its ISBN. This mechanism allows embedding object identifiers within inline text for later processing.
```rst
|The Transparent Society| offers a fascinating alternate view
on privacy issues.
.. |The Transparent Society| book:: isbn=0738201448
```
--------------------------------
### Laika Incorrect Bullet List Formatting Examples
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Shows examples of incorrectly formatted bullet lists in Laika, specifically focusing on issues with blank lines between list items and paragraphs, and incorrect indentation for sublists.
```text
- This first line is fine.
A blank line is required between list items and paragraphs.
(Warning)
- The following line appears to be a new sublist, but it is not:
- This is a paragraph continuation, not a sublist (since there's
no blank line). This line is also incorrectly indented.
- Warnings may be issued by the implementation.
```
--------------------------------
### Build EPUB Transformer and Transform
Source: https://github.com/typelevel/laika/blob/main/docs/src/02-running-laika/02-library-api.md
This snippet demonstrates building an EPUB transformer from Markdown input and then using it to transform content from a directory to an EPUB file. It utilizes Laika's `Transformer` API for configuration.
```scala
val epubTransformer = Transformer
.from(Markdown)
.to(EPUB)
.using(Markdown.GitHubFlavor)
.parallel[IO]
.build
val epubRes: IO[Unit] = epubTransformer.use {
_.fromDirectory("src")
.toFile("output.epub")
.transform
}
```
--------------------------------
### Laika Bullet List Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Provides an example of a correctly formatted bullet list in Laika, including nested sublists and multi-paragraph list items. It highlights the requirement for blank lines between list items and paragraphs.
```text
- This is the first bullet list item. The blank line above the
first list item is required; blank lines between list items
(such as below this paragraph) are optional.
- This is the first paragraph in the second item in the list.
This is the second paragraph in the second item in the list.
The blank line above this paragraph is required. The left edge
of this paragraph lines up with the paragraph above, both
indented relative to the bullet.
- This is a sublist. The bullet lines up with the left edge of
the text blocks above. A sublist is a new list so requires a
blank line above and below.
- This is the third item of the main list.
This paragraph is not part of the list.
```
--------------------------------
### reStructuredText Admonition Directive Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec-tidy.html
Shows how to use the admonition directive (e.g., .. note::) in reStructuredText to create distinct blocks for notes, warnings, or other highlighted content. It includes an example with a bullet list as content.
```rst
.. note:: This is a paragraph
- Here is a bullet list.
```
--------------------------------
### Markdown Reference-Style Link Example
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Basics.md
Illustrates the creation of reference-style links in Markdown, where link definitions are placed separately. It covers both numbered and named references, with and without optional titles. The output displays the resulting HTML anchor tags.
```markdown
I get 10 times more traffic from [Google][1] than from
[Yahoo][2] or [MSN][3].
[1]: http://google.com/ "Google"
[2]: http://search.yahoo.com/ "Yahoo Search"
[3]: http://search.msn.com/ "MSN Search"
I start my morning with a cup of coffee and
[The New York Times][NY Times].
[ny times]: http://www.nytimes.com/
```
--------------------------------
### Example Field Lists in reStructuredText
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.rst
Provides examples of field lists in reStructuredText, used for metadata or key-value pairs. It demonstrates the syntax for field names, colons, and indented field bodies, including multi-line bodies and classifiers.
```rst
:Date: 2001-08-16
:Version: 1
:Authors: - Me
- Myself
- I
:Indentation: Since the field marker may be quite long, the second
and subsequent lines of the field body do not have to line up
with the first line, but they must be indented relative to the
field name marker, and they must line up with each other.
:Parameter i: integer
```
--------------------------------
### Create a Basic Block Parser
Source: https://github.com/typelevel/laika/blob/main/docs/src/05-extending-laika/04-writing-parser-extensions.md
This method creates a parser for block elements that consume lines based on prefixes. It expects parsers for the first line's prefix and subsequent lines' prefixes. The result is a `BlockSource` containing the stripped lines, and parsing stops on a blank line.
```scala
def block (firstLinePrefix: Parser[Any],
linePrefix: => Parser[Any]): Parser[BlockSource]
```
--------------------------------
### Markdown Lists (Unordered and Ordered) Examples
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/markdownTestSuite/Markdown Documentation - Basics.html
Shows how to create unordered (bulleted) and ordered (numbered) lists in Markdown. Demonstrates the use of asterisks, pluses, hyphens for unordered lists, and numbers with periods for ordered lists. Also covers multi-paragraph list items.
```markdown
* Candy.
* Gum.
* Booze.
```
```html
- Candy.
- Gum.
- Booze.
```
```markdown
+ Candy.
+ Gum.
+ Booze.
```
```markdown
- Candy.
- Gum.
- Booze.
```
```markdown
1. Red
2. Green
3. Blue
```
```html
- Red
- Green
- Blue
```
```markdown
* A list item.
With multiple paragraphs.
* Another item in the list.
```
```html
A list item.
With multiple paragraphs.
Another item in the list.
```
--------------------------------
### Line Blocks in Laika
Source: https://github.com/typelevel/laika/blob/main/core/jvm/src/test/resources/rstSpec/rst-spec.orig.html
Line blocks are used to preserve line breaks and indentation, suitable for addresses, poetry, or unadorned lists. They are defined by lines starting with a vertical bar '|'. Continuation lines start with a space.
```text
| Lend us a couple of bob till Thursday.
| I'm absolutely skint.
| But I'm expecting a postal order and I can pay you back
as soon as it comes.
| Love, Ewan.
| A one, two, a one two three four
|
| Half a bee, philosophically,
| must, *ipso facto*, half not be.
| But half the bee has got to be,
| *vis a vis* its entity. D'you see?
|
| But can a bee be said to be
| or not to be an entire bee,
| when half the bee is not a bee,
| due to some ancient injury?
|
| Singing...
```
--------------------------------
### Configure Site Base URL (sbt)
Source: https://github.com/typelevel/laika/blob/main/docs/src/03-preparing-content/01-directory-structure.md
Configure the site's base URL in an sbt environment using Laika's standard configuration API. This sets the `siteBaseURL` configuration value.
```scala
import laika.config.LaikaKeys
laikaConfig := LaikaConfig.defaults
.withConfigValue(LaikaKeys.siteBaseURL, "https://my-docs/site")
```