Mon md converti avec Pandoc

Publié paradminBlog Laisser un commentaire sur Mon md converti avec Pandoc

Pre-requis :

Passer le tout en mode décompressé sans cache et en twig debug :

Suivre les indication de SI1A sur le site INEA:

On copie le starterKit SASS dans la partie custom dans un nouveau thème custom (bofip_themes/bofip_bootstrap_sass) :

jpmena@jpmena-HP-ProDesk-600-G2-MT:/var/www/bofiptest/web/themes/contrib/bootstrap/starterkits$ cp -pvr sass /var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass
'sass' -> '/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass'
'sass/templates' -> '/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass/templates'
………………………………………………………………...
'sass/scss/style.scss' -> '/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass/scss/style.scss'
'sass/scss/jquery-ui' -> '/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass/scss/jquery-ui'
'sass/scss/jquery-ui/_autocomplete.scss' -> '/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass/scss/jquery-ui/_autocomplete.scss'
'sass/scss/_overrides.scss' -> '/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass/scss/_overrides.scss'

Les noms de fichiers :

On a renommé les 3 fichiers :

  • cf. les commentaires dans le listage du répertoire
jpmena@jpmena-HP-ProDesk-600-G2-MT:/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass$ ll
total 424
drwxr-xr-x 7 jpmena www-data   4096 févr. 12 10:37 ./
drwxrwsr-x 7 jpmena www-data   4096 févr.  2 15:28 ../
# on a renommé THEMENAME.starterkit.yml
-rwxr-xr-x 1 jpmena www-data    614 févr.  2 16:11 bofip_bootstrap_sass.info.yml*
# on a renommé THEMENAME.libraries.yml
-rwxr-xr-x 1 jpmena www-data    777 janv. 20 07:14 bofip_bootstrap_sass.libraries.yml*
# on a renommé THEMENAME.theme
-rwxr-xr-x 1 jpmena www-data     95 janv. 20 07:14 bofip_bootstrap_sass.theme*
drwxr-xr-x 4 jpmena www-data   4096 janv. 20 07:14 config/
drwxrwxr-x 2 jpmena jpmena     4096 févr. 12 09:21 docs/
-rwxr-xr-x 1 jpmena www-data   1150 janv. 20 07:14 favicon.ico*
drwxr-xr-x 2 jpmena www-data   4096 janv. 20 07:14 images/
-rwxr-xr-x 1 jpmena www-data   1295 janv. 20 07:14 logo.svg*
-rwxr-xr-x 1 jpmena www-data   2687 janv. 20 07:14 README.md*
-rw-r--r-- 1 jpmena www-data 378677 févr.  2 16:57 screenshot.png
drwxr-xr-x 4 jpmena www-data   4096 janv. 20 07:14 scss/
drwxr-xr-x 2 jpmena www-data   4096 janv. 20 07:14 templates/

On a renommé également les 2 fichiers du sous-répertoire config :

  • cf. les commentaires dans le listage des répertoires
# on renomme THEMENAME.schema.yml cf ci dessous
pmena@jpmena-HP-ProDesk-600-G2-MT:/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass$ ll config/schema/
total 12
drwxr-xr-x 2 jpmena www-data 4096 févr.  2 16:12 ./
drwxr-xr-x 4 jpmena www-data 4096 janv. 20 07:14 ../
-rwxr-xr-x 1 jpmena www-data  171 févr.  2 17:52 bofip_bootstrap_sass.schema.yml*
# on renomme THEMENAME.settings.yml cf ci dessous
jpmena@jpmena-HP-ProDesk-600-G2-MT:/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass$ ll config/install/
total 12
drwxr-xr-x 2 jpmena www-data 4096 févr.  2 16:12 ./
drwxr-xr-x 4 jpmena www-data 4096 janv. 20 07:14 ../
-rwxr-xr-x 1 jpmena www-data  749 janv. 20 07:14 bofip_bootstrap_sass.settings.yml*

Adaptations du contenu de certains fichiers :

Le contenu du fichier bofip_bootstrap_sass.info.yml …

  • cf. les commentaires que j’ai ajoutés
core: 8.x
type: theme
base theme: bootstrap

# changement du name et de description pour proposer
# quelque code de parlant à l'interface d'administration
name: 'BOFIP SASS'
description: 'Thème BOFIP basé les sur le Kit BootStrap3/SASS - https://github.com/twbs/bootstrap-sass (not for beginners).'
package: 'Bootstrap'

