Sites statiques : Github, Middleman et Jekyll

5 min readDec 14, 2016

Souvenez-vous des sites personnels avec livre d’or, commentaires, statistiques en tous genres, écrits en bon vieux HTML/PHP, hébergés sur un mutu 1&1 Starter 2€99, balancés sur la toile en FTP avec l’espoir que la base MySQL est bien paramétrée… J’en passe des meilleures.

Ce temps est révolu, concentrez vous sur le contenu ! Actuellement, la majorité des actions sur un blog/application sont le “bookmark” ou le “précédent”.

Néanmoins, ces technos ne sont pas à bannir, elles restent tout de même la base d’une bonne compréhension web.

A présent, entrons dans le vif du sujet : vous souhaitez vous créer un site personnel ? Un site présentant votre Facebook fait maison ? Cet article est fait pour vous !

User/project Github pages

Github : c’est un service web d’hébergement et de gestion de développement de logiciels, utilisant le programme Git (merci Wikipédia)… Pour faire court : une plateforme sociale de travail. Ce réseau offre d’innombrables solutions permettant le développement de communautés souhaitant collaborer au sein d’un environnement stable et agréable.

Restons focalisés sur le thème de cet article. L’une de ces fonctionnalités est le “user/project Github pages”, comprenez “pages Github d’utilisateur/projet”.

Après la création de votre compte Github, vous aurez la possibilité de démarrer une infinité de projets (appelés “repository”).

Où veux-tu en venir ? Tu travailles pour Github ?

Eh non, mais pour chacun des dossiers créés, un domaine web est réservé pour la mise en place d’un site de présentation du projet, intéressant non ?

Exemple : my-awesome-plugin créé par moi-même (tiste), donnerait l'url suivante : http://tiste.github.io/my-awesome-plugin

La technique

Commençons par un projet banal.

Admettons que votre code soit versionné. Il utilisera les branches master, develop, etc.

Afin de construire votre “project github pages”, vous n’aurez qu’à pousser du code basique style : HTML, CSS, Javascript... sur une branche nommée gh-pages.

Le rendu sera disponible d’ici une dizaines de minutes sur http://username.github.io/projectname

Mais qu’est ce qu’un “user Github pages” ?

Le principe est le même, à deux différences près :

le dossier doit prendre la forme de : username.github.io
le code source doit être sur la branche master

L’intérêt de ce dossier est de posséder votre site personnel sur une adresse du type : http://username.github.io Ainsi, vous mêlez projets et site de présentation sur une même base URL.

Je veux changer d’URL

En effet, d’un point de vue communication, il est étrange de donner une adresse Github pour un site web (quoique…).

Il existe donc un agencement de méthodes assez simple :

déposer un CNAME à la racine de vos sources avec l’url souhaitée comme seul contenu
faire pointer les DNS sur Github (explication à la suite)

Si votre URL ne possède pas de sous-domaine, créez une entrée A pointant vers l'ip 204.232.175.78.

Sinon, créez une entrée CNAME dirigeant vers votre url Github.io, soit : username.github.io.

Voyons maintenant divers outils les plus utilisés dans la conception de sites hébergés chez Github.

Outils

Github’s Automatic Page Generator

Le premier de ces outils est bien évidemment livré par Github.

Allez dans l’onglet “Settings” de votre dossier Github, et cliquez sur le bouton “Automatic Page Generator”.

Vous aurez accès à l’écriture de votre contenu ainsi qu’une sélection de thèmes. Les sources seront incluses dans votre dossier sur la branche gh-pages.

Astuce : rédigez au préalable un README.md et Github le prendra comme contenu par défaut.

Middleman

Pour moi l’un des meilleurs générateur de sites statiques, Middleman est écrit et se développe en ruby.

Cette gem crée une architecture ressemblant à celle de Ruby On Rails.

L’avantage de ce générateur est qu’il est en parfaite interaction avec Ruby et donc, les gems (une gem est un assortiment de fichier de code, permettant un développement plus rapide de certaines fonctionnalités). Ajoutez donc les gems souhaitées au Gemfile, et utilisez les dans votre code.

Exemple : slim, sass, coffeescript...

Son principe est simple, l’ensemble du code se situe dans le dossier source et il se compile dans le dossier data. Pour lancer le serveur middleman : middleman server (accessible sur localhost:4567).

Vous l’aurez compris, Github a besoin de la version compilée de Middleman. Le principe est simple :

Créez une branche master contenant vos sources
Créez une branche orpheline gh-pages contenant le site compilé

Tu m’as perdu ! C’est beaucoup trop dur à gérer !

Heureusement, pour les plus novices d’entre vous, la gem middleman-deploy fera ce travail. Vous n'aurez que l'architecture et le contenu à penser.

Voici une brève installation de middleman.

gem install middleman # si vous ne la possédez pas encore
middleman init my_awesome_project --template=html5# Gemfile

gem 'middleman',            '~> 3.1.3'
gem 'middleman-deploy'
gem 'middleman-livereload', '~> 3.1.0'
gem 'middleman-syntax'
gem 'redcarpet'
gem 'slim'# config.rb

activate :gzip
activate :livereload
activate :syntax

set :markdown, fenced_code_blocks: true
set :markdown_engine, :redcarpet

configure :build do
  activate :minify_css
  activate :minify_javascript
end

activate :deploy do |deploy|
  deploy.method       = :git
  deploy.branch       = 'master'
  deploy.build_before = true
end

Ressources utiles :

Jekyll

Avec un esprit “blog” plus important, Jekyll est L’outil pour gérer votre contenu de manière très simple.

Celui-ci est composé de la structure suivante :

_posts/ : les articles
_includes/ : les parties globales du site (header, footer, etc...)
config.yml : configuration générale
_site : placé dans le .gitignore, ce dossier représente votre site compilé (disponible après le premier lancement du serveur, voir plus bas)
_layouts/ : modèles utilisés dans un post, une page, etc... Il suffit de le préciser dans les données de cette page

Il vous sera donc possible de gérer une pagination, d’installer des plugins et gems, des permaliens…

Afin d’avoir un meilleur jugement concernant sa simplicité, voici la documentation Jekyll.

Au niveau du déploiement, Github prend complètement en charge sa compilation. En effet, lors du développement, la commande permettant l’affichage du site et sa compilation est : jekyll serve (accessible sur localhost:4000). Lors de la production, Github va automatiquement détecter chacun de vos push, et compilera automatiquement votre application.

Note : veillez à développer votre application sur la branche gh-pages ou master (dans le cas respectivement d'un dossier de projet, ie. project Github pages, ou de votre dossier personnel, ie. user Github pages).