Site-builder is a simple static site generator. It allows you to create and manage a website out of simple text files and templates.

Overview

Build Status

Site-builder

Site-builder is a simple static site generator. It allows you to create and manage a website out of simple text files and templates. This gives you many of the advantages of a CMS, but because the result is plain old HTML, it's more secure and has higher performance.

Site-builder works by copying files from your content directory to an output directory, applying one or more transformation filters on the way.

Note: There are more stable and better-supported static site generators out there; this is just a personal project to help me learn and improve my code. If you're looking for a well-supported and very capable static site generator, look at Jekyll (Ruby), Hyde (Python), or Phrozn or PieCrust (both PHP).

Quick Start

  1. Download the .phar file. It's the whole app in one file, with everything it needs to run.
  2. Put sitebuilder.phar in the directory where you want to keep the installation.
  3. Run php sitebuilder.phar init to create directories, config, and sample files.
  4. Test your installation with php sitebuilder.phar rebuild. If it works, you should see a generated example.html file in the output directory.
  5. Replace the default template with your own. Twig is a pretty straightforward template language; just put {{ content | raw }} where you want your page content to appear. Read on for more help and links to the Twig docs.
  6. Create your content files. You can write plain HTML (and save as .html), or Markdown (and save as .md or .markdown). You can make sub-directories too. Read on for more info on Markdown, including a link to the documentation.
  7. Run php sitebuilder.phar rebuild to regenerate your site.

Why use it?

Using a CMS or Apache/PHP includes will build your site dynamically upon request, which adds a lot of overhead - your content probably doesn't change very often, and all you really need those things for is to keep your content and your templates separate.

By contrast, static site generators run offline and rebuild your site as flat HTML when you change your content. A web server like Apache can deliver flat HTML files hundreds of times more efficiently than processing PHP files every time they're requested.

Site-builder is yet another SSG. Out of the box it supports Twig templates, and content files in HTML and Markdown. It's also extensible, so you can add transformations for any other behaviour you want.

Requirements

  • PHP 5.3 or newer. If you use Ubuntu or Debian, you may need to install the php5-cli package to let you run scripts on the command-line.

If you aren't running the .phar edition, you'll need these:

  • Twig 1.6 or newer
  • "dflydev"'s Markdown library
  • Symfony2 Components: Yaml, Config, DependencyInjection, ClassLoader, Console

A composer.json file is included to handle the installation of these requirements. See the next section for more about this.

Installation

  1. Download or clone this repository.
  2. From the command-line, run curl http://getcomposer.org/installer | php and follow the on-screen instructions to install Composer.
  3. Run php composer.phar install to install all the required libraries into the vendor directory.
  4. Test the installation by running php sitebuilder.php rebuild. Check for files in the output directory.
  5. If you're helping to develop Site-builder, run php composer.phar install --dev to install PHPUnit, and run it with vendor/bin/phpunit. You can copy phpunit.xml.dist to phpunit.xml if you want to change it. Rebuild the phar with the compile.php script.

Usage

The basics

  1. Put your content (e.g. index.html, about-me.md) into the content directory. Content files are just that: the main content of the page you want to publish. The name of the file when you publish will be the same as the content file, except with .html instead of the original extension. You can create sub-directories in your content directory and they'll be created in the output directory when you publish, so don't feel like you have to cram everything into the same directory.

  2. The default template is template.twig in the templates directory. Change it however you like. You can also change the default template in config.ini. More on that later. The content of your content files is placed into the template variable called $content (or {{content}} in Twig).

  3. Run php sitebuilder.php rebuild to render every file and save it to the output directory.

Templates

Twig is a fast, clean, and extensible template language with a syntax very similar to Jinja and Django's templating systems. Read more about writing Twig templates here.

Twig escapes output by default, which is very safe and good practice. However the content variable which contains your page content probably shouldn't be escaped. You can tell Twig not to escape it by passing it through the raw filter, i.e. {{ content | raw }}

Content

Site-builder accepts content in either HTML or Markdown format. Pick whichever you prefer, or use both. Both have an optional "front matter" block which contains instructions you can pass to the template.

HTML & Twig content format

Look at content/example.html for an example. The file is like any other HTML file and you can write whatever you like into it. The only difference is an optional front matter block, which allows you to pass more information to the template when you rebuild the site.

When the page is published, the contents of the file are passed to the template in the content variable along with anything else you define in your front matter block.

---
title: This is my page title
---

<h2>Hello world!h2>
<p>This is my content file. There are many like it but this one is mine.p>

If you set the template variable in your front matter, then Site-builder will render the page with that template instead of the default.

Markdown & Twig content format

