Guide de démarrage Docpad
D’après la description disponible sur le site officiel du projet,
DocPad est une architecture de prochaine génération pour le web. Il permet une gestion de contenu via le système de fichiers, un rendu par l’intermédiaire de plugins et la génération de sites statiques capables d’être déployer n’importe où. Il est construit avec Node.js et Express.js, ce qui le rend naturellement rapide et facilement extensible.
Vous pouvez aussi lire ce que j’en disais dans ce précédent article sur les générateurs de sites statiques et vous pouvez trouver un comparateur de Docpad avec Wordpress et Jekyll sur le site.
Installation de Docpad
Rien de plus simple une fois que NodeJS est installé.
npm install -g docpadMise à jour de Docpad
La mise à jour de Docpad ne pose pas de problème comme le prouve la commande ci-dessous.
docpad upgrade; docpad updateCréation d’un projet
Commençons un nouveau projet nommé docpad (belle inspiration !) qui sera la base de notre nouveau blog.
mkdir docpad
cd docpad
docpad runComme c’est la première fois que Docpad est lancé dans ce répertoire, il initialise un nouveau projet et vous demande de choisir parmi une vingtaine de modèles prêts à l’emploi. J’ai volontairement ignoré de la sortie console qui suit les descriptions des 20 modèles présentés.
info: Welcome to DocPad v6.57.0 (global installation: /home/yol/checkmy.ws/lib/node_modules/docpad)
info: Contribute: http://docpad.org/docs/contribute
info: Plugins:
info: Environment: development
Before we continue, have you read and agree to DocPad's Terms of Service (http://bevry.me/tos) and Privacy Policy (http://bevry.me/privacy)? [Y/n] y
Fantastic. We like informed people!
Would you like to subscribe to our newsletter and stay up to date with the latest releases and tutorials? [Y/n] n
No worries. Continuing with the desired action.
info: Updating the exchange...
This can take a moment...
info: Updated the exchange
info: You are about to create your new project inside your current directory. Below is a list of skeletons to bootstrap your new project:
Which skeleton will you use? [1-20]
1. HTML5 Boilerplate
2. HTML5 Boilerplate with Grunt
3. HTML5 Boilerplate with Jade and LESS
4. Twitter Bootstrap
5. Twitter Bootstrap with Jade
6. Twitter Bootstrap with Coffeekup
7. Kitchensink
8. Benjamin Lupton's Website
9. DocPad's Website
10. Bevry's Website
11. Startup Hostel's Website
12. NodeChat
13. SlidePad
14. Reveal.js
15. Conference Boilerplate
16. Zurb Foundation(SASS)
17. Meny
18. YUI PureCSS
19. Zurb Foundation
20. No Skeleton
>Je choisis le 20 (No Skeleton) histoire de commencer avec le minimum pour y voir plus clair. La hiérarchie des fichiers et dossiers à la racine du projet est celle-ci.
-rw-rw-r-- 1 yol yol 185 janv. 20 17:14 docpad.coffee
drwxrwxr-x 4 yol yol 4096 janv. 20 17:16 node_modules
-rw-rw-r-- 1 yol yol 350 janv. 20 17:14 package.json
-rw-rw-r-- 1 yol yol 98 janv. 20 17:14 README.md
drwxrwxr-x 5 yol yol 4096 janv. 20 17:14 srcle dossier src contient trois dossiers:
- documents
- files
- layouts
Nous y reviendrons en détail par la suite.
Création page d’accueil
Créez le fichier index.html dans le dossier src/documents dans lequel vous pouvez par exemple mettre ce contenu.
<html>
<head>
<title>Bienvenue! | Mon nouveau super blog avec Docpad</title>
</head>
<body>
<h1>Bienvenue!</h1>
<p>sur mon super blog fait avec Docpad!</p>
</body>
</html>Docpad, comme tout bon générateur de sites statiques, surveille le répertoire du projet et reconstruit celui-ci dès qu’il détecte un changement dans un des fichiers. Il est donc possible d’admirer la page sur http://localhost:9778 si vous travaillez en local sur votre poste de travail.
Premier layout
Créez une page about.html dans le dossier src/documents dans lequel vous pouvez mettre ce contenu.
<html>
<head>
<title>À propos de moi sur mon site à moi</title>
</head>
<body>
<h1>À propos de moi</h1>
<p>Moi, moi-même, personnellement. <strong>Mon blog en Docpad!</strong></p>
</body>
</html>La page est disponible si tout s’est bien passé sur http://localhost:9778/about.html
Comme c’est pas très malin de dupliquer du code HTML à tout va, comme entre nos pages index.html et about.html, nous allons utiliser une technique ancestrale qui a fait ses preuves: Les layouts.
Concrètement, nous allons créer un fichier src/layouts/default.html.eco et y mettre ce contenu.
<html>
<head>
<title><%= @document.title %> | Mon site à moi</title>
</head>
<body>
<h1><%= @document.title %></h1>
<%- @content %>
</body>
</html>Reste à modifier nos deux fichiers index.html et about.html pour qu’ils utilisent ce layout.
Pour le fichier index.html, cela donne:
---
title: "Bienvenue!"
layout: "default"
isPage: true
---
<p>sur mon super blog fait avec Docpad!</p>et pour about.html, vous vous débrouillez… Je vais quand même pas tout faire !
Remarquez par contre le isPage à true qui indique que cette page est une page (par opposition à un billet de blog). Le layout placé à default pointe bien évidemment sur le layout que nous venons de créer; default.html.eco.
Rechargez la page index.html dans votre navigateur et zut plus aucun contenu mais les balises que nous avons saisi dans notre fichier de layout. Il y a un problème d’interprétation. Notre fichier de layout se terminant par .eco, Docpad veut donc l’interpréter avec eco, le moteur de templates pour CoffeScript. Celui-ci n’étant pas installé, rien ne se passe. Je quitte le serveur Docpad par CTRL+C et j’installe eco.
Premiers plugins
docpad install ecoUne fois le serveur relancé avec docpad run, le résultat est plus convaincant et notre layout correctement transformé en HTML. La nature modulaire de Docpad vous permet donc d’utiliser le langage de templates que vous préférez (HAML, Stylus, Mustache…)
Live Reload
Sois fainéant, sois fainéant tu vivras longtemps
disait Coluche dans ses excellents conseils à un nourrisson. Ne le faisons pas mentir et installons le plugin qui nous permettra de ne plus avoir à recharger la page après chaque modification.
docpad install livereloadRelancez le serveur, modifiez une page et… Rien ne se passe !
Premier « block »
Rien ne se passe car il faut encore ajouter des « blocks » (dans le jargon Docpad) à notre layout pour que celui-ci puisse injecter les scripts dans la page.
Modifions le contenu du fichier src/layouts/default.html.eco pour qu’il contienne ceci:
<html>
<head>
<title><%= @document.title %> | My site à moi</title>
<%- @getBlock("meta").toHTML() %>
<%- @getBlock("styles").toHTML() %>
</head>
<body>
<h1><%= @document.title %></h1>
<%- @content %>
<%- @getBlock("scripts").toHTML() %>
</body>
</html>Rechargez la page après modification du layout et regardez du côté du source. Vous verrez du Javascript injecté au code HTML de la page. Modifiez une des pages créées et observez celle-ci se recharger automatiquement dans le navigateur après modification.
Ajout de médias
Pas de sites sans images ou médias de nos jours, comment Docpad gère t’il tout cela ?
Images
Ajouter une image est aussi simple que de la placer, comme tout fichier binaire dans le répertoire src/files ou un sous-répertoire de celui-ci bien sûr.
Ainsi, un logo enregistré dans src/files/img/log.png est appelé par le code HTML suivant:
<img src="/img/logo.png" />Feuilles de styles
Le principe est globalement le même pour les feuilles de style mais avec une subtilité supplémentaire. Pour appeler une feuille de style stockée dans src/documents/css/main.css, il faut ajouter un « block » comme ci-dessus mais en appelant la feuille de style désirée.
<%- @getBlock("styles").add(["/css/main.css"]).toHTML() %>Scripts
Même logique que précédemment pour les feuilles de style, les scripts sont placés dans un sous-répertoire de src/documents. L’appel d’un script jquery.js stocké dans le sous-répertoire js se fait donc comme suit:
<%- @getBlock("scripts").add(["/js/jquery.js","/scripts/main.js"]).toHTML() %>Au passage, cette ligne appelle un deuxième script situé dans src/documents/scripts/main.js.
Un peu de fun avec les pré-processeurs
S’il y a bien un domaine dans lequel excelle Docpad, c’est celui du pré-processing. Les pré-processeurs sont devenus au fil du temps un des maillons obligatoires d’une bonne chaîne de développement de sites web et ils sont utilisés aussi bien pour le contenu (Markdown) que pour les feuilles de style (SCSS, Less, Stylus…) ou les scripts (CoffeeScript…).
Avec Markdown
Voyons ce que ça donne pour pouvoir écrire les pages et billets non plus en HTML mais en Markdown. Et si vous commencez à capter la logique de Docpad, il faut ajouter un plugin; multimarkdown peut-être ?
docpad install multimarkdownReste maintenant à modifier notre page src/documents/about.html pour y ajouter un peu de markdown comme ceci:
## Titre h2et surtout renommer le fichier en about.html.md pour indiquer à Docpad la transformation préliminaire de markdown en HTML.
Vous avez un pré-processeur less avant vos feuilles de styles, nommez votre fichier main.css.less et voilà !
Les variables
De façon classique pour un générateur de sites statiques, Docpad sait gérer des variables au niveau global de la façon suivante.
Au moment de la génération du site avec un premier docpad run, celui-ci a créé à la racine du site un fichier docpad.coffee qui ressemble à ceci:
# DocPad Configuration File
# http://docpad.org/docs/config
# Define the DocPad Configuration
docpadConfig = {
# ...
}
# Export the DocPad Configuration
module.exports = docpadConfigNous ajoutons un bloc de configuration pour les templates en lieu et place de # ...
templateData:
site:
title: "Mon site à moi"Ne reste plus qu’à appeler cette variable globale depuis un template comme src/layouts/default.html.eco que nous avons travaillé plus haut.
<title><%= if @document.title then "#{@document.title} | #{@site.title}" else @site.title %></title>La plupart des générateurs s’arrêtent là et mélangent du coup logique et présentation dans les templates. Il va falloir rentrer dans cette condition if chaque fois que vous souhaitez afficher un titre dans vos templates… Un peu lourd !
Les templates helpers
Docpad permet de séparer la logique de la présentation de façon stricte. Le code que nous avons utilisé juste avant peut être amélioré de cette façon.
Ajoutez cette ligne dans le fichier docpad.coffee juste sous la variable title:
getPreparedTitle: -> if @document.title then "#{@document.title} | #{@site.title}" else @site.titlele fichier complet devient alors:
# DocPad Configuration File
# http://docpad.org/docs/config
# Define the DocPad Configuration
docpadConfig = {
templateData:
site:
title: "Mon site à moi"
getPreparedTitle: -> if @document.title then "#{@document.title} | #{@site.title}" else @site.title
}
# Export the DocPad Configuration
module.exports = docpadConfigNous avons défini une nouvelle variable getPreparedTitle qui va comme son nom l’indique se charger de préparer le titre pour l’affichage.
Il ne reste plus qu’à appeler de façon simple cette variable dans les templates partout où nous avons besoin d’afficher le titre d’une page. Ceci donne pour le template src/layouts/default.html.eco de tout à l’heure:
<title><%= @getPreparedTitle() %></title>Beaucoup plus propre !
Ça vous a plu, vous en demandez encore ?
J’espère vous avoir donner envie à travers ce petit guide de prise en main de Docpad de creuser un peu la « bête ». Pour ma part, Docpad me paraît avoir un joli potentiel et je ne peux que vous inviter à vous rendre sur la documentation pour notamment comprendre la notion de collections chère à Docpad, en attendant un prochain article sur le sujet.
