Repository files navigation

Generate static sites with Statamic.

You can install the Static Site Generator package with the following command:

php please install:ssg

The command will install thestatamic/ssg package via Composer, optionally publish the configuration file and prompt you if you wish to install thespatie/fork package for runningmultiple workers.

Run the following command:

php please ssg:generate

Your site will be generated into a directory which you can deploy however you like. SeeDeployment Examples below for inspiration.

For improved performance, you may spread the page generation across multiple workers. This requires Spatie'sFork package. Then you may specify how many workers are to be used. You can use as many workers as you have CPU cores.

composer require spatie/forkphp please ssg:generate --workers=4

Routes will not automatically be generated. You can add any additional URLs you wish to be generated by adding them to theurls array in the config file.

'urls' => ['/this-route','/that-route',],

You can also exclude single routes, or route groups with wildcards. This will override anything in theurls config.

'exclude' => ['/secret-page','/cheat-codes/*',],

You may add URLs dynamically by providing a closure that returns an array to theaddUrls method.

useStatamic\StaticSite\SSG;class AppServiceProviderextends Provider{publicfunctionboot()    {SSG::addUrls(function () {return ['/one','/two'];        });    }}

Wherever pagination is detected in your antlers templates (eg. if you use thepaginate param on thecollection tag), multiple pages will automatically be generated with/articles/page/2 style urls.

You may configure a custom routing style inconfig/statamic/ssg.php:

'pagination_route' =>'{url}/{page_name}/{page_number}',

You may optionally define extra steps to be executed after the site has been generated.

useStatamic\StaticSite\SSG;class AppServiceProviderextends Provider{publicfunctionboot()    {SSG::after(function () {// eg. copy directory to some server        });    }}

The default configuration of Statamic is to have Glide use "dynamic" images, which means that theglide tag will only output URLs. The images themselves will be generated when the URLs are visited. For a static site, this no longer makes sense since it will typically be deployed somewhere where there is no dynamic Glide route available.

By default, the SSG will automatically reconfigure Glide to generate images into theimg directory wheneverglide tags are used. This is essentially Glide'scustom static path option.

You can customize where the images will be generated:

'glide' => ['directory' =>'images',],

If you are using acustom glide disk, you can tell the SSG to leave it alone:

'glide' => ['override' =>false,],

And then copy the images over (or create a symlink) after generating has completed:

SSG::after(function () {$from =public_path('img');$to =config('statamic.ssg.destination').'/img';app('files')->copyDirectory($from,$to);// orapp('files')->link($from,$to);});

If you are using the SSG in a CI environment, you may want to prevent the command from succeeding if any pages aren't generated (e.g. to prevent deployment of an incomplete site).

By default, the command will finish and exit with a success code even if there were un-generated pages. You can tell configure the SSG to fail early on errors, or even on warnings.

'failures' =>'errors',// or 'warnings'

These examples assume your workflow will be to author contentlocally andnot using the control panel in production.

Deployments are triggered by committing to Git and pushing to GitHub.

• Create a site in yourNetlify account
• Link the site to your desired GitHub repository
• Set build command tophp please ssg:generate
  • If you need to compile css/js, be sure to add that command too and execute it before generating the static site folder
  • ie.npm install && npm run build && php please ssg:generate
• Set publish directory tostorage/app/static
• AddAPP_KEY env variable, by runningphp artisan key:generate locally, and copying from your.env
  • ie.APP_KEYyour-app-key-value
• AddAPP_URL environment variable after your site has a configured domain
  • ie.APP_URLhttps://thats-numberwang-47392.netlify.com

If you are storing your assets in an S3 bucket, the.envs used will need to be different to the defaults that come with Laravel, as they are reserved by Netlify. For example, you can amend them to the following:

# .envAWS_S3_ACCESS_KEY_ID=AWS_S3_SECRET_ACCESS_KEY=AWS_S3_DEFAULT_REGION=AWS_S3_BUCKET=AWS_URL=

Be sure to also update these in yours3 disk configuration:

// config/filesystems.php's3' => ['driver' =>'s3','key' =>env('AWS_S3_ACCESS_KEY_ID'),'secret' =>env('AWS_S3_SECRET_ACCESS_KEY'),'region' =>env('AWS_S3_DEFAULT_REGION'),'bucket' =>env('AWS_S3_BUCKET'),'url' =>env('AWS_URL'),],

Deployments are triggered by committing to Git and pushing to GitHub.

• Create a new filebuild.sh file in your project and paste from theexample code snippet below
• Runchmod +x build.sh on your terminal to make sure the file can be executed when deploying
• Import a new site in yourVercel account
• Link the site to your desired GitHub repository
• Set build command to./build.sh
• Set output directory tostorage/app/static
• AddAPP_KEY env variable, by runningphp artisan key:generate locally, and copying from your.env
  • ie.APP_KEYyour-app-key-value
• AddAPP_URL environment variable after your site has a configured domain
  • ie.APP_URLhttps://thats-numberwang-47392.vercel.app

Add the following snippet tobuild.sh file to install PHP, Composer, and run thessg:generate command:

#!/bin/sh# Install PHP & WGETdnf clean metadatadnf install -y php8.2 php8.2-{common,mbstring,gd,bcmath,xml,fpm,intl,zip}dnf install -y wget# INSTALL COMPOSEREXPECTED_CHECKSUM="$(wget -q -O - https://composer.github.io/installer.sig)"php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"ACTUAL_CHECKSUM="$(php -r "echo hash_file('sha384', 'composer-setup.php');")"if [ "$EXPECTED_CHECKSUM" != "$ACTUAL_CHECKSUM" ]then    >&2 echo 'ERROR: Invalid installer checksum'    rm composer-setup.php    exit 1fiphp composer-setup.php --quietrm composer-setup.php# INSTALL COMPOSER DEPENDENCIESphp composer.phar install# GENERATE APP KEYphp artisan key:generate# BUILD STATIC SITEphp please stache:warm -n -qphp please ssg:generate

Prerequisite: Install withnpm install --global surge. Your first deployment will involve creating an account via command line.

• Build with commandphp please ssg:generate
• Deploy withsurge storage/app/static

Prerequisite: Follow the instructions toget started with Firebase hosting

• Once hosting is set up, make sure thepublic config in yourfirebase.json is set tostorage/app/static
• (Optionally) Add apredeploy config to runphp please ssg:generate
• Runfirebase deploy