Default Theme

Ornate‘s default theme generates multiple HTML pages for the site, one per page. It uses Foundation’s Flexbox-based CSS layout for responsive design across different classes of devices. All assets are included in the generated site by default.

Configuration

This is the theme’s default configuration:

# Theme-specific settings for the default theme.
theme.default {
  # Settings which are only accessed globally
  global {
    # Synthetic pages to be generated without matching source files.
    # Source URI (relative to site:/), or null to omit a page.
    # If a matching source file exists, it is used instead of generating a page.
    pages {
      toc = "site-contents.md"
      #index = "site-index.md"
      search = "site-search.md"
    }
    # Directory (as URI relative to site:/) where the theme places resources
    resourceDir = "theme"
    # If set to a file name like "index.html", generated links to this name will
    # go to the directory instead
    indexPage = null
    # Search index file that is generated if theme.default.global.pages.search
    # is defined (URI relative to site:/, or null to disable the search index)
    searchIndex = "search-index.js"
    # Array of gitignore-style patterns matching page URIs (relative to site:/)
    # to exclude from the search index
    searchExcludePages = [ ${theme.default.global.pages.search} ]
    # Number of characters per page to use for excerpts in search results
    # (0 to disable excerpts)
    searchExcerptLength = 200
    # Front matter for the generated search page
    searchPageConfig {
      theme.default.template: search
      theme.default.pageNav: false
    }
    minify {
      all = false
      # Minify CSS files with CSSO
      css = ${theme.default.global.minify.all}
      # Minify JS files with Closure Compiler
      js = ${theme.default.global.minify.all}
      # Minify generated HTML files with HtmlCompressor
      html = ${theme.default.global.minify.all}
    }
    # Configuration options for MathJax
    mathJax {
      # The config files to preload:
      loadConfig = ["TeX-MML-AM_CHTML-full"]
      # A configuration object to put into the generated HTML files
      inlineConfig = {
        # The default scheme automatically schedules a `Process` command on startup when
        # this option is set. This avoids running any preprocessors that may have been
        # loaded (but are not needed because Ornate creates `script` tags for MathJax's
        # main processing step).
        skipStartupTypeset: true
      }
    }
    # Configurable colors for the global stylesheet
    color {
      # The main accent color, used for links and active navigation markers
      accent = "rgb(0,120,215)"
      # A light accent color for backgrounds. If unset, use `accent` with 0.15 alpha
      accentBackground = null
      # Text color for page headers and footers
      headerFooter = "white"
      # Background color for page headers and footers
      headerFooterBackground = "#444"
    }
    # Extra CSS settings to append to the generated app.css file
    css  = null
    # A file (relative to the base directory) containing extra CSS settings
    cssFile = null
  }
  # English-language default strings, referenced from theme.default.strings.
  # Strings are usually parsed as Markdown in the context of the surrounding page.
  en {
    siteNav = null
    pageNav = "On This Page"
    headerLeft = ${meta.siteTitle}
    headerRight = null
    footerLeft = ${meta.copyright}
    footerRight = "Generated with [Ornate](https://github.com/szeiger/ornate)."
    navFirst = "![](foundation-icon:previous) First"
    navPrev = "![](foundation-icon:arrow-left) Previous"
    navNext = "![](foundation-icon:arrow-right) Next"
    navLast = "![](foundation-icon:next) Last"
    navToc = "![](foundation-icon:list-thumbnails) Contents"
    navIndex = "![](foundation-icon:list) Index"
    navEdit = "![](foundation-icon:page-edit) Edit Page"
    versionNavPrefix = "Version:"
    versionNavLoading = "Loading..."
    tocPage = "# Table of Contents\n\n![](toctree:)"
    indexPage = "# Index\n\n![](index:)"
    indexSymbols = "Symbols"
    searchPlaceholder = "Search"
    searchPage = "# Search\n\nFrom here you can search all pages. Enter the search terms below and click the search button. Note that the search function will search for a combination of *all* search terms."
    noScript = "> {.warning}\n> This page requires JavaScript. Please enable JavaScript in your browser."
    # The searchCount strings are plain text only:
    searchCount0 = "No matching pages found."
    searchCount1 = "Found one matching page:"
    searchCountN = "Found # matching pages:"
  }
  # Localized strings
  strings = ${theme.default.en}
  # Type of the site navigation on the left side ("toctree:" URI or null)
  siteNav = "toctree:maxLevel=1"
  # Show multi-version site navigation on the left side below siteNav
  versionNav = false
  # Show multi-version dropdowns for "versions:/" URIs
  versionNavDropdown = true
  # Index page from which to determine the available versions for the multi-version
  # site navigation, relative to the site root's target URI
  versionIndex = "../"
  # Show page navigation on the right side (true or false, or null to enable
  # automatically when the page has more than one section)
  pageNav = null
  # Max depth for page navigation (or null to use global.tocMaxLevel)
  pageNavMaxLevel = null
  # Content of navigation bars above and below the content. Possible contents are
  # first, prev, next, last, toc, index, edit. If none of the configured links are
  # available, the bar is not shown.
  topNavBar = [prev, next, edit, toc]
  bottomNavBar = ${theme.default.topNavBar}
  # The target for the "Edit Page" link on all non-synthetic pages. The string `[page]`
  # is replaced by the source page URI relative to global.sourceDir. Set to null to
  # disable "edit page" links.
  editPage = null
  # The template that is used to render pages
  template = default
  # A list of extra "link" elements for the HTML header. Each entry is an object whose
  # fields are HTML attributes. The "href" attribute is resolved relative to the current
  # page's "site:" URI, all other attributes are copied verbatim.
  links = []
}

