Statamic Static Site Generator
Generate static sites with Statamic 3.
Installation
Install the package using Composer:
composer require statamic/ssg
If you want or need to customize the way the site is generated, you can do so by publishing and modifying the config file with the following command:
php artisan vendor:publish --provider="Statamic\StaticSite\ServiceProvider"
The config file will be in config/statamic/ssg.php. This is optional and you can do it anytime.
Usage
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.
Multiple Workers
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
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/*',
],
Dynamically adding routes
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'];
});
}
}
Post-generation callback
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
});
}
}
Triggering Command Failures
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'
Deployment Examples
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. e.g.php please ssg:generate && npm install && npm run prod). - Set publish directory
storage/app/static
After your site has an APP_URL...
- Set it as an environment variable. Add
APP_URLhttps://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]
S3 Asset Containers
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:
# .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.shand paste the code snippet below. - Run
chmod +x build.shon 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>
Code for build.sh
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
publicconfig in yourfirebase.jsonis set tostorage/app/static - (Optionally) Add a
predeployconfig to runphp please ssg:generate - Run
firebase deploy
7 Jul 11, 2022
13 Nov 10, 2022
16 Jul 7, 2022
3 Jul 19, 2022
2.2k Dec 28, 2022
1 Nov 1, 2021
80 Dec 31, 2022
248 Dec 26, 2022
393 Jan 2, 2023
471 Dec 31, 2022
2 Mar 29, 2022
52 Sep 6, 2022
1k Dec 16, 2022
13 Aug 17, 2022
31 Dec 29, 2022
8 Dec 6, 2022
3 Nov 19, 2021
2 Oct 20, 2021
72 Jul 18, 2022