Create a Custom Template
Page Content
How to Create a Template
Create a directory for your template and give it a name (name the directory)
Optionally create an
assets
directory inside of your template directory. This is for static assets that your template will use, including images, CSS, JavaScript, etc. All files within this directory will be copied as is during the build process into the built directory.Create a
layout
directory inside of your template directory and add adefault.html
file to thelayout
directory. Read more about creating layouts.Create a
styles
directory inside of your template directory if you want to use SASS styling for your template. Read more about SAAS styling for your templates.
Layouts
Summary
A
default
layout is required and must be nameddefault.html
.Layouts use EJS templating for dynamic HTML generation.
When a layout is rendered it gets information about what is being rendered.
Details
Your markdown pages can specify which template layout they want to user in their headers. If a markdown file does not specify which template to use then the default
template will be used. Therefore, every template must define a default
template.
To create a layout create an html
file inside the layouts
directory. The name you give this file will be the name of the layout that your markdown files can reference it by. For example, if you have a layout file named main.html
then your markdown file can include in its headers layout: main
to select this layout.
On render, a template receives data about what is to be rendered, including:
content - The HTML rendered from the markdown file.
navigation - The HTML rendered navigation based on the documentations directory structure.
page - Page headers as defined by your markdown files as well as default page header values.
site - Site variables as defined in the documentation's configuration file.
toc - A page's table of contents menu, rendered as specified by the page headers as HTML.
Example
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title><%= site.title %> | <%= page.title %></title>
<% if (page.description) { %><meta name="description" content="<%= page.description %>"><% } %>
<link rel="icon" href="/favicon.png">
<link rel="stylesheet" href="/assets/css/main.css">
</head>
<body>
<% if (page.title) { %>
<h1><%= page.title %></h1>
<% } %>
<% if (toc) { %>
<div class="toc">
<div>Page Contents</div>
<%- toc %>
</div>
<% } %>
<div class="content">
<%- content %>
</div>
<script src="/assets/js/main.js"></script>
</body>
</html>
SASS Styles
Summary
SASS files for your template should exist in a
styles
directory at the root of your template's directory.SASS files that have a comment
// SASS bootstrap
will be rendered to CSS.SASS files that are bootstrapped can also take configuration file input to overwrite default values.
Description
Templates can use SASS to generate CSS files. The SASS files must exist in a directory named styles
in the root of your template's directory. For all SASS files that you'd like rendered, include the comment // SASS bootstrap
.
While defining your SASS files there may be certain values that you would like to allow the user of your template to define. To accomplish this you must first define the default value and then on the same line add the comment // VAR varName
where varName
is the name of the variables that can be used to overwrite the default value.
Example
In this example we set the body default color to #333
but this can be overwritten if the textColor
is specified in the configuration file's cssVars object.
SCSS File
body {
color: #333; // VAR textColor
background: white; // VAR backgroundColor
}
Config File
module.exports = {
title: 'My Site',
template: {
cssVars: {
textColor: 'white',
backgroundColor: '#333'
}
}
}