Skip to content

Latest commit

 

History

History
80 lines (52 loc) · 4.03 KB

README.md

File metadata and controls

80 lines (52 loc) · 4.03 KB
Raw

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

Setup

  • Install ruby : sudo apt install ruby
  • Install jekyll : sudo gem install jekyll jekyll-feed jekyll-gist jekyll-paginate jekyll-sass-converter jekyll-coffeescript
  • Install plantuml and a plantuml command in the PATH (requirement of jekyll-plantuml) (and probably dot : sudo apt install graphviz for Debian systems)
  • Install make then run make setup (or look into Makefile for the underlying commands)

Assets/blog folder

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

It keeps the same layout as the previous website 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 the following to update Ruby gems & and start a local server with automatic reload and drafts preview :

make serve

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

Drafts don't appear in the RSS feed, as this would trigger false updates until the article is ready for release (the publication date would change all the time). The current workaround is to put those articles in a preposts collection until ready.

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 :

Publishing

  1. Build the final site without drafts :
make build
  1. 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.