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.

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 but you can define custom values such as a description, author, image, etc.

index.md example

---
title: My first post
description: The first post I wrote in my Publican site.
date: 2025-01-23
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. It defines:

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

Build #

The site is built to your project’s default build/ directory when you run:

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.