regions:
  navigation: 'Navigation'
  navigation_collapsible: 'Navigation (Collapsible)'
  header: 'Top Bar'
  highlighted: 'Highlighted'
  help: 'Help'
  content: 'Content'
  sidebar_first: 'Primary'
  sidebar_second: 'Secondary'
  footer: 'Footer'
  page_top: 'Page top'
  page_bottom: 'Page bottom'

# changement de THEMENAME à bofip_inea_sass (nom actuel de mon thème)
##  pour les références ci dessous !!!
libraries:
  - 'bofip_bootstrap_sass/global-styling'
  - 'bofip_bootstrap_sass/bootstrap-scripts'
  
core: 8.x
type: theme
base theme: bootstrap

Le contenu du fichier config/schema/bofip_bootstrap_sass …

# Schema for the theme setting configuration file of the THEMETITLE theme.
## changer le label ci dessous ('THEMETITLE settings' dans le Kis SASS) pour un label unique sur tous les projets drupal embarqués par mon instance
# Schema for the theme setting configuration file of the THEMETITLE theme.

bofip_bootstrap_sass.settings:
  type: theme_settings
  label: 'bofip_bootstrap_sass settings'

Ajouter les librairies Booststrap SASS

Ressources

Placement des sources Booststrap SASS

# on détarre l'archive Github au bon endroit
jpmena@jpmena-HP-ProDesk-600-G2-MT:/var/www/bofiptest/web/themes/custom$ tar xf bootstrap-sass-3.3.7.tar.gz -C bofip_themes/bofip_bootstrap_sass/
# on renomme le répertoire
jpmena@jpmena-HP-ProDesk-600-G2-MT:/var/www/bofiptest/web/themes/custom$ cd bofip_themes/bofip_bootstrap_sass/
jpmena@jpmena-HP-ProDesk-600-G2-MT:/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass$ mv -v bootstrap-sass-3.3.7 bootstrap
'bootstrap-sass-3.3.7' -> 'bootstrap'

Sources javascript

  • Le fichier bofip_bootstrap_sass/bofip_bootstrap_sass.libraries.yml fait référence aux sources javascript de Bootstrap à travers le chemin relatif: bootstrap/assets/javascripts/bootstrap
bootstrap-scripts:
  js:
    bootstrap/assets/javascripts/bootstrap/affix.js: {}
    bootstrap/assets/javascripts/bootstrap/alert.js: {}
    bootstrap/assets/javascripts/bootstrap/button.js: {}
    bootstrap/assets/javascripts/bootstrap/carousel.js: {}
    bootstrap/assets/javascripts/bootstrap/collapse.js: {}
    bootstrap/assets/javascripts/bootstrap/dropdown.js: {}
    bootstrap/assets/javascripts/bootstrap/modal.js: {}
    bootstrap/assets/javascripts/bootstrap/tooltip.js: {}
    bootstrap/assets/javascripts/bootstrap/popover.js: {}
    bootstrap/assets/javascripts/bootstrap/scrollspy.js: {}
    bootstrap/assets/javascripts/bootstrap/tab.js: {}
    bootstrap/assets/javascripts/bootstrap/transition.js: {}
  • noter que l’ajout de ces fichiers Javascripts suppose la présence de la librairie Bootstrap.js qui, si elle n’est pas à récupérer du CDN peut se faire localement grâce au projet Bootstrap Library

Sources SASS:

  • Le répertoire récupéré du KIT SASS ne vient pas vide:
jpmena@jpmena-HP-ProDesk-600-G2-MT:/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass$ ll scss
total 28
drwxr-xr-x 4 jpmena www-data 4096 janv. 20 07:14 ./
drwxr-xr-x 8 jpmena www-data 4096 févr. 12 13:40 ../
drwxr-xr-x 2 jpmena www-data 4096 janv. 20 07:14 component/
-rw-r--r-- 1 jpmena www-data  542 janv. 20 07:14 _default-variables.scss
drwxr-xr-x 2 jpmena www-data 4096 janv. 20 07:14 jquery-ui/
-rw-r--r-- 1 jpmena www-data 1254 janv. 20 07:14 _overrides.scss
-rw-r--r-- 1 jpmena www-data  176 janv. 20 07:14 style.scss

le fichier principal scss/style.scss

  • c’est le fichier SASS principal:
    • Il inclue *_default-variables.scss* et *_overrides.scss* (cf. contenu ci après)
// Default variables.
@import "default-variables";

