____ _ ____ ____ ____ | _ \(_) ___ ___/ ___/ ___| / ___| | |_) | |/ __/ _ \___ \___ \| | _ | __/| | (_| (_) |__) |__) | |_| | |_| |_|\___\___/____/____/ \____|

Installation Guide

Getting started with PicoSSG is quick and easy. This guide will walk you through the installation process and set you up to create your first static site.

Prerequisites

Before installing PicoSSG, you'll need:

You can verify you have the right versions installed by running:

node --version; npm --version

Installation Methods

There are two main ways to use PicoSSG:

1. Use with npx (Recommended for First-Time Users)

The simplest way to use PicoSSG without installing it globally is with npx, which comes with npm:

npx @wolframkriesing/picossg -c content -o output

This command runs PicoSSG, processing files from the content directory into the output directory. Running the command will maybe create very detailed output like this, when it works:

> npx @wolframkriesing/picossg -c content -o output

🎬 Building with config: {
    "contentDir": "content",
    "outDir": "output",
    "configFile": "_config.js"
}
✅  Loaded njk custom filters from:
    /xxxxx/content/_njk-custom/filters.js
    1 custom njk filters loaded: slug
✅  Loaded user functions from:
    /xxxxx/content/_config.js

💾 Copy style.css => output/style.css ✅ 
⏭️ Preprocessing done.
⚙️ Process index.html.md.njk, 3.72 kB, .njk👍🏾.md👍🏾 layout: _base.njk👍🏾
⚙️ Process components/index.html.md, 8.05 kB, .md👍🏾 layout: _base.njk👍🏾
⚙️ Process custom-filters/index.html.md, 5.99 kB, .md👍🏾 layout: _base.njk👍🏾
⚙️ Process diagrams/index.html.md, 5.46 kB, .md👍🏾 layout: _base.njk👍🏾
⚙️ Process file-mapping/index.html.md, 4.00 kB, .md👍🏾 layout: _base.njk👍🏾
✅  index.html.md.njk => index.html 9.00 kB
✅  components/index.html.md => components/index.html 15.05 kB
✅  custom-filters/index.html.md => custom-filters/index.html 11.31 kB
✅  diagrams/index.html.md => diagrams/index.html 10.10 kB
✅  file-mapping/index.html.md => file-mapping/index.html 9.38 kB

⏱️ Processed 5 files in 0.04 seconds.

2. Project-Based Installation (Recommended for Projects)

For ongoing projects, it's better to set up PicoSSG as a project dependency:

  1. Create a new directory for your project and navigate into it:
mkdir my-ssg-site
cd my-ssg-site
  1. Initialize a new npm project (or skip if you already have a package.json):
npm init -y
  1. Create a basic project structure:
mkdir content
  1. Add PicoSSG scripts to your package.json:
{
  "name": "my-ssg-site",
  "version": "1.0.0",
  "scripts": {
    "build": "npx @wolframkriesing/picossg -c content -o output",
    "start": "npx http-server output -p 8000",
    "build:watch": "npx nodemon --quiet --legacy-watch --watch content --ext '*' --exec \"bash -c 'npm run build'\""
  }
}

With this setup, you can:

Command Line Options

PicoSSG supports the following command line options:

Option Short Description
--content -c Source directory (required)
--out -o Output directory (required)
--config -x Config file name (default: _config.js)
--help -h Show help message

Example usage:

npx @wolframkriesing/picossg -c content -o output -x _custom-config.js

Next Steps

Now that you have PicoSSG installed, you're ready to start building your site: