Staticka is yet another static site generator written in PHP. It uses Markdown format for the content files and the Laravel Blade or Twig engine for managing the view files. It is also written using Slytherin.
Via Composer
$ composer require rougin/staticka illuminate/bladeNOTE: Laravel Blade is only available in PHP v5.4.0 and later. For PHP v5.3.0, you can use Twig as a replacement (twig/twig) or the Renderer instance (the default one) from Slytherin.
- Preparation
- Building
- Customization
- Watch file/s for changes
- Run scripts before or after building
- Helpers
- Filters
- Integrations
To generate a simple static site, you must have at least this file structure:
static-site/
├── content/
│ └── hello-world.md
├── views/
│ └── index.blade.php
└── routes.php
The contents of the routes.php file must return an array of Rougin\Staticka\Route instances:
routes.php
$routes = array();
array_push($routes, new Rougin\Staticka\Route('/', 'hello-world'));
array_push($routes, new Rougin\Staticka\Route('/hello-world', 'hello-world'));
return $routes;There is a third parameter in the Route class wherein you could specify the view it should use.
It maps to the index file by default (the index.blade.php) from the views directory.
NOTE: / is a special character that means it is the landing page of the site.
To build your static site, you need to run this command:
$ vendor/bin/staticka build --site="static-site" --path="static-site/build"After running the command, it will render all routes listed in routes.php and it should look like this:
static-site/
└── build/
│ ├── hello-world/
│ │ └── index.html
│ └── index.html
└── content/
--site- path of the source files. If not specified, it will use the current working directory as its default.--path- path on which the static files will be built. If not defined, the current working directory or the--site+builddirectory (if specified) will be used.
To customize the directory structure of the static site, add a file named staticka.php to specify the paths of the required files/directories and its other settings. The settings specified below will be discussed later.
staticka.php
return array(
/**
* Directory path for the configurations.
*
* @var array|string
*/
'config' => __DIR__ . '/config',
/**
* Directory path for the contents.
*
* @var string
*/
'content' => __DIR__ . '/content',
/**
* Directory path for the views.
*
* @var string
*/
'views' => __DIR__ . '/source/views',
/**
* A listing of available routes.
*
* @var array|string
*/
'routes' => __DIR__ . '/routes.php',
/**
* Looks for file changes from the specified directories.
*
* @var array
*/
'watch' => array(),
/**
* Scripts needed to be run before or after the building.
*
* @var array
*/
'scripts' => array('before' => '', 'after' => ''),
/**
* Returns a listing of helpers to be used in the view files.
*
* @var array
*/
'filters' => array(
'url' => 'Rougin\Staticka\Helper\UrlHelper',
),
/**
* Returns a listing of integrations to be used.
*
* @var array
*/
'integrations' => array(
'Rougin\Staticka\Content\MarkdownIntegration',
'Rougin\Staticka\Helper\HelperIntegration',
'Rougin\Staticka\Renderer\RendererIntegration',
),
);NOTE: You could also define an array of Route instances in the routes key of staticka.php instead on specifying it to a routes.php file. You can do also the same thing in the config key.
To run the build command if there is a file change, you need to run this command:
$ vendor/bin/staticka watch --site="static-site" --path="static-site/build"By default, Staticka will watch the path of the keys specified from the settings file (staticka.php):
configcontentviews
If you want to add additional folders to be watched, just find the watch key:
staticka.php
...
/**
* Looks for file changes from the specified directories.
*
* @var array
*/
'watch' => array(__DIR__ . '/source/assets'),
...You may encounter a scenario wherein you need to compile your files first before or after building. An example for this one is running Gulp commands. To run the required scripts, find the scripts key with before and after values:
staticka.php
...
/**
* Scripts needed to be run before or after the building.
*
* @var array
*/
'scripts' => array('before' => 'gulp'),
...Staticka can use helpers in helping you to put functions into your view files. By default, Rougin\Staticka\Helper\UrlHelper is added in which can be used in the view by the $url variable. To add additional helpers to your site, include them in a includes key:
staticka.php
...
/**
* Returns a listing of helpers to be used in the view files.
*
* @var array
*/
'filters' => array(
/**
* The "key" is the alias to the view while the "value" is the class related to it.
*/
'url' => 'Rougin\Staticka\Helper\UrlHelper',
'array' => 'Acme\Helper\ArrayHelper',
'dir' => 'Acme\Helper\DirectoryFilter',
),
...views/index.blade.php
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Staticka - yet another static site generator written in PHP.</title>
<!-- You can now use the URL helper as "$url" inside a view template -->
<link rel="stylesheet" href="{{ $url->set('css/styles.css') }}">
</head>
<body>
<p>The ting goes skrrrahh (ah)</p>
<p>Pap, pap, ka-ka-ka (ka)</p>
<p>Skidiki-pap-pap (pap)</p>
<p>And a pu-pu-pudrrrr-boom (boom)</p>
<p>Skya (ah), du-du-ku-ku-dun-dun (dun)</p>
<p>Poom, poom, you don' know</p>
<script src="{{ $url->set('js/scripts.js') }}" async></script>
</body>
</html>Staticka can also use filters to modify the contents generated in the built path. By default, these two filters are available and added:
Rougin\Staticka\Filter\CssMinifierRougin\Staticka\Filter\HtmlMinifier
To modify the list of filters you want to use, just find the filters key:
staticka.php
...
/**
* Returns a listing of filters to be used in the built site.
*
* @var array
*/
'filters' => array(
'Rougin\Staticka\Filter\CssMinifier',
'Rougin\Staticka\Filter\HtmlMinifier',
'Acme\Filter\MyFilter',
'Acme\Filter\AnotherFilter',
),
...To create your own filter, you must implement it in FilterInterface.
If you have a filter or a helper that contains dependencies or needs to be configured first, it is better to add them into an integration in order for Staticka to use it properly. The example below contains the integration file of the Rougin\Staticka\Helper\UrlHelper:
HelperIntegration.php
namespace Rougin\Staticka\Helper;
use Rougin\Slytherin\Container\ContainerInterface;
use Rougin\Slytherin\Integration\Configuration;
use Rougin\Slytherin\Integration\IntegrationInterface;
/**
* Helper Integration
*
* An integration for template renderers to be included in Slytherin.
*
* @package Slytherin
* @author Rougin Royce Gutib <rougingutib@gmail.com>
*/
class HelperIntegration implements IntegrationInterface
{
/**
* Defines the specified integration.
*
* @param \Rougin\Slytherin\Container\ContainerInterface $container
* @param \Rougin\Slytherin\Integration\Configuration $config
* @return \Rougin\Slytherin\Container\ContainerInterface
*/
public function define(ContainerInterface $container, Configuration $config)
{
$helper = 'Rougin\Staticka\Helper\UrlHelper';
$url = new UrlHelper($config->get('app.base_url'));
return $container->set($helper, $url);
}
}To include your own integration/s, just find the integration key:
staticka.php
...
/**
* Returns a listing of integrations to be used.
*
* @var array
*/
'integrations' => array(
'Acme\Integrations\AcmeIntegration',
'Acme\Integrations\NewIntegration',
'Rougin\Staticka\Content\MarkdownIntegration',
'Rougin\Staticka\Helper\HelperIntegration',
'Rougin\Staticka\Renderer\RendererIntegration',
),
...NOTE: MarkdownIntegration and ViewIntegration are implemented in Rougin\Staticka\Content\ContentInterface and Rougin\Slytherin\Template\RendererInterface respectively which are required by Staticka to generate the content and view files. So if you don't want to use the Markdown format and the Laravel Blade or Twig engine, you can replace them by implementing it to their mentioned interfaces.
Please see CHANGELOG for more information what has changed recently.
$ composer testPlease see CONTRIBUTING for details.
If you discover any security related issues, please email rougingutib@gmail.com instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.