Bienvenue sur codices.org

Credits

Premier contact avec Jekyll

Bienvenue sur codices.org

Cela faisait un moment que l'envie de monter un blog technique me titillait. Je sais que je suis de la vieille école, mais je ne suis pas un grand fan de ces chaînes youtube qui poussent un peu partout. Je voulais quelquechose avec une structure, qui soit facile à parcourir et où l'on peut sauter facilement au chapitre qui vous interesse. Quequechose comme ... un livre ou une page web quoi ! Et pendant que je criais à l'aide sur twitter, @DanielGriehaber m'a donné une excellente réponse : "try jekyll"

Bon, alors c’est quoi Jekyll ?

Jekyll n’est pas un CMS au sens traditionnel du terme. Avec Jekyll, pas de PHP. Non, pas de web dynamique ici mon bon monsieur : on ne génère pas les pages à la demande. C’est un générateur de site statique : on écrit les contenus en markdown (vous savez, comme sur dokuwiki) et Jekyll va transformer tout ça en une foultitude de fichiers html.

Quel intérêt me direz-vous ? Qui dit absence de php et de base de données dit surtout moins de surface d’attaque pour les méchants hackers russes. Un serveur Web minimaliste, sans CGI ni PHP, et vous voilà parti !

Alors oui, bien sur les cliquodromes à la wordpress sont bien plus “user-friendly”. Mais si vous êtes un sysadmin débutant ou amateur, croyez-moi sur parole : vous avez vraiment intérêt à maintenir votre wordpress à jour !

Installation

Pour une fois, l’installation est relativement simple et il n’y a pas une foultitude de dépendances. Pour pouvoir utiliser Jekyll, il vous faudra néanmoins :

  • Ruby
  • RubyGems
  • Python
  • NodeJS

Sur ma bonne vieille gentoo, voici comment sont configurés les USE pour chacun des paquets :

# equery u ruby
[ Legend : U - final flag setting for installation]
[        : I - package is installed with flag     ]
[ Colors : set, unset                             ]
 * Found these USE flags for dev-lang/ruby-2.3.3:
 U I
 + + berkdb    : Add support for sys-libs/db (Berkeley DB for MySQL)
 - - debug     : Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces
                 see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
 - - doc       : Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of
                 globally
 - - examples  : Install examples, usually source code
 + + gdbm      : Add support for sys-libs/gdbm (GNU database libraries)
 + + ipv6      : Add support for IP version 6
 - - jemalloc  : Use dev-libs/jemalloc for memory allocation.
 - - libressl  : Use dev-libs/libressl as SSL provider (might need ssl USE flag), packages should not depend on this
                 USE flag
 + + ncurses   : Add ncurses support (console display library)
 + - rdoc      : Install dev-ruby/rdoc after installing Ruby.
 + + readline  : Use the sys-libs/readline library to provide the readline extension, used for instance by the irb
                 tool. This flag is meaningful only if the libedit USE flag is disabled. If neither libedit nor
                 readline USE flags are enabled, the readline extension will not be built (and irb will lose line
                 editing functionality).
 - - rubytests : Install ruby tests that can only be run after ruby is installed
 - - socks5    : Add support for the socks5 proxy
 + + ssl       : Add support for Secure Socket Layer connections
 - - tk        : Add support for Tk GUI toolkit
 - - xemacs    : Add support for XEmacs
# 
# equery u rubygems
[ Legend : U - final flag setting for installation]
[        : I - package is installed with flag     ]
[ Colors : set, unset                             ]
 * Found these USE flags for dev-ruby/rubygems-2.6.8:
 U I
 + + ruby_targets_ruby21 : Build with MRI Ruby 2.1.x
 - - ruby_targets_ruby22 : Build with MRI Ruby 2.2.x
 - - ruby_targets_ruby23 : Build with MRI Ruby 2.3.x
 - - server              : Install support for the rubygems server
 - - test                : Workaround to pull in packages needed to run with FEATURES=test. Portage-2.1.2 handles this
                           internally, so don't set it in make.conf/package.use anymore
# 
# equery u python
[ Legend : U - final flag setting for installation]
[        : I - package is installed with flag     ]
[ Colors : set, unset                             ]
 * Found these USE flags for dev-lang/python-3.5.2:
 U I
 - - build    : !!internal use only!! DO NOT SET THIS FLAG YOURSELF!, used for creating build images and the first half
                of bootstrapping [make stage1]
 - - examples : Install examples, usually source code
 + + gdbm     : Add support for sys-libs/gdbm (GNU database libraries)
 - - hardened : Activate default security enhancements for toolchain (gcc, glibc, binutils)
 + + ipv6     : Add support for IP version 6
 - - libressl : Use dev-libs/libressl as SSL provider (might need ssl USE flag), packages should not depend on this USE
                flag
 + + ncurses  : Add ncurses support (console display library)
 + + readline : Enable support for libreadline, a GNU line-editing library that almost everyone wants
 - - sqlite   : Add support for sqlite - embedded sql database
 + + ssl      : Add support for Secure Socket Layer connections
 - + threads  : Enable threading support. (DON'T DISABLE THIS UNLESS YOU KNOW WHAT YOU'RE DOING)
 - - tk       : Add support for Tk GUI toolkit
 - - wininst  : Install Windows executables required to create an executable installer for MS Windows.
 + - xml      : Add support for XML files