// Bootstrap Framework.
@import '../bootstrap/assets/stylesheets/bootstrap';

// Base-theme overrides.
@import 'overrides';
  • on voit qu’il inclue les source sass de bootstrap (cf. placement juste ci dessus des sources bootstrap), le fichier _bofip_bootstrap_sass/bootstrap/assets/stylesheets/bootstrap.scss fait appel par défaut à toutes les ressources sass bootstrap:
    • La difficulté sera dans un second temps (quand le projet sera plus avancé) de définir un tel fichier *scss/_booststrap.scss* dans nos sources scss ramené aux imports minimaux !!!
    • et de l’inclure dans notre scss/style.scss en lieu et place de *bootstrap/assets/stylesheets/_bootstrap.scss*
/*!
 * Bootstrap v3.3.7 (http://getbootstrap.com)
 * Copyright 2011-2016 Twitter, Inc.
 * Licensed under MIT (https://github.com/twbs/bootstrap/blob/master/LICENSE)
 */

// Core variables and mixins
@import "bootstrap/variables";
@import "bootstrap/mixins";

// Reset and dependencies
@import "bootstrap/normalize";
@import "bootstrap/print";
@import "bootstrap/glyphicons";

// Core CSS
@import "bootstrap/scaffolding";
@import "bootstrap/type";
@import "bootstrap/code";
@import "bootstrap/grid";
@import "bootstrap/tables";
@import "bootstrap/forms";
@import "bootstrap/buttons";

// Components
@import "bootstrap/component-animations";
..................................
@import "bootstrap/wells";
@import "bootstrap/close";

// Components w/ JavaScript
@import "bootstrap/modals";
@import "bootstrap/tooltip";
@import "bootstrap/popovers";
@import "bootstrap/carousel";

// Utility classes
@import "bootstrap/utilities";
@import "bootstrap/responsive-utilities";
  • Le fichier scss/style.scss est le fichier que l’outillage va compiler en css/style.css
    • en effet bofip_bootstrap_sass/bofip_bootstrap_sass.libraries.yml y fait référence (cf. contenu ci après):
global-styling:
  css:
    theme:
      css/style.css: {} # c'est le fichier résultant de la compilation de scss/style.scss

le fichier *scss/_default-variables.scss*

  • Il est importé par style.scss et doit :
  • permettre de redéfinir les variables présentes sous *../bootstrap/assets/stylesheets/bootstrap/_variables.scss*
    • les variables de ce fichier sont sufixées par !default;
    • ce qui signifie qu’elles s’imposent uniquement si elle n’ont pas été défini auparant (sans le !default; bien sûr)!!!
    • c’est à ce niveau qu’intervient notre fichier *scss/_default-variables.scss*
  • Un exemple de son usage nous est donné dans le contenu livré par le KitSASS:

« scss /** * Default Variables. * * Modify this file to provide default Bootstrap Framework variables. The * Bootstrap Framework will not override any variables defined here because it * uses the!default` flag which will only set their default if not already * defined here. You can copy existing variables directly from the following file: * ./THEMENAME/bootstrap/assets/stylesheets/bootstrap/_variables.scss */

// Set the proper directory for the Bootstrap Glyphicon font. $icon-font-path: ‘../bootstrap/assets/fonts/bootstrap/’; « `

le fichier *scss/_overrides.scss*

  • Il est importé par style.scss et est chargé
    • d’apporter la customisation Bootstrap par rapport aux spécificités de Drupal 8
  • Il n’est pas vide et son contenu fait appel aux fichiers sass présents sous scss/component

mise en place de l’outillage SASS / Gulp

Prérequis: installation d’un compilateur SASS

# installation du paquet ruby-sass par apt 
## il installe autmatiquement ruby et les Gem qui vont bien pour la compilation SASS
jpmena@jpmena-HP-ProDesk-600-G2-MT:~$ sudo apt install ruby-sass
[sudo] Mot de passe de jpmena : 
...................
# on vérifie
jpmena@jpmena-HP-ProDesk-600-G2-MT:~$ sass --version
Sass 3.4.21 (Selective Steve)
jpmena@jpmena-HP-ProDesk-600-G2-MT:~$ whereis sass
sass: /usr/bin/sass /usr/share/man/man1/sass.1.gz
jpmena@jpmena-HP-ProDesk-600-G2-MT:~$ ll /usr/bin/sass
-rwxr-xr-x 1 root root 142 janv. 25  2016 /usr/bin/sass*
  • /usr/bin/sass est un script Ruby !!!
