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

#Build a site

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

deno run -A https://deno.land/x/ter/main.ts

Use --input and --output (or -i and -o) flags for custom source/destination directories:

deno run -A https://deno.land/x/ter/main.ts -i pages -o _dist

To start a local server with live refresh, pass the --serve (or -s) flag:

deno run -A https://deno.land/x/ter/main.ts -s

Run this to compile all .md files in the current directory to HTML (requires Deno to be installed):

deno run -A https://deno.land/x/ter/main.ts

• see usage for more details;
• goals for some thinking behind Ter's approach;
• or feel free to just roam around.

Made with Deno. Deno is fun. Contribute or submit issues: github.com/kkga/ter

Using Ter? Add your site!

deno run https://deno.land/x/ter/main.ts --help

Ter -- tiny wiki-style site builder

USAGE:
  ter [options]

OPTIONS:
  -i, --input     Source directory (default: .)
  -o, --output    Output directory (default: _site)
  -c, --config    Path to config file (default: .ter/config.json)
  -s, --serve     Serve locally and watch for changes (default: false)
  -d, --debug     Verbose output and statistics (default: false)
  --port          Serve port (default: 8000)
  --drafts        Render pages marked as drafts (default: false)`;

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

#Example

{
  "title": "Your Blog Name",
  "description": "I am writing about my experiences as a naval navel-gazer",
  "url": "https://example.com/",
  "rootCrumb": "index",
  "authorName": "Your Name Here",
  "authorEmail": "youremailaddress@example.com",
  "authorUrl": "https://example.com/about-me/",
  "lang": "en",
  "codeHighlight": true,
  "head": "<script src='https://microanalytics.io/js/script.js' id='XXXXXXXX'></script>"
}

Note: when using non-default input and output paths, 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 https://deno.land/x/ter/main.ts

#Output directory

_site

#Install command

curl -fsSL https://deno.land/x/install/install.sh | 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

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

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

    steps:
      - 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
        with:
          # Replace with the project name on Deno Deploy
          project: my-ter-site
          entrypoint: https://deno.land/std/http/file_server.ts
          # Change if using non-default output directory
          root: _site

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:

content
├── index.md
├── about-me.md
└── life
    ├── failed-startup-ideas.md
    └── thoughts-on-life.md

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

If a directory contains an index.md 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.

Items in the index are sorted in the following order:

1. files with pinned: true in the frontmatter are listed at the top;
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
tags:
  - myTag
  - otherTag
property: value
---

## My content

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

#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 https://deno.land/x/ter/main.ts --serve --drafts

#Dead internal links

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

If any of the following sounds relevant, Ter might be for you.

#Goals

• The filesystem is the navigation and organization method;
• Creating a new page (or section) should be as simple as creating a file (or directory);
• No bundled JavaScript -- it's just a bunch of hyperlinked documents, after all;
• Work out of the box, simplicity > customization.

#Use cases

• A published personal wiki;
• A collection of Zettelkasten notes;
• A simple blog;
• Software documentation (just like the one you're currently browsing).

If you're looking for a more flexible static site generator, try something like 11ty or Astro.

Below is a sample of GFM for previewing and testing purposes.

Text can be bold, italic, or strikethrough.

This is a normal paragraph. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

This is a blockquote. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Internal links look like this. External links look like this. Links to non-html files look like this.

#Header 1

This is a normal paragraph following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

#Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

#Header 3

This is a code block following a header.

#Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

#Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

#Header 6

Here is an unordered list:

• Salt-n-Pepa
• Bel Biv DeVoe
• Kid 'N Play

And an ordered list:

1. Michael Jackson
2. Michael Bolton
3. Michael Bublé

And an unordered task list:

• Create a sample markdown document
• Add task lists to it
• Take a vacation

And a "mixed" task list:

• Steal underpants
• ?
• Profit!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

There's a horizontal rule above and below this.

Definition lists can be used with HTML syntax.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should condense down and/or scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

var foo = "bar";

Code can also use syntax highlighting.

var foo = "bar";

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

var foo =
  "The same thing is true for code with syntax highlighting. A single line of code should horizontally scroll if it is really long.";

async function initializeFile(filePath: string, url: URL) {
  const fileResponse = await fetch(url).catch((err) => {
    console.log(`Can't fetch file: ${url}, Error: ${err}`);
    // Exit if we can't get the file
    Deno.exit(1);
  });
  if (fileResponse && fileResponse.body) {
    await ensureDir(dirname(filePath));
    const file = await Deno.open(filePath, {
      write: true,
      create: true,
    });
    const writableStream = writableStreamFromWriter(file);
    await fileResponse.body.pipeTo(writableStream);
  }
}

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The zettelkasten (German: "slip box", plural zettelkästen) is a system of note-taking and personal knowledge management used in research and study.

This post on the r/Zettelkasten subreddit has a great introduction to the system, but here's a short snippet:

The term comes from Niklaus Luhmann, a German autodidact and famously prolific academic sociologist. Similar techniques were developed independently by Nabokov and Prisig, among others.

Luhmann used a physical box of cards -- imagine an analog library card catalog. Most modern practitioners use digital slip-boxes. The core of the technique lies in a few simple principles:

• Write liberally about what you think and read. Write in detail so you can quickly re-internalize ideas after you forget them.
• Wherever you can, separate notes into small and distinct ideas.
• When you notice connections between ideas, encode them by writing references from one note to another.
• When you want to think or write, read your notes and follow the references between them.