Skip to content

HTML components

Jump to bottom Edit New page
Szymon Witamborski edited this page Nov 24, 2013 · 9 revisions

This page describes the components Stencil uses to generates HTML output files.

Pages

Pages are the input files given to stencil which map directly to output files (for each given page, a single output file is compiled). Pages can be written in pure HTML or markdown, and include both doT variables as well as a JSON meta data header to hold any required meta data about that page (and the partials included in that page).

A page is tied with other HTML components in the following ways:

  • Using a built-in include function in doT's it object, a page can include the compiled contents of any partial.
    • {{= it.include("my_partial.md") }} in the content of a page
  • Defining a template file in the page's JSON header, a page will be wrapped with that template. The contents of the page will be injected to the template whereever {{= it.document }} is placed.
    • {"template": "default.html"} in the header of a page

Both include function and document objects hold fields of respectively partial's and wrapped page's headers.

The following page, for example, will include the compiled source of both footer.md and navigation.dot.html, and will be injected into the template default.dot.html. Note that specifying file extensions to both partials and templates is optional.

page.html:

{
  "body_class": "main",
  "title": "Welcome",
  "template": "default"
}

<div class="wrapper">
  {{= it.include("navigation") }}

  <div class="content">
    Content
  </div>

  {{= it.include("footer") }}
</div>

default.dot.html:

<html>
  <head>
    <title>{{= it.document.title }}</title>
  </head>
  <body class="{{= it.document.body_class }}">
    <!-- Use the document key to specify where a page should be included into a template -->
    {{= it.document }}
  </body>
</html>

Partials

Partials are small files to hold chunks of content that can be shared by many pages. Partials can, too, be written in both pure HTML, markdown, and include doT variables and a meta data header (including a template the partial should be wrapped with). Partials can also include other partials. A simplified footer.md partial might look as follows (note the combined usage of doT variables and markdown):

__Copyright 2013 Stencil__

*{{= it.include('contact_information') }}*

include function accepts a second argument which is an optional environment passed to the partial. Partial can then use the variable inside as long it doesn't define one with the same name in it's header. (Local header fields take precedence.)

Example page:

{{= it.include('widget', { title: 'how great!' }) }}

widget partial can be something like this:

{{= it.title }}

Templates

Templates are HTML wrapper files that can be used to avoid rewriting head tags, script and style tags, headers or other code that pages or partials might share. To specify where the contents of a page should be injected inside a template, {{= it.document }} should be used.

In the following example, a template file defines the generic <head> element with script and stylesheet tags, and inherits meta data from the page that uses it.

main_page.dot.html:

{
  "template": "default_template",
  "title": "My page title",
  "stylesheet": "styles/main.css",
  "scripts": ["js/onload.js", "js/menu.js"],
  "body_class": "blue_links",
}

<header>
  <ul>
    <li><a href="home.html">Home</a></li>
    <li><a href="contact.html">Contact</a></li>
  </ul>
</header>

<div class="content">
  Welcome!
</div>

default_template.dot.html:

<html>
  <head>
    <title>{{= it.document.title }}</title>

    <!-- Loop through given scripts -->
    {{~it.document.scripts :script}}
    <script type="text/javascript" src="{{= script }}">
    {{~}}

    <link rel="stylesheet" type="text/css" href="{{= it.document.stylesheet }}">
  </head>
  <body class="{{= it.document.body_class }}">
    {{= it.document }}
  </body>
</html>

Compiling main_page.dot.html with the default options will result in main_page.html:

main_page.html:

<html>
  <head>
    <title>My page title</title>
    <!-- Loop through given scripts -->
    <script type="text/javascript" src="js/onload.js">
    <script type="text/javascript" src="js/menu.js">

    <link rel="stylesheet" type="text/css" href="styles/main.css">
  </head>
  <body class="blue_links">
    <header>
      <ul>
        <li><a href="home.html">Home</a></li>
        <li><a href="contact.html">Contact</a></li>
      </ul>
    </header>

    <div class="content">
      Welcome!
    </div>
  </body>
</html>
Add a custom footer
Add a custom sidebar
Clone this wiki locally