Source code for https://www.nicolabs.net

Setup

• Install jekyll
• Install plantuml and a plantuml command in the PATH (requirement of jekyll-plantuml) (and probably dot : apt install graphviz)
• Run bundle install

Assets/blog folder

The assets/blog folder gathers asset files used in articles.

It keeps the same layout as the previous wesite located from http://www.nicobo.net/sites/default/files in order to ease migration of URLs, but the pictures subfolder may not be used for new assets.

The new layout is :

3rdparty/       # local copy of remote pictures, some modified (e.g. resized)
    \_ logos/   # icons & logos of third party products
    \_ images/  # photos & pictures taken from external sources
screenshots/    # screen captures or alike used to illustrate some articles

Previewing locally

Run bundle exec jekyll serve --livereload -H '*' --drafts to start a local server with automatic reload and drafts preview.

Drafts

Jekyll drafts (articles in _drafts/) are absolutely not ready for publication. Some of them are still old documents I've never finished... On the other hand, articles tagged with draft (in _posts/) are published with a special mention so that they hopefully can be useful to anybody : old drafts are slowly being published with this draft mention. There are other mentions (unpublished, draft, good, stable, deprecated) to indicate articles' maturity.

See Migrating from Drupal to Jekyll for the explanation. Most of the code lies in _includes/maturity.html and _sass/nicolabs/*.scss in order to :

• display the maturity label in each article's header
• advertise unstable articles in indexes (index.html, tags.html)
• remove drafts from the default feed

Fullscreen pictures & PlantUML diagrams

I found it to be necessary to better display PlantUML diagrams.

This is implemented with :

• a modified version of jekyll-plantuml
  • because it is the Jekyll integration advertized on plantuml.com
  • however it generates only <svg> inside <object>, which is not fullscreen-compatible OOTB => I replaced with <img> using the generated SVG as source
  • and it generated files in the root of the project
  • TODO anyway a replacement that uses Markdown standard ```plantuml rather than Jekyll-specific {% plantuml %} syntax should be found
• assets/lib/screenfull.js polyfill (seen at Modernizr) and a few lines of code to activate it
• very few CSS

Based on :

• https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API
• https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API/Guide
• https://caniuse.com/#feat=fullscreen
• https://developer.mozilla.org/fr/docs/Apprendre/HTML/Comment/Ajouter_des_images_vectorielles_%C3%A0_une_page_web

Publishing

1. Update Ruby gems & build the final site without drafts :

   bundle update bundle exec jekyll build

2. Add, commit & push files into the master git branch, including the docs directory (same as Jekyll's _site directory, but renamed for github pages)

See Bypassing GitHub's Jekyll limitations for more informations.