Publican content

Publican content files define the main content of a page. They would not normally define content such as page headers, footers, and navigation blocks which typically reside in templates.

Example content #

Content files can contain markdown, HTML, or any other text format.

#index.md example

---
title: My first Publican site
menu: Home
description: The home page of my static site.
author: Craig Buckler
date: 2025-01-23
priority: 1
tags: Publican, SSG
---

This is my new static site built with [Publican](https://publican.dev/).

It was written on ${ data.date } by ${ data.author }
and has ${ data.wordCount } words.

## Updates coming

This site is *under construction!*

Front matter #

The top lines between --- delimiters is front matter name: value pairs. These define meta data about the content that can be used in in templates, the content, or even within other front matter fields.

Some front matter values are used by Publican to control the build (title, menu, slug, date, publish etc.), but you can add your own values.

Front matter can be added to any file, e.g.

src/content/contact.html

---
title: Contact us
email: helpdesk@site.com
---

<p>Contact us at <a href="mailto:${ data.email }">${ data.email }</a></p>

The primary content follows the closing front matter delimiter. Markdown is converted to HTML during the build. Other types of file content such as HTML or TXT are not changed (other than removing the front matter block).

Any file can use ${ expression } template literals to output page data or global tacs values.

Markdown #

Publican supports markdown for content. It’s a simple format which can be transformed to clean HTML. The following resources can help you get started with markdown:

• Daring Fireball markdown
• markdownguide.org basics
• markdownguide.org extended
• Markdown reference

You can configure the markdown to HTML conversion options in publican.config.js.

Template literal ${ expressions } can be included in markdown, but refer to the jsTACS notes and options.

Content file location #

Create content files in src/content/ unless you set an alternative directory in publican.config.js, e.g.

publican.config.js

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

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

// alternative content location
publican.config.dir.content = './my-content/';

// build site
await publican.build();

Directory structure #

A content file’s location determines its full path in the built web site (the slug). Examples:

The default slug definition rules:

• The characters #, !, $, ^, ~, and space are removed.

• All letters are converted to lower case.

• .md and .html files are web page content – they will always result in a slug ending index.html in a specific directory. This creates friendlier URLs such as mysite.com/post/my-post/ rather than mysite.com/post/my-post.html.

Publican shows an error and aborts when slugs clash.

Ignored content files #

Filenames beginning with an underscore (_) are ignored (the rule is configurable). This can be useful if you are creating notes or content that you do not want in the built site.

Custom slugs #

The front matter slug value overrides the generated slug value.

src/content/post/my-post.md

---
title: A new post
menu: New post
date: 2025-01-23
slug: post/2025/my-post.html
---

Content coming soon.

The page will be built to build/post/2025/my-post.html rather than build/post/my-post/index.html.

Slug string replacement #

You can define any number of slug search and replace values in the publican.config.slugReplace Map object. Search values can be strings or regular expressions.

The following example removes two or more digits followed by an underscore and changes .html extensions to .htm:

publican.config.js excerpt

// slug replacement - removes NN_
publican.config.slugReplace.set(/\d{2,}_/g, '');

// slug replacement - rename .html to .htm
publican.config.slugReplace.set('.html', '.htm');

Virtual content files #

Content can also be passed to Publican as a string in the configuration file. This may be useful if you are retrieving data from a Content Management System API rather than using the file system.

To add virtual content, call:

publican.addContent( <filename>, <content> );

prior to running the build process (await publican.build();).

The filename follows the directory structure rules and determines the type of content. For example, to add a markdown page:

publican.config.js

publican.addContent(
  'article/virtual-post.md', `
---
title: Virtual post
---
This is a virtual post!
`);