How to use and configure Ter.

  1. 1Quick start
  2. 2Command line usage
  3. 3Configuration
  4. 4Content
  5. 5Deploy

Quick start  #

Install deno  #

Ter is built with Deno, so you’ll need to have it installed.

Build a site  #

This command will recursively search for *.md files in the current directory and generate a site into the _site directory:

deno run -A --unstable

Use --input/--output flags for custom source/destination directories:

deno run -A --unstable --input pages --output _dist

To start a local server with live refresh, pass the --serve flag:

deno run -A --unstable --serve

Command line usage  #

Run Ter with the --help flag to see usage reference.

deno run --help
Ter -- tiny wiki-style site builder

  ter [options]

  --input     Source directory (default: .)
  --output    Output directory (default: _site)
  --config    Path to config file (default: .ter/config.json)
  --serve     Serve locally and watch for changes (default: false)
  --port      Serve port (default: 8080)
  --drafts    Render pages marked as drafts (default: false)
  --debug     Verbose output and statistics (default: false)

Configuration  #

Ter reads a JSON configuration file at .ter/config.json before building a site.

Alternative location can be specified with with the --config CLI flag. If the file does not exist, Ter will create it with default options on first build.

Options  #

Key Description
title Title of your site.
description Description of your site.
url Published URL address of your site.
rootCrumb Label used for root crumb label (default: “index”).
authorName Your name.
authorEmail Your email.
authorUrl Your home page.
lang Optional. Locale used for formatting dates.
navLinks Optional. Object of navigation links in form of {label: path, ...}.
codeHighlight Optional. Use syntax highlighting in code blocks (default: false).
head Optional. String to inject at the bottom of <head> tag.

Example  #

  "title": "Your Blog Name",
  "description": "I am writing about my experiences as a naval navel-gazer",
  "url": "",
  "rootCrumb": "index",
  "authorName": "Your Name Here",
  "authorEmail": "",
  "authorUrl": "",
  "lang": "en",
  "navLinks": { "about": "/about", "contact": "/contact" },
  "codeHighlight": true,
  "head": "<script src='' id='XXXXXXXX'></script>"

Content  #

Index pages  #

Ter recursively recreates the source file system on the rendered site and each directory gets an index file listing its content. For example, if the source looks like this:

└── life

… the life directory will get an life/index.html page with an index of its content.

If a directory contains an file, its content will be injected into the rendered index.html above the index list. This can be useful for describing what the directory content is about or calling out individual pages.

Index sorting  #

Items in the index are sorted in the following order:

  1. files with pinned: true in the frontmatter are listed at the top and get an ★ symbol;
  2. directories (child index pages);
  3. rest of markdown files, sorted by date.

Markdown frontmatter  #

Ter extracts YAML frontmatter delimited by --- from markdown files. Here’s an example:

title: My page
description: Here’s my description
date: 2022-01-29
  - myTag
  - otherTag
property: value

## My content

Some properties are utilized when building a site. All of them are optional.

Property Default Description
title page title
description page description
tags page tags
date page publish date in YYYY-MM-DD format
dateUpdated page last update date in YYYY-MM-DD format
pinned false page is listed at the top of index lists
unlisted false page is excluded from all index lists
draft false file is ignored during site generation
log false if set on an index page (, all child pages are rendered inline
toc false affects rending of table of contents
showHeader true affects rendering of page header with title, description, date and tags
showTitle true affects rendering of page title
showDescription true affects rendering of page description
showMeta true affects rendering of page date and tags

Ignoring files  #

Any files and folders that start with an _ or . (hidden) are ignored. For example, if there is a _drafts folder in the content directory, it will be skipped during site generation.

In addition, any markdown file with draft: true in the frontmatter will be ignored. To render files with draft: true, pass --drafts flag to the main command. For example:

deno run -A --unstable --serve --drafts

Ter automatically finds non-working internal links and lets you know about them after building a site. Here’s an example output:

Dead links:
/overview -> /non-existent-page-name
/overview -> /some-dead-link

Deploy  #

Ter generates a static site which can be deployed anywhere.

Note If using non-default input and output folders, update the build command and output directory accordingly.

Vercel  #

To deploy on Vercel, use the following build and output configuration.

Build command  #

deno run -A --unstable

Output directory  #


Install command  #

curl -fsSL | DENO_INSTALL=/usr/local sh

Deno Deploy  #

For Deno Deploy, we can use a GitHub Action to automatically build the site and then deploy it with Deno’s deployctl.

Firstly, create a new project on Deno Deploy. Select “Deploy from GitHub”, link the repository, and use the production branch. For deployment mode, select “GitHub Actions”.

Next, create a .github/workflows/deno-deploy.yml file in the repository and make changes according to your setup.

GitHub Action (deno-deploy.yml)  #

name: Deploy to Deno Deploy

    # Change if using a different production branch
    branches: [ main ]
    branches: [ main ]

    name: Deploy
    runs-on: ubuntu-latest
      id-token: write
      contents: read

      - name: Clone repository
        uses: actions/checkout@v3

      - name: Setup Deno
        uses: denoland/setup-deno@v1.1.0

      - name: Build site
        # Change if using non-default input/output directories
        run: deno run -A --unstable main.ts

      - name: Deploy to Deno Deploy
        uses: denoland/deployctl@v1
          # Replace with the project name on Deno Deploy
          project: my-ter-site
          # Change if using non-default output directory
          root: _site