Publican core concepts

Publican is a Node.js static site generator. It builds web pages from:

1. content
2. templates, and
3. a JavaScript configuration file.

Download the basic theme to examine and adapt for your own site.

Content #

By default, Publican looks for text-based content files in src/content/.

Markdown(.md) is a practical format for articles (including this one), but Publican can process HTML, XML, TXT, SVG or other other text file.

Front matter #

Any content file can have front matter values at the top. This defines meta data such as the title, date, and tags. Some values control how Publican works and you can define custom values such as a description, author, image, etc.

index.md example

---
title: My first post
description: This is the first post I wrote in my Publican site.
date: 2025-01-31
tags: HTML, CSS, JavaScript
---

This is my **page content**.

Directory indexes #

Publican presumes directories directly under src/content/ contain specific types of content. For example:

• docs/ contains documentation
• post/ contains blog posts
• about/ contains person/organization information.

(Sub-directories of these are presumed to have the same type of content.)

Publican generates paginated directory index pages which can be configured and presented in different ways.

Tag indexes #

Front matter can specify tags – key words associated with the content:

tags: HTML, CSS, JavaScript

Publican generates paginated tag index pages linking to pages that use those tags. These can be configured and presented in different ways.

Media files #

Media and other static files can be copied directly to the website build directory without modification.

Templates #

By default, Publican looks for text-based template files in src/template/. Most templates will be HTML files that Publican slots content into to create web pages.

jsTACS template engine #

Publican uses jsTACS as its templating engine. It parses standard JavaScript ${ expression } template literals. For example, <h1>${ data.title }</h1> slots a (front matter) title into a heading.

Configuration #

Publican is configured and launched from a publican.config.js file. Three lines of code is required:

publican.config.js

// imports
import { Publican } from 'publican';

// create Publican object
const publican = new Publican();

// build site
await publican.build();

but you can also define:

• options such as directories, page sorting, and pagination
• global values that used across all pages, and
• advanced options such as string replacement and event functions.

Build #

The site is built to a default build/ directory when you execute the configuration file:

terminal

node ./publican.config.js

This creates a production build which omits draft and future-dated content. You can create a development build that includes all content by setting the NODE_ENV environment variable to development before running Publican.

Note you will require a local development server to view your site.