CouicStart, un template Middleman pour démarrer rapidement un projet

Les templates Middleman

Middleman permet de créer des templates de sites, qu'on peut utiliser lorsqu'on démarre un nouveau projet avec middleman init mon_projet. Toute la configuration et le contenu du template sont alors copiés dans le nouveau projet ce qui permet un énorme gain de temps.

Il existe un grand nombre de templates et certains répondent peut-être déjà à vos besoins. N'hésitez pas à consulter les sources :)

Il n'y a aucune restriction, on peut inclure ce qu'on veut dans un template! C'est pourquoi on en trouvera certains très dépouillés avec juste la configuration de base et d'autres plus complets avec une mise en page CSS et des pages à éditer.

CouicStart

CouicStart est un template Middleman qui s'inscrit dans un projet plus vaste ayant pour but d’accélérer la cadence de production de sites web. Comme tout template ou thème pour CMS il n'a pas pour vocation d'être universel et de répondre à tous les besoins.

Il sera utile pour des projets de sites type brochure/vitrine, blog, micro-site, landing-page ainsi que pour du prototypage rapide.

Il est pré-configuré et livré avec des exemples de pages de site et un blog fonctionnel. Il suffit d'éditer quelques fichiers et on peut rapidement déployer sur Github Pages ou en FTP/STP.

Fiche technique

CouicStart utilise diverses gems Ruby qui seront installées automatiquement à la création du nouveau projet si elles ne sont pas présentes sur votre système. Ci après la liste des gems utilisées:

• middleman-blog : ajoute la fonction blog
• middleman-livereload : live reload des pages en développement
• middleman-deploy : permet de déployer en une seule commande

• middleman-dotenv : permet d'ajouter des variables dans un fichier .env

• middleman-autoprefixer : ajoute les préfixes navigateurs aux CSS
• middleman-favicon-maker : automatise la création de favicon
• middleman-sitemap : automatise la création du sitemap
• middleman-google-analytics : ajoute le script pour Google Analytics
• middleman-protect-emails : ajoute un protection pour les emails

• middleman-minify-html : minifie les fichiers HTML au build

• middleman-disqus : ajoute le support de commentaires avec Disqus

• slim : permet d'utiliser Slim comme langage de template
• better_errors : un peu d'eye-candy pour l'affichage des erreurs
• bourbon : librairie de mixins SASS
• neat : grille responsive

La liste des gems permet d'entrevoir les fonctionnalités du template dont la plupart sont activées dans config.rb, les autres nécessitant de modifier des fichiers.

Installation

L'installation du template se fait dans le dossier ~/.middleman/ en clonant le dépôt git. Soit en ligne de commande

$ git clone https://github.com/SamuelBourdon/couicstart.git ~/.middleman/couicstart`

Les mises à jour du template seront à faire dans ce dossier avec git pull. Pour la suite, on démarre un nouveau projet en utilisant CouicStart :

# Dans votre dossier de travail
$ middleman init nom_du_projet --template=couicstart

Middleman crée le nouveau projet et installe automatiquement les gems manquantes. Post-installation, on dispose d'un site fonctionnel avec des pages en exemple servant à populer le menu principal, un blog permettant la création de nouveaux articles et listant ceux existants et un minium de CSS pour l'affichage.

Un petit goût de Ruby on Rails

Les dossiers images, stylesheets et javascripts sont déplacés dans le dossier assets pour calquer l'asset pipeline de Ruby on Rails. Ce choix est volontaire, l'idée étant de pouvoir réutiliser des composants à la fois dans Middleman et Rails en limitant les modifications.

Architecture CSS

CouicStart utilise SASS, Bourbon et Neat comme librairies de mixins pour les CSS.

Dans assets/stylsheets/base/ on trouve des fichiers .scss définissant les styles de base. L'approche se veut "par composant" qu'on ajoute dans le dossier components/ comme c'est déjà le cas pour _navbar.scss et _footer.scss.

Toutes les variables sont déclarées en en-tête de chacun des fichiers avec le flag !default et peuvent être écrasées dans le fichier _settings.scss.

CouicStart est lié à un autre projet qui consiste en une bibliothèque de composants interchangeables pour Middleman/Rails.