#!/usr/bin/ruby
# The command line Sass parser.

require 'sass'
require 'sass/exec'

opts = Sass::Exec::SassScss.new(ARGV, :sass)
opts.parse!

Prérequis NodeJS/npm présents sur le poste:

Installation de la dernière version Node JS/npm

  • Télécharger la dernière version Node JS/Npm
  • La détarer et ajouter le répertoire des binaires dans le PATH Linux
    • et on teste la prise en compte !!!

bash # je l'ai téléchargé dans un sous-répertoire Ateliers de mon $HOME jpmena@jpmena-HP-ProDesk-600-G2-MT:~/Ateliers$ ls -ltr | tail -1 -rw-rw-r-- 1 jpmena jpmena 11410120 févr. 13 08:02 node-v8.9.4-linux-x64.tar.xz # On dé-tare jpmena@jpmena-HP-ProDesk-600-G2-MT:~/Ateliers$ tar xf node-v8.9.4-linux-x64.tar.xz # on ajoute le chemin du répertoire des binaires node et npm dans le PATH jpmena@jpmena-HP-ProDesk-600-G2-MT:~$ tail -3 .profile # set PATH so it includes user's private bin directories NODE_HOME=$HOME/Ateliers/node-v8.9.4-linux-x64 PATH="$NODE_HOME/bin:$HOME/bin:$HOME/.local/bin:$PATH" # On teste la prise en compte de ce chemin ## on active la nouvelle configuration jpmena@jpmena-HP-ProDesk-600-G2-MT:~$ source .profile ## On vérifie la version de Node jpmena@jpmena-HP-ProDesk-600-G2-MT:~$ node --version v8.9.4 ## On vérifie la version de npm jpmena@jpmena-HP-ProDesk-600-G2-MT:~$ npm --version 5.6.0

installation du client Gulp

  • La page d’accueil du projet Gulp nous présente un écran avec les 4 commandes à passer
# Installation du client Gulp (global '-g' à mon utilisateur) 
jpmena@jpmena-HP-ProDesk-600-G2-MT:~$ npm install gulp-cli -g
/home/jpmena/Ateliers/node-v8.9.4-linux-x64/bin/gulp -> /home/jpmena/Ateliers/node-v8.9.4-linux-x64/lib/node_modules/gulp-cli/bin/gulp.js
+ gulp-cli@2.0.1
added 244 packages in 12.06s
# vérification
jpmena@jpmena-HP-ProDesk-600-G2-MT:~$ gulp --version
[08:17:32] CLI version 2.0.1
#liste des commandes gulp disponibles:
jpmena@jpmena-HP-ProDesk-600-G2-MT:~$ gulp --help

Usage: gulp [options] tasks

Options:
  --help, -h              Show this help.                              [booléen]
  --version, -v           Print the global and local gulp versions.    [booléen]
  --require               Will require a module before running the gulpfile.
                          This is useful for transpilers but also has other
                          applications.                    [chaine de caractère]
  --gulpfile, -f          Manually set path of gulpfile. Useful if you have
                          multiple gulpfiles. This will set the CWD to the
                          gulpfile directory as well.      [chaine de caractère]
  --cwd                   Manually set the CWD. The search for the gulpfile, as
                          well as the relativity of all requires will be from
                          here.                            [chaine de caractère]
  --verify                Will verify plugins referenced in project's
                          package.json against the plugins blacklist.
  --tasks, -T             Print the task dependency tree for the loaded
                          gulpfile.                                    [booléen]
  --tasks-simple          Print a plaintext list of tasks for the loaded
                          gulpfile.                                    [booléen]
  --tasks-json            Print the task dependency tree, in JSON format, for
                          the loaded gulpfile.
  --tasks-depth, --depth  Specify the depth of the task dependency tree.[nombre]
  --compact-tasks         Reduce the output of task dependency tree by printing
                          only top tasks and their child tasks.        [booléen]
  --sort-tasks            Will sort top tasks of task dependency tree. [booléen]
  --color                 Will force gulp and gulp plugins to display colors,
                          even when no color support is detected.      [booléen]
  --no-color              Will force gulp and gulp plugins to not display
                          colors, even when color support is detected. [booléen]
  --silent, -S            Suppress all gulp logging.                   [booléen]
  --continue              Continue execution of tasks upon failure.    [booléen]
  --series                Run tasks given on the CLI in series (the default is
                          parallel).                                   [booléen]
  --log-level, -L         Set the loglevel. -L for least verbose and -LLLL for
                          most verbose. -LLL is default.              [comptage]

