Advanced site configuration
611 words, 4-minute read
The site build is configured by the publican.config.js file. It contains JavaScript code to:
- load and parse values set in the
.env.devand.env.prodconfiguration files - modify page slugs to remove the initial number or date
- set the number of pages and sort order for directory and tag index pages
- copy static files such as images and icons
- run event hook functions to examine and modify data
- append custom global values and functions to the
tacsobject - define replacement strings such as
−−ROOT−− - minify HTML in production mode
- clean the build directory
- start the build
- watch for file changes in development mode
- start a development mode server
You can add your own Publican customisations as necessary.
Function libraries #
The theme provides the following code libraries in the lib directory.
hooks.js #
This exports two functions:
processFileDate()extracts the post date from its filenamepostrenderMeta()adds aPublicangenerator meta tag to the HTML<head>
publican.config.js imports and uses these as event hook functions:
import * as fnHooks from './lib/hooks.js';
// determine post date from filename
publican.config.processContent.add( fnHooks.processFileDate );
// processPostRender hook: add <meta> tags
publican.config.processPostRender.add( fnHooks.postrenderMeta );
format.js #
This provides a number of formatting functions such as:
number()– displays a date in a readable format for the default localedateHuman()– displays a date in a readable format for the default localerss()– cleans HTML content and adds fully-qualified URLs for the RSS feed defined insrc/content/feed.xml
publican.config.js imports and appends these functions to the tacs object:
import * as fnFormat from './lib/format.js';
// jsTACS functions
tacs.fn = tacs.fn || {};
tacs.fn.format = fnFormat;
Therefore, templates can format dates and numbers, e.g.
<ul>
<li>Post written on ${ tacs.fn.format.dateHuman( data.date ) }</li>
<li>${ tacs.fn.format.number( data.wordCount ) } words</li>
<ul>
To render:
- Post written on April 7, 2025
- 1,234 words
nav.js #
This exports three functions:
mainMenu()creates the menu in the page header by examining the top-level pages in the globaltacs.navobjectbreadcrumb()creates a breadcrumb trail to the current page (shown above the page title) using the globaltacs.navobjectpagination()formats the list of pages (back, 1, 2, 3, …, next) shown on directory and tag indexes by examining thedata.paginationobject.
These are complex and would be cumbersome to create in ${ expressions } alone. publican.config.js imports and appends these functions to the tacs object:
import * as fnNav from './lib/nav.js';
// jsTACS functions
tacs.fn = tacs.fn || {};
tacs.fn.nav = fnNav;
The main menu can therefore be added to a template using code such as:
<nav class="menu">
${ tacs.fn.nav.menuMain( data.link ) }
</nav>