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 the statamic/ssg
package via Composer, optionally publish the configuration file and prompt you if you wish to install the spatie/fork
package for running multiple workers.
Run the following command:
php please ssg:generate
Your site will be generated into a directory which you can deploy however you like. See Deployment Examples below for inspiration.
For improved performance, you may spread the page generation across multiple workers. This requires Spatie's Fork 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/fork
php 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 the urls
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 the urls
config.
'exclude' => [
'/secret-page',
'/cheat-codes/*',
],
You may add URLs dynamically by providing a closure that returns an array to the addUrls
method.
use Statamic\StaticSite\SSG;
class AppServiceProvider extends Provider
{
public function boot()
{
SSG::addUrls(function () {
return ['/one', '/two'];
});
}
}
Wherever pagination is detected in your antlers templates (eg. if you use the paginate
param on the collection
tag), multiple pages will automatically be generated with /articles/page/2
style urls.
You may configure a custom routing style in config/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.
use Statamic\StaticSite\SSG;
class AppServiceProvider extends Provider
{
public function boot()
{
SSG::after(function () {
// eg. copy directory to some server
});
}
}
The default configuration of Statamic is to have Glide use "dynamic" images, which means that the glide
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 the img
directory whenever glide
tags are used. This is essentially Glide's custom static path option.
You can customize where the images will be generated:
'glide' => [
'directory' => 'images',
],
If you are using a custom 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);
// or
app('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 content locally and not using the control panel in production.
Deploy to Netlify
Deployments are triggered by committing to Git and pushing to GitHub.
- Create a site in your Netlify account
- Link the site to your desired GitHub repository
- Add build command
php 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. e.g.npm install && npm run build && php please ssg:generate
). - Set publish directory
storage/app/static
After your site has an APP_URL...
- Set it as an environment variable. Add
APP_URL
https://thats-numberwang-47392.netlify.com
Finally, generate an APP_KEY
to your .env file locally using php artisan key:generate
and copy it's value, then...
- Set it as an environment variable. Add
APP_KEY
[your app key value]
If you are storing your assets in an S3 bucket, the .env
s 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:
# .env
AWS_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 your s3
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'),
],
Deploy to Vercel
Deployments are triggered by committing to Git and pushing to GitHub.
- Create a new file called
./build.sh
and paste the code snippet below. - Run
chmod +x build.sh
on your terminal to make sure the file can be executed when deploying. - Import a new site in your Vercel account
- Link the site to your desired GitHub repository
- Add build command
./build.sh
- Set output directory to
storage/app/static
- Add environment variable in your project settings:
APP_KEY
<copy & paste from dev>
Add the following snippet to build.sh
file to install PHP, Composer, and run the ssg:generate
command:
#!/bin/sh
# Install PHP & WGET
yum install -y amazon-linux-extras
amazon-linux-extras enable php7.4
yum clean metadata
yum install php php-{common,curl,mbstring,gd,gettext,bcmath,json,xml,fpm,intl,zip,imap}
yum install wget
# INSTALL COMPOSER
EXPECTED_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 1
fi
php composer-setup.php --quiet
rm composer-setup.php
# INSTALL COMPOSER DEPENDENCIES
php composer.phar install
# GENERATE APP KEY
php artisan key:generate
# BUILD STATIC SITE
php please ssg:generate
Deploy to Surge
Prerequisite: Install with npm install --global surge
. Your first deployment will involve creating an account via command line.
- Build with command
php please ssg:generate
- Deploy with
surge storage/app/static
Deploy to Firebase hosting
Prerequisite: Follow the instructions to get started with Firebase hosting
- Once hosting is set up, make sure the
public
config in yourfirebase.json
is set tostorage/app/static
- (Optionally) Add a
predeploy
config to runphp please ssg:generate
- Run
firebase deploy