# 
# equery u nodejs
[ Legend : U - final flag setting for installation]
[        : I - package is installed with flag     ]
[ Colors : set, unset                             ]
 * Found these USE flags for net-libs/nodejs-7.2.0:
 U I
 + + cpu_flags_x86_sse2       : Use the SSE2 instruction set
 - - debug                    : Enable extra debug codepaths, like asserts and extra output. If you want to get
                                meaningful backtraces see
                                https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
 - - doc                      : Add extra documentation (API, Javadoc, etc). It is recommended to enable per package
                                instead of globally
 - - icu                      : Enable ICU (Internationalization Components for Unicode) support, using dev-libs/icu
 + - npm                      : Enable NPM package manager
 + + python_targets_python2_7 : Build with Python 2.7
 + - snapshot                 : Enable snapshot creation for faster startup
 + + ssl                      : Add support for Secure Socket Layer connections
 - - systemtap                : Enable SystemTAP/DTrace tracing
 - - test                     : Workaround to pull in packages needed to run with FEATURES=test. Portage-2.1.2 handles
                                this internally, so don't set it in make.conf/package.use anymore
# 

Grâce à gem, vous devriez être en mesure d’installer la dernière version de Jekyll et bundler. Le tout, en une seule commande :

# gem install jekyll bundler

Tous les programmes nécessaires sont maintenant installés, vous allez pouvoir commencer votre blog. Félicitations !

Un nouveau blog from scratch

Pour créer le squelette de votre site, vous pouvez maintenant éxécuter la commande suivante, dans le repertoire de votre choix. (Attention, pas celui utilisé par votre serveur web)

$ jekyll new my-awesome-site
New jekyll site installed in /home/sebastien/my-awesome-site. 
Running bundle install in /home/sebastien/my-awesome-site... 
Fetching gem metadata from https://rubygems.org/...........
Fetching version metadata from https://rubygems.org/..
Fetching dependency metadata from https://rubygems.org/.
Resolving dependencies...
Using public_suffix 2.0.4
Using colorator 1.1.0
Using ffi 1.9.14
Using forwardable-extended 2.6.0
Using sass 3.4.23
Using rb-fsevent 0.9.8
Using kramdown 1.13.1
Using liquid 3.0.6
Using mercenary 0.3.6
Using rouge 1.11.1
Using safe_yaml 1.0.4
Using bundler 1.13.6
Using addressable 2.5.0
Using rb-inotify 0.9.7
Using pathutil 0.14.0
Using jekyll-sass-converter 1.5.0
Using listen 3.0.8
Using jekyll-watch 1.5.0
Using jekyll 3.3.1
Using jekyll-feed 0.8.0
Using minima 2.1.0
Bundle complete! 3 Gemfile dependencies, 21 gems now installed.
Use `bundle show [gemname]` to see where a bundled gem is installed.
$ 
$ cd my-awesome-site/
$ ls
about.md  _config.yml  Gemfile  Gemfile.lock  index.md  _posts
$ 

Jekyll va même vous permettre de démarrer un mini serveur web pour voir à quoi ressemble votre site :

$ bundle exec jekyll serve
$

il ne vous reste maintenant qu’à ouvrir un navigateur sur http://localhost:4000 pour parcourir le résultat.

Oui, je sais … C’est blanc. Pas de jolie image, pas de chaton, bref : c’est moche !

Pour que la magie opère, vous allez devoir apprendre le HTML, le CSS, un doigt de SEO et quelques autres infamies aux noms barbares. Sinon, vous pouvez aussi utiliser un thème !

Vous avez (vraiment) besoin d’un thème

Bon, les thèmes, sous Jekyll, c’est pas plug and play. C’est plutôt des sortes de templates de projets que vous pouvez cloner et adapter à vos besoins. Certains sont disponibles au travers de gem, d’autres doivent être clonés avec git: d’une manière générale, les thèmes jekyll sont plutôt faciles à trouver et à tester.

Vous pouvez en trouver ici, ici et . Attention, tous ne sont pas gratuits !

Celui que j’utilise sur codices.org s’appelle feeling responsive, par plow. Je le trouve vraiment classe pas vous ?

C’est tout ?

Oh non ! Définivement pas ! La documentation en ligne de jekyll est un passage obligatoire : elle est courte, bien écrite, et vous devriez trouver dedans tout ce dont vous pouvez avoir besoin pour commencer. Mon objectif dans cet article était de vous en donner un aperçu, mais vous aurez besoin de bien plus pour être vraiment prêt.

