Choucroute, knacks, et picon bière
Bretzel (Bretzel Project Starter) est une base de départ pour des projets HTML / CSS et JS créée par l'agence Alsacréations.
Bretzel est configuré pour fonctionner dans un environnement axé sur les outils Gulp, Sass et KNACSS (v7). Des connaissances minimales de ces outils sont un pré-requis.
src/home.html
favicon.ico
, .htaccess
et autres fichiers .txt
présents à la racine.zip
de build ou de production.editorconfig
permettant d'assurer une cohérence dans les conventions d'indentations.sass-lint.yml
de configuration pour outils de Linter .scss
Récupérez ce repo, soit :
git clone https://github.com/alsacreations/bretzel
À la racine de votre dossier de projet :
npm install
ou yarn
pour installer automatiquement les plugins et dépendances nécessaires qui sont listées dans package.json
,npm i -g gulp gulp-cli
,gulp
pour générer le dossier de destination /dist
.Note : en production, npm install --production
n'installera que les dépendances requises et non les dépendances de développement local (devDependencies
).
Compilez vos fichiers avec gulp
pour les tâches de base, ou surveillez les fichiers dans votre projet avec gulp watch
pour relancer les tâches de base lorsqu'ils sont modifiés. Voir ci-après pour les tâches détaillées.
gulp
ou gulp build
: tous les fichiers de /src
sont compilés dans /dist
mais ne sont ni minifiés ni concaténés. Le destinataire de ces fichiers peut modifier, améliorer et mettre en production lui-même.gulp --prod
: tous les fichiers de /src
sont compilés dans /dist
et sont en plus concaténés, minifiés, optimisés. Le destinataire de ces fichiers les utilise tel quel ou peut recompiler lui-même.gulp watch
: surveille styles, html, php (facultatif) et scripts.gulp css
: compile uniquement les fichiers Sassgulp js
, gulp html
, gulp php
, gulp img
, gulp fonts
: toi même tu saisgulp styleguide
: création d'un guide de stylesgulp doc-md
: génère une documentation des sources JavaScript vers Markdowngulp doc-html
: génère une documentation des sources JavaScript vers HTMLgulp clean
: suppression des fichiers inutiles en productiongulp zip
et gulp zip --prod
: crée une archive compressée et datée du projet en exécutant build
ou prod
puis archive
. Par exemple projectName-build-2019-01-21-13h37.zip
ou projectName-prod-2019-01-21-13h37.zip
gulp s3
: publie sur Amazon Web Services (AWS) S3, voir détails plus loinBretzel 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
ou d'utiliser les commandes npm install --save-dev
:
"dependencies": {
"jquery": "^3.x",
"knacss": "7.x",
"styledown-skins": "drakeh/styledown-skins"
},
Dans cet exemple jQuery est une dépendance npm et styledown-skins 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
];
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.
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.
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
:
_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 utlisé car il est écrasé à chaque mise à jour de KNACSS)src/assets/css/knacss.scss
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 personnalisés.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é.
Pour publier les fichiers compilés vers Amazon Web Services S3 (Simple Storage Service) en une seule commande, par exemple pour héberger un site statique ou front-end, utiliser le module gulp-awspublish.
Installation (non prévue par défaut dans package.json
) :
npm install --save-dev gulp-awspublish
Les dossiers et droits doivent être configurés au préalable côté AWS (via les services S3+IAM) pour donner les capacités d'écriture/upload :
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1564418715000",
"Effect": "Allow",
"Action": [
"s3:*"
],
"Resource": [
"arn:aws:s3:::www.hopla.com",
"arn:aws:s3:::www.hopla.com/*"
]
}
]
}
aws-credentials.json
dans le projet (à la racine, en plus de gulpfile.js
){
"params": {
"Bucket": "<nom_du_bucket_S3>"
},
"accessKeyId": "<aws_access_key>",
"secretAccessKey": "<aws_secret_key>",
"region":"<code_region>"
}
Le code région est celui donné par la région hébergeant le bucket S3. Par exemple eu-central-1
pour Francfort.
Lancement de la synchronisation : gulp s3
(va utiliser tous les fichiers dans /dist/
par défaut si c'est le chemin configuré dans les variables paths
). Il est possible de définir dans quel sous-dossier du bucket envoyer les fichiers, et d'ignorer certains types. Pour ceci modifier gulpfile.js
.
Voir le Changelog
Projet lancé par Matthieu Bousendorfer, et tenu à jour par Alsacréations.
GitIgnore Mac OSX Crap : https://github.com/github/gitignore/blob/master/Global/OSX.gitignore