Puzzle
Puzzle is a simple static sites generator which also provides the oportunity to use REST endpoints for your forms
(or any other type of endpoint you want to use)., (*1)
Uses Jigsaw to provide a template engine as Laravel's Blade
and compile the resources to a static site., (*2)
Uses Grunt to automate tasks providing an effortless development experience and optimal frontend., (*3)
Getting Started
Installing Globally
-
Install Puzzle globally via Composer:, (*4)
$ composer global require lordoffreaks/puzzle, (*5)
Make sure ~/.composer/vendor/bin is in your $PATH., (*6)
-
Initialize a new project:, (*7)
$ puzzle init my-site, (*8)
Installing Locally
If you run into dependency conflicts when trying to install Puzzle globally, you can always install it locally on a per site basis., (*9)
-
Create a folder for your site:, (*10)
$ mkdir my-site && cd my-site, (*11)
-
Install Puzzle via Composer:, (*12)
$ composer require lordoffreaks/puzzle, (*13)
-
Initialize a new project in the current folder:, (*14)
$ ./vendor/bin/puzzle init, (*15)
Building your first site
Building a Puzzle site is exactly like building a static HTML site, except that files ending in .blade.php will be rendered using Laravel's Blade Templating Language., (*16)
Build out your site however you like in the /source directory. It might look something like this:, (*17)
├─ source
│ ├─ _assets
│ ├─ _layouts
│ │ └─ master.blade.php
│ ├─ img
│ │ └─ logo.png
│ ├─ about-us.blade.php
│ └─ index.blade.php
└─ config.php
When you'd like to build it, run the build command from within your project root:, (*18)
$ puzzle build, (*19)
Your site will be built and placed in the /build_local directory by default., (*20)
Using the example structure above, you'd end up with something like this:, (*21)
├─ build_local
│ ├─ about-us
│ │ └─ index.html
│ ├─ img
│ │ └─ logo.png
│ └─ index.html
├─ source
└─ config.php
To quickly preview it, start a local PHP server:, (*22)
$ php -S localhost:8000/ -t build_local, (*23)
Layouts
One of the biggest benefits of a templating language is the ability to create reusable layouts., (*24)
Since it's important that a layout is never rendered on it's own, you need to be able to tell Jigsaw when a file shouldn't be rendered., (*25)
To prevent a file or folder from being rendered, simply prefix it with an underscore:, (*26)
├─ source
│ ├─ _layouts
│ │ └─ master.blade.php # Not rendered
│ └─ index.blade.php # Rendered
└─ config.php
Config variables
Anything you add to the array in config.php will be made available as a variable in your templates., (*27)
For example, if your config looks like this..., (*28)
return [
'contact_email' => 'support@example.com',
];
...you can use that variable in your templates like so:, (*29)
@extends('_layouts.master')
@section('content')
Contact us at {{ $contact_email }}, (*30)
@stop
Environments
You might have certain configuration variables that need to be different in different environments, like a Google Analytics tracking ID for example., (*31)
Puzzle lets you specify a different configuration file for each environment to handle this., (*32)
To create an environment-specific config file, just stick your environment name in front of the file extension:, (*33)
config.production.php, (*34)
To build your site for a specific environment, use the --env option:, (*35)
$ puzzle build --env=production, (*36)
Each environment gets it's own build_* folder, so in this case your site will be placed in build_production., (*37)
Note: Environment-specific config files are merged with the base config file, so you don't have to repeat values that don't need to change., (*38)
Pretty URLs
Puzzle will automatically take any Blade files not named index and render them as index.html in a subfolder with the same name as the original file., (*39)
For example, if you have a file named about-us.blade.php in your source directory:, (*40)
├─ source
├─ _layouts
├─ about-us.blade.php
└─ index.blade.php
...it will be rendered as index.html in the build/about-us directory:, (*41)
├─ build_local
├─ about-us
│ └─ index.html
└─ index.html
If you need to disable this behavior, use the --pretty=false option when building your site., (*42)
Wallogit.com