La documentation officielle est belle, elle est bonheur et source d’illumination et de joie. Va consulter la doc petit scarabée, va !

Notes

Quelques petites notes et commandes utiles en vrac, pour conclure. (Elles seront utiles au moins à votre serviteur)

  • Pour générer les pages web et déployer le site :
$ bundle exec jekyll build --destination /var/www/localhost/htdocs/
  • Idem, mais regénère dynamiquement le site à chaque fois qu’un fichier est modifié :
$ bundle exec jekyll build --watch --destination /var/www/localhost/htdocs/
  • Pour démarrer un serveur web local, avec une config spécifique pour tester le site :
$ bundle exec jekyll serve --config _config.yml,_config_dev.yml --watch
  • Pour prévisualiser les brouillons :
$ bundle exec jekyll serve --config _config.yml,_config_dev.yml --drafts --watch
  • Squelette d’un projet jekyll : (source)
.
├── _config.yml
├── _data
|   └── members.yml
├── _drafts
|   ├── begin-with-the-crazy-ideas.md
|   └── on-simplicity-in-technology.md
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2007-10-29-why-every-programmer-should-play-nethack.md
|   └── 2009-04-26-barcamp-boston-4-roundup.md
├── _sass
|   ├── _base.scss
|   └── _layout.scss
├── _site
├── .jekyll-metadata
└── index.html # can also be an 'index.md' with valid YAML Frontmatter
Fichier / Répertoire Description

_config.yml

Configuration générale du site

_drafts

Les brouillons (drafts) sont des articles en cours de rédaction. Le format de nom de ces fichiers ne comporte pas de date: title.MARKUP.

_includes

Ici sont rangés les morceaux de code ("partials") qui peuvent être appelés par les modèles et les articles pour faciliter la réutilisation de code. La balise Liquid {% include file.ext %} peut être utilisée dans ce but.

_layouts

Ici sont stockés les modèles ("layouts") qui mettent en forme les articles du blog. Les modèles de chaque article sont choisis au cas par cas dans l'entête YAML de l'article. La balise Liquid {{ content }} est utilisée afin d'injecter du contenu dans une page web.

_posts

Les articles de votre blog, aussi appelés posts. Le nom de fichier utilisé est important et doit obeir au format suivant : ANNEE-MOIS-JOUR-titre.MARKUP.

_data

Les données du site web peuvent être placées dans ce repertoire au format choisi. Le moteur Jekyll va automatiquement charger tous les fichiers de données de ce répertoire (en utilisant les formats et extensions suivantes :.yml, .yaml, .json ou .csv) et les rendre accessibles en tant que `site.date`. Par exemple, s'il y a un fichier members.yml dans ce repertoire, alors vous pouvez accéder à ses données au travers de site.data.members.

_sass

Encore des bouts de code, mais cette fois-ci en sass. Ceux là peuvent être importés dans votre main.scss qui sera ensuite transformé en une feuille de style unique : main.css. Tout ceci définit le style utilisé par votre blog.

_site

C'est ici que le site web généré va être placé ( par défaut ) lorsque Jekyll a fini de le générer. C'est probablement une très bonne idée d'ajouter ce répertoire à votre fichier .gitignore !

.jekyll-metadata

Ce fichier permet à Jekyll de garder une trace de quel fichier a été modifié depuis la dernière génération du site, et donc de savoir qu'il devra les recompiler la prochaine fois. Ce fichier ne sera pas inclus dans le site généré. C'est probablement une bonne idée de l'ajouter à votre fichier .gitignore .

index.html ou index.md et autres fichiers HTML, Markdown et text

Tant qu'un fichier possède une entête YAML, il sera transformé par Jekyll. Cela est également vrai pour n'importe quel fichier .html, .markdown, .md, ou .textile à la racine de votre site ou dans un repertoire non cité ici.

Autres fichiers et Répertoires

Tous les autres répertoires et fichiers seront copiés tels quels dans le site généré. Quelques exceptions toutefois : les repertoires css et images et le fichier favicon.ico .

Conclusion

Une dernière chose : vous trouverez pas mal de pages web sur Jekyll expliquant “Comment monter un blog en 8 secondes”. The cake is a lie. Personnellement, cela m’a pris une semaine à temps plein pour faire de codices.org ce que je voulais. Jekyll n’est en aucun cas magique et il vous faudra de la patience, du temps et du travail pour l’apprivoiser.

D’ailleurs, ce site est toujours en beta testing : si vous trouvez un bug, un truc mal foutu ou mal pensé, n’hésitez pas à me le faire savoir par Email ou sur twitter. Je suis preneur de retours pour améliorer tout ça !

Idem pour les fautes, coquilles et autres imperfections : les corrections orthographiques et grammaticales sont toujours les bienvenues.

Et bien, tout cela conclut donc ce premier post sur codices.org \o/

J’espère que cela vous a intéressé, même si c’était plutôt un premier test grandeur nature pour moi. A bientôt !

Seb

MISC
jekyll blog gentoo web

Dialogues & Discussions