• gulp : tous les fichiers de /src sont compilés dans /dist et ne sont ni minifiés ni concaténés. Le client peut modifier, améliorer et mettre en prod lui-même. (gulp est un alias de gulp build)
• gulp --prod : tous les fichiers de /src sont compilés dans /dist et sont - en plus - concaténés, minifiés, optimisés. Le client utilise tel quel ou doit recompiler lui-même.
• gulp watch : surveille styles, html, php (facultatif) et scripts.

Tâches secondaires

• gulp css : compile uniquement les fichiers Sass
• gulp js, gulp html, gulp php, gulp img, gulp fonts : toi-même tu sais
• gulp styleguide : création d'un guide de styles
• gulp doc-md : génère une documentation des sources JavaScript vers Markdown
• gulp doc-html : génère une documentation des sources JavaScript vers HTML
• gulp clean : suppression des fichiers inutiles en production
• gulp zip et gulp zip --prod : tâche build ou prod puis création d'une archive zip. Ex. projectName-build-2017-11-22-13h37.zip ou projectName-prod-2017-11-22-13h37.zip

Gérer les dépendances

Bretzel gère les dépendances directement via npm ou yarn (pas via Bower).

Pour ajouter une dépendance, il suffit de modifier le fichier package.json :

"dependencies": {
    "jquery": "^3.x", // dépendance npm
    "knacss": "7.x",
    "styledown-skins": "drakeh/styledown-skins" // dépendance de type GitHub
  },

Vos dépendances JavaScript pourront être listées dans le fichier gulpfile.js sous cette forme pour être concaténées aux autres :

var vendors = [
    paths.vendors + 'jquery/dist/jquery.min.js',
    paths.vendors + 'swiper/dist/js/swiper.min.js',
    paths.src + paths.scripts.files,
    '!' + paths.src + paths.scripts.styleguideFiles, // exclusion des JS spécifiques au styleguide de la liste construite précédemment
  ];

.editorconfig

Les règles d'indentation (espace / tabulation) sont configurées via le fichier .editorconfig à la racine du projet.

Pour qu'elles s'appliquent, il suffit généralement de télécharger le plugin "editorconfig" dans votre éditeur.

Css / Scss Lint

Note : stylelint est à présent utilisé de préférence à Sass-lint mais les modifications ne sont pas encore présentes dans Bretzel (vous pouvez prendre de l'avance via l'Issue GitHub).

Les fichiers Sass (.scss) de Bretzel sont rendus corrigés à l'aide d'un "linter" (outil de correction et bonnes pratiques) dont les règles sont configurées via le fichier .sass-lint.yml à la racine du projet.

L'action de correction se fera à l'aide de plugins au sein de votre éditeur HTML, ou bien d'une tâche Gulp. Par exemple, sur l'éditeur Atom, les plugins nécessaires sont Atom Linter et Atom Sass Lint.

Note : les warning subsistants dans le linter, sont connus et éventuellement à corriger selon les projets au cas par cas.

Architecture Bretzel

Voici comment est architecturé bretzel par défaut, mais rien ne vous empêche de modifier cette structure en changeant les variables présentes dans gulpfile.js :

Usage avec KNACSS

• Modifiez le fichier _variables.scss dans votre dossier src/assets/css/_config (c'est une copie modifiée de ./node_modules/knacss/sass/_config/_variables.scss. Ce dernier n'est pas utilisé car il est écrasé à chaque mise à jour de KNACSS)
• Choisissez les fichiers KNACSS à importer au sein du fichier src/assets/css/knacss.scss
• Votre fichier de travail est styles.scss et commencera par l'import des 2 fichiers de configuration de KNACSS _config/_variables et _config/_mixins puis par @import "knacss"; (ce dernier ne réimporte pas les 2 premiers _partials ; ils y sont commentés), puis suivront vos styles perso.

Documentation

• Bretzel utilise gulp-documentation basé sur http://documentation.js.org/ pour pouvoir générer une documentation au format HTML ou Markdown selon les blocs de commentaires JSDoc placés dans les fichiers JavaScript.
• La syntaxe est décrite dans la documentation de documentation https://github.com/documentationjs/documentation/blob/master/docs/GETTING_STARTED.md
• Avec l'éditeur Atom, le package https://atom.io/packages/docblockr est conseillé.