Night Owl logoNight Owl

Glossary

This page lists some of the terms that are used throughout this site. Night Owl uses similar terms to other tools, so if you have used a static site generator before, you may already be familiar with these terms.

Templates

A file written in a format such as Markdown, Pug, Sass or JavaScript. Templates are compiled and rendered into one or more pages. When templates render, they are provided with data from the template, as well as layout and global data.

Pages

Pages are files that are generated from templates. They are usually HTML files, but can be any file type. A single template produces one page, unless it has pages or index data.

Layouts

Layouts let you reuse the same consistent page structure across multiple pages. Layouts are useful for Markdown or JavaScript templates, which only contain data and content. Templates can use a separate Pug file to control how their content is rendered.

Data

Templates use data to control the way content is rendered. Pug and Markdown templates might include data in their front‑matter, while JavaScript templates declare data as their default export. Data can be provided by a global data file, and layouts can also include data in their front‑matter.

Night Owl also creates some additional meta data that is supplied to a page when it renders.

Collections

A collection is an array of pages grouped together. Collections are created by using tags in the template data. A template can have any number of tags, and appear in multiple collections.

Indexes

An index is a series of paginated results listing different items, using one or more pages. Indexes are useful for listing all the items in a collection or subdirectory over multiple pages of results, just like the index of a book. And indexes are not limited to listing other pages — you use normal arrays to make an index too.

Front-matter

Templates and layouts use front‑matter to define data. You add front‑matter at the top of your file, surrounded by three hyphens above and below.

---
title: "My title"
object: { property: 12 }

# You can add comments

# YAML has a few ways to specify arrays and strings
array1: ["Item 1", "Item 2"]

array2:
  - "Item 1"
  - "Item 2"

string: >
  Some text might need to wrap over
  multiple lines because of it's length.
---

Night Owl uses gray‑matter to parse a file’s front‑matter, which supports YAML, JSON, JavaScript and TOML. YAML is the default option. You can specify other languages by adding the type after the first delimiter.

---toml
title = "TOML"
description = "This page uses TOML front-matter"
---

File-based routing

Night Owl decides where to generate files based on their location in your project.

When saving a template, the directory structure of the src directory is mirrored in dist. To create user‑friendly URLs, HTML templates are saved as index.html files in a sub-directory named after the file.

src dist url
/index.md /index.html /
/about.md /about/index.html /about/
/css/app.sass /css/app.css /css/app.css

Add a url in your template data to disable file‑based routing for any template.

Compile

When a template changes, it gets compiled into a list of pages, each with a render function. When a template dependency changes, all templates that depend on that file are compiled.

Render

After compiling any templates that have changed, Night Owl calls the render function of every template page and saves the new files to your dist directory.

Because collections are generated from templates, every template is rendered each time a file is changed. This ensures that all pages have updated collections data. Rendering is much faster than compiling, so the affect on build times is neglible.

Glob patterns

Glob patterns are strings that use special characters to identify multiple files or folders. Night Owl uses minimatch to check whether files match glob patterns.

export default {
  watch: [
    // Match all SVG files at the base of "src/assets"
    "src/assets/*.svg",

    // Match all SVG files in any subfolder of "src/assets"
    "src/assets/**/*.svg",

    // The path can also point to a specific file
    "src/assets/logo.svg",
  ]
}
Page data

This page was rendered with the following data.

{
  "layout": "_/layouts/docs",
  "menu": {...},
  "filters": {...},
  "helpers": {...},
  "version": "0.5.4",
  "github": "https://github.com/stephenhutchings/night-owl/",
  "npm": "https://www.npmjs.com/package/night-owl",
  "hash": "lmu1z5z4",
  "thumbnail": "https://night-owl.s-ings.com/assets/thumb.png",
  "isDev": false,
  "title": "Glossary",
  "description": "An overview of terms that Night Owl uses",
  "url": "/docs/more/glossary/",
  "meta": {
    "url": "/docs/more/glossary/",
    "src": "src/docs/05-more/01-glossary.md",
    "dist": "dist/docs/more/glossary/index.html",
    "collections": {
      "all": [...],
      "intro": [...],
      "commands": [...],
      "configuration": [...],
      "advanced": [...],
      "templates": [...]
    }
  },
  "content": "<p>This page lists some of the terms that are used throughout this site. Night O..."
}