ornate-reference.conf

Third-Party Content

Sites that are generated by the default theme contain Foundation 6 and its dependencies (JQuery, what-input), all of which are available under the MIT License.

Sites that are generated by the default theme may contain Foundation Icon Fonts 3 which is available under the MIT License.

Sites that are generated by the default theme may contain fonts from Font Awesome which are available under the SIL OFL 1.1.

When using Mermaid diagrams, the generated site includes Mermaid which is available under the MIT License.

When using MathJax for math notation, the generated site includes MathJax which is available under the Apache License.

When using the Emoji extension, the generated sites can contain images from the EmojiOne project which require attribution when used in commercial projects.

Search

The default theme can generate a JavaScript-based search function for the site using Elasticlunr (available under the MIT License). The search index includes page titles, content and keywords. See above for configuration options.

Minification

Ornate can minify generated HTML files, JavaScript assets and CSS using the following libraries:

CSSO (running on Nashorn) for CSS
Closure Compiler for JavaScript
HtmlCompressor for HTML

Minification is turned off by default for better performance when building the site. It can be enabled with the following settings under theme.default.global:

minify {
  all = false
  # Minify CSS files with CSSO
  css = ${theme.default.global.minify.all}
  # Minify JS files with Closure Compiler
  js = ${theme.default.global.minify.all}
  # Minify generated HTML files with HtmlCompressor
  html = ${theme.default.global.minify.all}
}

ornate-reference.conf

Snippet Source Links

Snippets from fenced code blocks can show links to an appropriate source file by setting the sourceLinkURI attribute. If sourceLinkText is also set, it is used as the link text, otherwise the file name from the URI is used.

Example:

```text sourceLinkURI=https://github.com/szeiger/ornate/blob/v0.2/README.md
*Ornate* is a tool for building multi-page HTML sites from Markdown sources.
```

This gets rendered as (link shown on mouse-over):

*Ornate* is a tool for building multi-page HTML sites from Markdown sources.

README.md

The includeCode extension can generate link targets for included snippets automatically.

Shortcut Icons

Shortcut icons can be defined through custom link elements with appropriate rel and href values under theme.default:

# A list of extra "link" elements for the HTML header. Each entry is an object whose
# fields are HTML attributes. The "href" attribute is resolved relative to the current
# page's "site:" URI, all other attributes are copied verbatim.
links = []

ornate-reference.conf

For example, this is how you add a standard favicon.ico located under global.resourceDir:

theme.default.links = [
  { rel: "icon", href: "/favicon.ico" }
]

Customization

Some of the default theme’s colors can be changed under theme.default.global.color. These are the default values:

# Configurable colors for the global stylesheet
color {
  # The main accent color, used for links and active navigation markers
  accent = "rgb(0,120,215)"
  # A light accent color for backgrounds. If unset, use `accent` with 0.15 alpha
  accentBackground = null
  # Text color for page headers and footers
  headerFooter = "white"
  # Background color for page headers and footers
  headerFooterBackground = "#444"
}

ornate-reference.conf

Other styles can be changed by appending custom CSS code to the generated app.css file. These are the defaults (under theme.default.global):

# Extra CSS settings to append to the generated app.css file
css  = null
# A file (relative to the base directory) containing extra CSS settings
cssFile = null

ornate-reference.conf

Index

The default theme can generate an index page from user-defined keywords. Using the headerAttributes extension, you can define the keywords with the index key. Nested keywords are separated by commas, multiple independent keywords are separated by semicolons. For example, the following header definition contributes two index entries “Bar” and “Foo, Bar” that link to the header:

## Foo Bar {index="Bar;Foo,Bar"}

Multi-Version Sites

The default theme can add code for an automatic client-side multi-version navigation that allows users to switch between different versions of the site, going to the same page if it exists in the selected version or the root of the site otherwise. This works by reading an existing HTML index page (either auto-generated by the web server or maintained manually). Due to security restrictions and the way browsers handle directory listings this does not work (and is in fact automatically disabled) when loading a generated site from a file: URL. You have to put it on a web server to make it work.

The feature can be enabled under theme.default. Here is the default configuration:

# Show multi-version site navigation on the left side below siteNav
versionNav = false
# Show multi-version dropdowns for "versions:/" URIs
versionNavDropdown = true
# Index page from which to determine the available versions for the multi-version
# site navigation, relative to the site root's target URI
versionIndex = "../"

ornate-reference.conf

Example: A typical directory layout looks like this:

/
  docs/
    0.1/
      index.html
      foo.html
    0.2/
      index.html

Here /docs/0.1/ and /docs/0.2/ are two versions of a site that have been generated independently with Ornate. All HTML pages load ../ (the auto-generated directory listing of /docs/) as the index page and detect the versions 0.1 and 0.2 from it. For example, on /docs/0.1/foo.html you get a link to /docs/0.2/foo.html. When you click on it the navigation script first checks if the page exists and since it doesn’t in this case, it loads /docs/0.2/ instead.

Instead of a separate navigation section below the page navigation the version switcher can be integrated into a version number that is shown in the title bar by embedding an image with the special versions:/ URI. For example, the following definition could be used by this manual if it was supposed to be published as a multi-version site:

meta.siteTitle = "Ornate !["${version}"](versions:/) Manual"