Markdown is an "easy-to-read, easy-to-write plain text format", which is then turned into valid, clean HTML. It was developed by John Gruber and is very popular. This page itself was written in Markdown. A simple example markdown content file can be found in content/markdown-example.md.

Read more about writing Markdown here.

There are four important things to note about Markdown content files in Site-builder:

  1. Markdown can contain plain old HTML, so don't feel constrained by it!
  2. Your markdown content files should end in either .markdown or .md
  3. Site-builder looks for (but doesn't require) a "front-matter" block where you can set variables to be passed to your template.
  4. Site-builder uses Markdown Extra by default. It add some features to Markdown, like tables, ids, code blocks, and footnotes.

The front-matter block is written in YAML and looks like this:

---
title: This is my page title
template: myTemplate.twig
---

My page title
=============

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor 
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis 
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu 
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in 
culpa qui officia deserunt mollit anim id est laborum.

When you rebuild the site, Markdown files are converted into HTML and then passed to either the default template, or whichever template you named in the front-matter block. The HTML content is set on the {{ content | raw }} variable in the template.

Contributing

I'd love to have pull requests to improve Site-Builder. Please raise an issue first though, in case someone's already working on the feature.

  • I think I've got good unit test coverage, but I'm no expert. Any help with tests would be appreciated.

  • Documentation (end user and developer). I've started to add doc-comments and there's this README, but there could be more and better, I know.

  • A navigation generator object passed to the templates that represents the site structure, so that templates can create left navigation. It should ignore resource files and be context aware (so links in sub-directories don't break).

  • Please submit pull requests to the dev branch! The master branch is for tested, stable releases only.

Contributors

Comments
  • Twig variable

    Twig variable "back to root" ? (for offline documentation)

    Hello there,

    I'm currently planning to use site-builder for generation of offline html documentation (not an API doc, more like a user manual for non-tech guys). Thus I'm facing a problem for static ressources management (css+js) when using .md content files in subdirectories: as the directory structure is kept (which is a good thing), the links to the static resources are broken. And as I'm browsing the doc directly on the disk, I cannot make a reference to the "root of website"

    So my idea was to have access to a new variable in Twig generation context. This variable would reference the way to go back to the 'root' (=folder) of my 'website' (=local storage)

    The code would look like this:

    $data['backToRoot'] = '../../';
    

    Of course this variable would be set differently for each template depending on its location. Then the variable would be used in template like that:

    <link href="{{ backToRoot }}css/my-style.css" rel="stylesheet">
    
    • If you know a simpler way to solve this problem I'm interested ;)
    • If you think that it's not a good idea or that it's a too specific need, please tell me, I'll understand.
    • If you think it's fine, I can try to code this, even if I might need a little help, especially for the usage of the service container.
    opened by inouire 13
  • Is Sass mandatory ?">

    "Sass compiler not installed" -> Is Sass mandatory ?

    When I initiate a new project with php site-builder.phar init If I try to generate the files with php site-builder.phar rebuild, I have this error:

    [InvalidArgumentException] Sass compiler not installed, or not configured. Check your config.ini

    As I don't want to use Sass I left the field blank in the config.ini file: sass_path = but it doesn't seem to work.

    Am I doing something wrong ? Or is there a problem with arguments checking ?

    opened by inouire 6
  • New Pagecontext transformer

    New Pagecontext transformer

    Here is an implementation of a more complete PagecontextTransformer that populates the data object with information related to the context of generation:

    • siteroot : as before
    • pagename : name of the page, without extension
    • breadcrumbs : an array containing the list of directories of the current path

    I also completed template.twig and added some example content to show how to use such information.

    Tell me what you think !

    opened by inouire 3
  • Default template not always taken into account ?

    Default template not always taken into account ?

    I just noticed a strange behavior towards default template. Here is my structure

    index.md
    a/
      |_plop.md
    b/
      |_plop.md  
    

    The two plop.md files are the same, and no template is defined in their front matter. So I assume that default template specified in config.ini will be used. index.md has a specific template though, specified in the front-matter

    But when I rebuild the site, one of the generated file has the good template (default), but the other has the template used by index.md !

    Any idea ? Thanks for your help,

    opened by inouire 2
  • Refactor app object

    Refactor app object

    Currently the app object (actually an array) passed to the renderer contains the ContentCollection and ContentHandler objects, but these aren't really the right things to pass.

    The ContentCollection isn't aware of content hierarchy (paths are flattened) so generating nav from it isn't very useful. Relative path names are always "root relative" to the output folder, so building nav for a page that isn't in that folder makes broken links. A traversable tree object with a URL generator might make more sense.

    opened by mattattui 0
Owner
Matt Robinson
Matt Robinson
WordPress static site generator for security, performance and cost benefits

WordPress static site generator for security, performance and cost benefits

Leon Stafford 1.2k Nov 26, 2022
Sculpin — Static Site Generator

Sculpin - PHP Static Site Generator Sculpin takes data sources such as text files (Markdown, Textile, etc.) and transforms them using Twig templates t

Sculpin 1.4k Nov 28, 2022
Phrozn is extremely flexible static site generator in PHP.

Phrozn Phrozn is extremely flexible static site generator in PHP. Philosophy Configurable: you should be able to tune it to your needs SCM-Enabled: no

Povilas Balzaravičius 459 Oct 30, 2022
PHP Static site generator

Spress - PHP Static site generator Spress is a static site generator built with Symfony components. License: MIT. Requirements Linux, Unix, Mac OS X o

Spress 375 Nov 28, 2022
Statamic 3 is the flat-first, Laravel + Git powered CMS designed for building beautiful, easy to manage websites.

About Statamic 3 Statamic 3 is the flat-first, Laravel + Git powered CMS designed for building beautiful, easy to manage websites. Note: This reposito

Statamic 2.3k Dec 5, 2022
Cecil is a CLI application that merges plain text files (written in Markdown), images and Twig templates to generate a static website.

Cecil is a CLI application that merges plain text files (written in Markdown), images and Twig templates to generate a static website.

Cecil 206 Nov 19, 2022
Cecil is a CLI application that merges plain text files (written in Markdown), images and Twig templates to generate a static website.

Cecil is a CLI application that merges plain text files (written in Markdown), images and Twig templates to generate a static website.

Cecil 206 Nov 19, 2022
Create videos programmatically in the cloud from PHP: add watermarks, resize videos, create slideshows, add soundtrack, voice-over with text-to-speech (TTS), text animations.

Create videos programmatically in the cloud from PHP: add watermarks, resize videos, create slideshows, add soundtrack, voice-over with text-to-speech (TTS), text animations.

null 6 Oct 21, 2022
Greyhole uses Samba to create a storage pool of all your available hard drives, and allows you to create redundant copies of the files you store.

Greyhole Greyhole is an application that uses Samba to create a storage pool of all your available hard drives (whatever their size, however they're c

Guillaume Boudreau 246 Dec 1, 2022
Daux.io is an documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It helps you create great looking documentation in a developer friendly way.

Daux.io - Deprecation Notice This repository is deprecated! Daux.io has been moved to an organization, to guarantee future development and support. So

Justin Walsh 4.6k Nov 20, 2022
Daux.io is an documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It helps you create great looking documentation in a developer friendly way.

Daux.io Daux.io is a documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It help

Daux.io 719 Nov 29, 2022
A PHP spreadsheet reader (Excel XLS and XLSX, OpenOffice ODS, and variously separated text files) with a singular goal of getting the data out, efficiently

spreadsheet-reader is a PHP spreadsheet reader that differs from others in that the main goal for it was efficient data extraction that could handle l

Nuovo 665 Dec 1, 2022
Connect and work with MySQL/MariaDB database through MySQLi in PHP. This is an introductory project, If you need a simple and straightforward example that takes you straight to the point, you can check out these examples.

First MySQLi PHP Connect and work with MySQL/MariaDB database through MySQLi in PHP. The above exercises are designed for students. This is an introdu

Max Base 4 Feb 22, 2022
WordPress static site generator for security, performance and cost benefits

WordPress static site generator for security, performance and cost benefits

Leon Stafford 1.2k Nov 26, 2022
Sculpin — Static Site Generator

Sculpin - PHP Static Site Generator Sculpin takes data sources such as text files (Markdown, Textile, etc.) and transforms them using Twig templates t

Sculpin 1.4k Nov 28, 2022
Phrozn is extremely flexible static site generator in PHP.

Phrozn Phrozn is extremely flexible static site generator in PHP. Philosophy Configurable: you should be able to tune it to your needs SCM-Enabled: no

Povilas Balzaravičius 459 Oct 30, 2022
PHP Static site generator

Spress - PHP Static site generator Spress is a static site generator built with Symfony components. License: MIT. Requirements Linux, Unix, Mac OS X o

Spress 375 Nov 28, 2022
The official Statamic 3 static site generator package

Statamic Static Site Generator Generate static sites with Statamic 3. Installation Install the package using Composer: composer require statamic/ssg

Statamic 184 Nov 20, 2022
Laravel static site/blog generator with markdown support.

Katana static site & blog generator PHP static site & blog generator with markdown support. Using the power of laravel's Blade templating engine. Kata

Mohamed Said 380 Sep 3, 2022