Création d’une GulpFile à la racine de notre thème

  • On reprend du GulpFile.js du projet INEA la partie spécifique à la compilation SASS
    • On laisse de côté la génération KSS (documentation automatique des composants Bootstrap de la charte)
    • Dans ce projet les répertoire js, fonts et css sont dans un sour répertoire dist
      • on adapte le fichier _*.libraries.yml_ « `yaml global-styling: css: theme: dist/css/style.css: {}

bootstrap-scripts: js: bootstrap/assets/javascripts/bootstrap/affix.js: {} bootstrap/assets/javascripts/bootstrap/alert.js: {} bootstrap/assets/javascripts/bootstrap/button.js: {} bootstrap/assets/javascripts/bootstrap/carousel.js: {} bootstrap/assets/javascripts/bootstrap/collapse.js: {} bootstrap/assets/javascripts/bootstrap/dropdown.js: {} bootstrap/assets/javascripts/bootstrap/modal.js: {} bootstrap/assets/javascripts/bootstrap/tooltip.js: {} bootstrap/assets/javascripts/bootstrap/popover.js: {} bootstrap/assets/javascripts/bootstrap/scrollspy.js: {} bootstrap/assets/javascripts/bootstrap/tab.js: {} bootstrap/assets/javascripts/bootstrap/transition.js: {} « ` * on adapte aussi le fichier .gitignore pour exclure le répertoire dist des sources

création d’un package.json qui permet de charger les bibliothèques dont Gulp a besoin

  • on initialise un fichier package.json
jpmena@jpmena-HP-ProDesk-600-G2-MT:/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass$ npm init
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

See `npm help json` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg>` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
package name: (bofip_bootstrap_sass) #on répond aux différentes questions (souvent valeurs par défaut) 
.......
  • Ajout des librairies qui sont appelées (required) par le fichier gulpfile.js:
    • on passe les commandes npm require qui vont bien
# on installe gulp et le mémorise dans les dépendances de développement
jpmena@jpmena-HP-ProDesk-600-G2-MT:/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass$ npm install gulp --save-dev
......................................

+ gulp@3.9.1
added 274 packages in 11.468s
# on installe l'interfaces sass pour gulp et le mémorise dans les dépendances de développement
jpmena@jpmena-HP-ProDesk-600-G2-MT:/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass$ npm install gulp-sass --save-dev
............................................................
+ gulp-sass@3.1.0
added 173 packages in 11.924s
# on installe l'interfaces sass gulp-sourcemap et le mémorise dans les dépendances de développement
jpmena@jpmena-HP-ProDesk-600-G2-MT:/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass$ npm install gulp-sourcemaps --save-dev
.........................
+ gulp-sourcemaps@2.6.4
added 30 packages in 4.898s
  • le résultat dans mon cas est un fichier package.json à la racine de mon thème et qui contient
    • Pour réinstaller toutes les librairies nécessaires à partir de ce fichier un npm install sera suffisant
{
  "name": "bofip_bootstrap_sass",
  "version": "0.0.1",
  "description": "Compilation des assets",
  "main": "gulpfile.js",
  "directories": {
    "doc": "docs"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "gulp",
    "sass"
  ],
  "author": "JPmena",
  "license": "ISC",
  "devDependencies": {
    "gulp": "^3.9.1",
    "gulp-sass": "^3.1.0",
    "gulp-sourcemaps": "^2.6.4"
  }
}
  • on adapte aussi le fichier .gitignore pour exclure le répertoire node_modules des sources

lancement de la compilation

  • Lancement de la tâche css
jpmena@jpmena-HP-ProDesk-600-G2-MT:/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass$ gulp css
[10:53:09] Using gulpfile /var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass/gulpfile.js
[10:53:09] Starting 'css'...
[10:53:09] Finished 'css' after 219 ms
  • on a bien un répertoire créé dist/css qui n’existait pas avant
    • bien sûr, dist fait partie du .gitignore !!!
jpmena@jpmena-HP-ProDesk-600-G2-MT:/var/www/bofiptest/web/themes/custom/bofip_themes/bofip_bootstrap_sass$ ls -ltr dist/css/
total 588
-rw-rw-r-- 1 jpmena jpmena 433069 févr. 13 10:53 style.css.map
-rw-rw-r-- 1 jpmena jpmena 166192 févr. 13 10:53 style.css

compilation manuelle

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *