pagery

Opinionated static site generator

What is pagery?

pagery is my personal static site generator, primarily to be used with Cloudflare Pages. Be aware: it is an extremely opinionated tool, using my really niche stack. I wrote this for myself but maybe someone else can see the benefits in the simplicity of my stack. Plus it's got some cool features.

The stack

| Tool | Use | | :--: | :-: | | Pug | HTML templating | | Tailwind CSS | Page styling | | PostCSS | CSS processing | | JSON | Structured data |

Features

• Super-simple templating
• Compatible with Cloudflare Pages (or any other JAMstack host)
• Iteratively generate pages from JSON
• Included PostCSS plugins:
  • autoprefixer
  • cssnano
  • @tinycreek/postcss-font-magician

Installation

npx pagery is the suggested way to use pagery. Alternatively, you can explicitly install it:

npm i -g pagery

# or, per project
npm i pagery

If you install per project, I suggest including this script in your package.json:

{
    "scripts": {
        "pagery": "node ./node_modules/pagery/dist/pagery.js"
    },
    // ...
}

Then run it with npm run pagery.

It is recommended to be using at least Node 20 and NPM 10.

Usage

Step 1: Setup Tailwind

Create two new files, tailwind.config.js and tailwind.css in the root of your project. See Tailwind CSS docs: Configuration for tailwind.config.js. You may also use a .ts, check Tailwind docs for more info.

Add the following to tailwind.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

It is highly recommended to use Tailwind @layer directives to organize your CSS and avoid specificity issues.

Multiple Tailwind configurations

As of Tailwind v3.2, you are able to use multiple config files in one project. Reference Tailwinds documentation for more information.

Step 2: Setup Pug

Create a views directory in the root of your project. This is where all of your Pug files will go. At least one .pug file is required for compilation to work.

Loading the CSS

You can use CSS by either referencing the static CSS files generated by Pagery, or if you opt to disable that, the inline css variable as follows within a Pug file:

style
    != css

This will include the compiled CSS in the <style> tag.

Multiple CSS files

See information below on passing multiple CSS files to Pagery. To use them in your Pug files, you would do the following:

style
    != css.main

//- or

style
    != css.admin

The item names correspond to the filenames of the CSS files.

Using Tailwind classes

Tailwind classes are available in the Pug files. For example, to create a button with a red background and white text, you would do the following:

button.bg-red-500.text-white(onclick='alert("Hello world!")') Click me!

Tailwind uses : by default to indicate modifiers. This is a problem in Pug, so it's recommended to do the following:

// tailwind.config.js
module.exports = {
    separator: '_',
    // ...
}

button.bg-red_500.text-white.hover_bg-red-700(onclick='alert("Hello world!")') Click me!

See Tailwind docs for Separator for more information.

Some Tailwind classes use / for fractional values. This is also a problem in Pug, so it's recommended to do the following:

button.bg-red-500.text-white.hover_bg-red-700(class='w-1/2' onclick='alert("Hello world!")') Click me!

Using data

You can pass data to your Pug files by using the --data option. You can pass multiple files by separating them with a comma. For example:

pagery --data=foo.json,bar.json

The data will be available in the Pug files as the data variable. The data object is in the format of data.[filename].[key]. For example, if you have a foo.json file with the following contents:

{
    "bar": "baz"
}

You can access it in your Pug files like this:

p= data.foo.bar

Your HTML would render as:

<p>baz</p>

Step 3: Run pagery

Once the project is setup, you can run pagery with the following command:

pagery

This will compile your Pug files into HTML in the html/ directory.

Options

| Option | Description | Default | |--------|-------------|---------| | config | Use a config file instead of CLI parameters | null | | views | Directory where your Pug files are located | views/ | | output | Directory where the compiled HTML files will be placed | html/ | | tailwindFile | Path to your Tailwind CSS file(s) | tailwind.css | | tailwindConfigFile | Path to your Tailwind config file | tailwind.config.js/.ts | | outputCss | Save compiled CSS to file | true | | dir | Directory to run pagery in | ./ | | data | Path to JSON file(s) containing data to pass to Pug files | null | | exclude | Comma-separated list of Pug files or directories to exclude from the output | null | | only | Comma-separated list of Pug files to explicity render | null |

All options can be set on the command line (for example, --output=static/), in a JSON config file (must be referenced using --config=file.json), or when used as a JS module.

Example:

pagery --views=pug/ --output=public/ --dir=website/
# or
pagery --dir=public/ --data=language.json --tailwindFile=css/main.css,css/admin.css

Using a config file

By specifying the --config flag, as well as a .json file, pagery will ignore all other command line options and instead use the options specified in the config file.

The config file supports all the same options as the command line, except for --config itself. For example:

{
    "views": "pug/",
    "output": "public/",
    "dir": "website/",
    "data": "language.json",
    "tailwindFile": "css/main.css,css/admin.css"
}

This would be the same as running:

npm run pagery --views=pug/ --output=public/ --dir=website/ --data=language.json --tailwindFile=css/main.css,css/admin.css

Importing as a module

You can also import pagery as a module and use it in your own scripts for dynamic server-side rendering. For example:

const { generate } = require('pagery');

generate({
    views: 'pug/',
    output: 'public/',
    dir: 'website/',
    data: 'language.json',
    tailwindFile: 'css/main.css,css/admin.css'
})
    .then((data) => {
        console.log(`HTML files: ${Object.keys(data.pug).length}`);
        console.log(`CSS files: ${data.css instanceof Array ? data.css.length : 1}`);
    })
    .catch((err) => console.error(err));

Iteration Generation

You can use an Iteration file to quickly build many pages from a single template and JSON data.

An Iteration file is indicated to pagery using [].pug. For example, [recipes].pug would generate multiple pages using data contained in the recipes.json file. You must also specify any iteration data files with the data option (i.e. --data=recipes.json).

By default, pagery will use the "data" property in the JSON file. If you have multiple top-level properties or want to use something other than "data", you may specify so using commas. For example, using [recipes,breakfast].pug would use the recipes.json data file, but generating with data from the "breakfast" property. You may also use nested properties, such as [recipes,breakfast,drinks].pug. A sample recipes.json may look like this:

{
    "breakfast": {
        "drinks": {
            "hot-chocolate": {
                ...
            },
            "chai-latte": {
                ...
            }
        },
        "eggs": {
            "fried": {
                ...
            }
        }
    },
    "lunch": {
        ...
    }
}

The data provided to an Iteration must be in Object form: the Object key becomes the filename and the value is passed to the template for that specific step of the Iteration. In the last example, hot-chocolate.html and chai-latte.html would be generated by the Iteration file.

License

Licensed under ISC

Copyright (c) 2023 tycrek