Cette bibliothèque contient des éléments d'interface comme des navbars ou footers mais aussi des sections de page, des galeries d'images, des formulaires prêts à l'emploi…

Chaque composant contient un fichier .scss pour les styles, un fichier .slim à intégrer dans la view et au besoin un .js pour le javascript et un .yml pour les datas.

Autres frameworks CSS

Si vous ne voulez pas utiliser cette base, supprimez tous les fichiers dans base/, config/ et components/ et le contenu du fichier all.css.scss. Pensez également à retirer les gems Bourbon et Neat du Gemfile.

Vous pouvez embarquer un framework CSS différent ainsi que toute dépendances front-end via Bower

# dans le dossier du projet
$ bower install nom_du_paquet

Les paquets seront alors dans le dossier bower_components à la racine du projet, il ne reste plus qu'à les linker dans les fichiers all.css.scsset all.js.

Prise en main rapide de CouicStart

Revenons sur la configuration initiale dans config.rb et les fichiers de données .yml. Voyons comment cela fonctionne et comment cela peut être modifié.

Éditer les fichiers datas

Dans le dossier data se trouvent les fichiers settings.yml et menu.yml qu'il faut éditer avec les informations relatives au projet.

Le fichier settings.yml contient des informations qui sont, ou peuvent, être utilisées dans les pages. Adaptez-les avec vos données.

Le fichier navbar.yml contient les entrées du menu situé dans la navbar. Le menu est généré dynamiquement, on utilise ce fichier pour ajouter de nouveaux éléments.

Le blog

Les articles créés avec la commande middleman article "Titre de l'article" sont rangés dans le dossier blog/ et sont au format année-mois-jour-titre.

Le format utilisé pour les articles est le Markdown. Chaque article dispose d'un bloc Frontmatter dans lequel on peut renseigner le nom de l'auteur et ajouter un titre spécifique pour la balise <title> et une descrption. Le nom de l'auteur et la date sont utilisés lors de l'affichage de la liste des articles.

Chaque nouvel article est généré grâce au template new-article.erb qu'il faut modifier si on souhaite ajouter de nouvelles informations dans Frontmatter.

Les commentaires Disqus sont par défaut désactivés. Pour les activer, il faut décommenter la gem Disqus dans le Gemfile, décommenter le bloc concernant Disqus dans config.rb et enfin décommenter la ligne = disqus dans layouts/blog.slim.

Reportez-vous au tutoriel Middleman : ajouter un blog pour une prise en main complète du blog.

Google Analytics

Pour utiliser Google Analytics, il faut rentrer votre code de suivi dans le fichier settings.yml puis décommenter la ligne = google_analytics_universal_tag dans le fichier layouts/layout.slim.

En développement

Le Live Reload est activé, permettant de rafraichir le navigateur à chaque sauvegarde du fichier. Autoprefixer se charge d'ajouter les préfixes navigateurs aux règles CSS en ayant besoin. Les tailles des images sont ajoutées automatiquement lors de l'usage du helper image_tag.

Le build

Le build est configuré pour minifier les CSS et JS et fichiers HTML. La compression gzip est activée et la création du sitemap est automatique.

Pour la favicon, les fichiers sont générés à partir de _favicon_template.png qu'il faut modifier avec votre favicon. Le fichier doit faire 152px * 152px.

Deployer le site

Initialement le déploiement est en FTP. La méthode de déploiement se change dans config.rb en accord avec la documentation de middleman-deploy. Les informations de connexions sont à entrer dans le fichier .env qu'il ne faudra pas oublier d'ajouter dans le fichier .gitignore pour ne pas le versionner et le voir s'afficher dans votre dépôt github.

Fonctionnalités à venir.

La première release est un peu brute de décoffrage et nécessite quelques améliorations. Les prochaines versions devraient voir arriver quelques helpers utiles, une localisation français/anglais, la gestion automatisée des tags et catégories pour le blog ainsi qu'une page dédiée à l'auteur ou aux auteurs générée automatiquement.

La bibliothèque de composants va s'étoffer et on pourra rapidement les copier/coller pour construire de nouvelles pages.