Templating

Paradox uses StringTemplate for the basic templating, i.e. for creating full HTML documents from documentation content generated from markdown. A set of templates of assets that comprises all that is needed for a full documentation page, is called a theme. There’s a default theme that is used if nothing else was specified.

String Templates are text files that include placeholders where property values are to be inserted during generation

Properties

Here is a list of supported properties that can be used in the string template files:

• $page.title$ : display the title of the page which corresponds to the first header on a page.
• $page.content$ : display the processed content of your entire markdown source file.
• $page.base$ : display the relative path to the root folder of the project.
• $page.home$, $page.prev$, $page.next$ : gives references to specified “links”. home corresponds to the root page of the project, next is the next page, and prev the previous one in the paradox navigation. Each “link” can provide four fields:
• href : displays the relative path.
• html : gives directly the url leading to this link.
• title : displays the title of the link (same process than $page.title$) - active : determines if the link is currently active or not. Particularly useful if we want to check whether we are on the main page or not: $if(page.home.active)$
• $page.breadcrumbs$ : gives the list of the parent folder of the current page and each parent is displayed as a link.
• $page.navigation$ : gives the links of all pages in the project (except the main page).
• $page.subheaders$ : determines if the current page contains subheaders or not, which concretely means that it contains multiple sections depending on the `toc-.
• $page.toc$ : in relation with $page.subheaders$, displays the list of all sections on the page as anchor links.
• $page.source_url$ : contains the plain text of the github source url of the current page. Works only if the associated github.base_url is defined (see github directive for additional information). If this property is not defined, this field returns a null value; then a condition testing like $if(page.source_url)$ would be necessary in this case.
• $page.properties$: displays purely the list of the properties for the current page, which contains the actual properties of the page and the global ones shared to all pages. See next sections to figure out how to deal with properties.

Custom properties

Properties are key-value pairs available in your pages. For a property named foo:

• Inside template files use $page.properties.("foo") or $foo$ if the template’s name does not contain dots.
• Inside markdown files use either $foo$ inline.
• Inside markdown file container blocks delimited by ``` use @@@vars around the block and $foo$ to call the property.

The special $ character can always be escaped with a back slash, i.e. \$.

To add properties to your pages, there exists two ways for doing this:

• To add properties to the entire document, common to all pages, you can add them in your build: paradoxProperties += ("foo" -> "bar")
• To add properties at page level, use Properties front matter (next section)

Conditionals

It is possible to conditionally include a section based on a boolean expression:

$if(page.next.html)$
<div class="nav-next">
<p><strong>Next:</strong> $page.next.html$</p>
</div>
$endif$

The property_is page property can be used to check whether a property has a certain value:

$if(page.property_is.("project.license").("Apache-2.0"))$
<section class="copyright">
<div>$page.properties.("project.name")$ is Open Source and available under the Apache 2 License.</div>
$endif$

Properties front matter

Paradox allows to specify some properties at page level using --- delimiters at the top of the page.

out

The out property allows to rename the target name of the current file.

---
out: newIndex.html
---
/*
 * Content of the page
 */

where newIndex.html will be the new name of the generated file. Links leading to this page are automatically updated.

layout

The layout of the page is determined by default by a template called page.st. Using layout property, we can change the layout template to something else for this particular page. The layouts are generated by default in paradox in the target/paradox/theme folder, but you can create one in src/main/paradox/_template folder as a string template file (.st).

---
layout: templateName
---
/*
 * Content of the page
 */

where templateName is the name of a template, more precisely the templateName.st file, which could either be a predefined template, or a created one in the src/main/paradox/_template folder. The default templates generated by paradox depends on the theme used, see this for more info about themes.

If you want to set a new default template page, let’s say myDefault.st for all your pages, you can set it by specifying the layout in build.sbt:

  paradoxProperties += ("layout" -> "myDefault.st")