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
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.next$: gives references to specified “links”.
homecorresponds to the root page of the project,
nextis the next page, and
prevthe 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
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:
$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_urlis 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.
Properties are key-value pairs available in your pages. For a property named
- Inside template files use
$foo$if the template’s name does not contain dots.
- Inside markdown files use either
- Inside markdown file container blocks delimited by ``` use
@@@varsaround the block and
$foo$to call the property.
$ 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)
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$
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$
Paradox allows to specify some properties at page level using
--- delimiters at the top of the page.
out property allows to rename the target name of the current file.
--- out: newIndex.html --- /* * Content of the page */
newIndex.html will be the new name of the generated file. Links leading to this page are automatically updated.
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 */
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
paradoxProperties += ("layout" -> "myDefault.st")