Nouveau blog du lab !

Le blog du lab est de retour ! Il est hébergé sur Github Pages et généré par Sculpin. Pourquoi Sculpin ? Comment l'installer ? Comment l'utiliser avec Github Pages.

Pourquoi Sculpin ?

Pour notre blog nous voulions un outil simple, et si possible sans maintenance. Avec Scuplin et les Github Pages, pas besoin de serveur ni de sauvegardes et pas de soucis concernant la maintenance. D'autres outils existent notament Jekyll en ruby, mais comme nous sommes plus habitués à PHP et à Symfony 2 et Twig, Sculpin nous sembait plus adapté.

Comment l'installer ?

Pour l'installer, plusieurs possibilités, nous avons décidé d'utiliser l'installation avec composer. Voici notre fichier composer.json

{
    "name": "lanetscouade/lelab-leblog",
    "require": {
        "sculpin/sculpin": "2.0.*@dev",
        "composer/composer": "1.*@dev"
    },
    "config": {
        "bin-dir": "bin"
    },
    "minimum-stability": "dev"
}

une fois ce fichier créé lancez la commande composer install

Pour démarrer votre blog voici une structure minimale

▾ app/
  ▾ config/
      sculpin_site.yml
▾ source/
  ▾ _includes/
  ▾ _posts/
      2014-03-05-mon-premier-post.md
  ▾ _views/
      default.html
      post.html
    index.html

Vos posts sont contenus dans le dossier source/_posts en markdown en html ou bien en textile, ici nous utiliserons markdown

La date au début du nom de fichier sera extraite pour être affichée dans l'article et reprise dans l'url. Par défaut 2014-03-05-mon-premier-post.md sera accessible avec l'url 2014/03/05/mon-premier-post

Voici le contenu du fichier 2014-03-05-mon-premier-post.md

---
title: Mon premier post !
---

Ceci est mon premier post avec scuplin

La partie entre les deux lignes --- est en YAML et vous permet de spécifier les variables liées à votre post, celles-ci seront accessibles dans vos templates par page.title

Pour afficher ce post il reste un travail de templating à faire, en effet il faut maintenant définir les 3 templates :

default.html qui sert de layout à votre blog
index.html pour contruire votre page d'accueil
post.html pour afficher vos posts

default.html

<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="UTF-8">
    <title>{{ site.title }}</title>
    <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css">
</head>
<body class="container">
    <header>
        <h1>{{ site.title }}</h1>
        <h2>{{ site.subtitle }}</h2>
    </header>
    <div id="content">
        {% block content_wrapper %}{% block content %}{% endblock %}{% endblock %}
    </div>
</body>
</html>

index.html

---
layout: default
generator: pagination
pagination:
    max_per_page: 3
use:
    - posts
---

{% for post in page.pagination.items %}
    <article>
        <header>
            <h2><a href="{{ site.url }}{{ post.url }}">{{ post.title }}</a></h2>
        </header>
        <div>
            {{ post.blocks.content | raw }}
        </div>
    </article>
{% endfor %}

post.html

{% extends "default" %}
{% block content_wrapper %}
<article>
    <header>
        <h1 class="title">{{ page.title }}</h1>
    </header>

    <section>
        {{ page.blocks.content | raw }}
    </section>
</article>
{% endblock %}

Et voila votre blog est prêt.

Pour le tester dans un navigateur : php bin/sculpin generate --watch --server votre blog sera alors visible à l'adresse http://127.0.0.1:9000.

Github pages

Github propose d'héberger vos pages, si vous souhaitez avoir une url du type username.github.io il faudra créer un dépôt nommé username.github.io et placer vos fichiers statiques dans la branche master.

Pour cela nous avons choisi de mettre les fichiers sculpin dans une branche sculpin et les fichiers générés dans la branche master.

Voici le script que nous utilisons :

#!/bin/bash

OUTPUT_DIR="output_prod"
REPO="git@github.com:LaNetscouade/LaNetscouade.github.io.git"

# check build dir exists
if [ ! -d "$OUTPUT_DIR" ]
then
  git clone -b master $REPO $OUTPUT_DIR
else
  cd $OUTPUT_DIR
  git pull
  cd ../
fi

php bin/sculpin generate --env=prod
cd $OUTPUT_DIR

# publish
git add .
git commit -m "updated gh-pages"
git push origin master

cd ..

Étendre Sculpin

Nous avions envie de pouvoir simplement afficher l'avatar de l'auteur du post, nous avons choisi d'utiliser gravatar.

Un bundle sf2 existe déjà ornicar/gravatar-bundle et Oh joie ! il est possible d'utiliser les bundles sf2 dans Sculpin.

Commençons par installer le bundle avec composer : composer require "ornicar/gravatar-bundle:1.1.0"

Ajoutons le fichier app/SculpinKernel.php

<?php

class SculpinKernel extends \Sculpin\Bundle\SculpinBundle\HttpKernel\AbstractKernel
{
    protected function getAdditionalSculpinBundles()
    {
        // Return an array of strings that represent the classes of the
        // Sculpin bundles.
        return array('Ornicar\GravatarBundle\OrnicarGravatarBundle');
    }
}

Et maintenant vous pouvez utiliser {{ gravatar('auteur@mail.com') }} dans vos templates même en markdown.

Notre dépôt git est disponible à cette adresse https://github.com/LaNetscouade/LaNetscouade.github.io.

La documentation de Sculpin sur https://sculpin.io.