Démarrer un projet

Guide complet pour installer le framework Beely Framework, créer un site, et le mettre en ligne.

Vocabulaire

Avant de commencer, voici les termes que vous allez rencontrer. Pas besoin de tout retenir — revenez ici si un mot vous bloque.

Installer le framework

Comment ouvrir un terminal ?

Toutes les commandes de cette page se tapent dans un terminal (ligne de commande). Voici comment l'ouvrir :

• Sur Mac : ouvrez l'application Terminal (dans Applications → Utilitaires) ou tapez terminal dans Spotlight (Cmd+Espace)
• Dans VSCode : menu Terminal → Nouveau terminal, ou le raccourci Ctrl+` (touche backtick, en haut à gauche du clavier)
• Sur Windows : ouvrez PowerShell ou Git Bash

Le terminal VSCode est pratique car il s'ouvre directement dans le dossier de votre projet.

D'où partez-vous ?

Choisissez le scénario qui correspond à votre situation :

Scénario A — Partir de zéro (aucun projet)

C'est le cas le plus simple. Trois options s'offrent à vous :

Option 1 — Script automatique init-project.sh (recommandé)

Une seule commande qui fait tout : clone le template, crée les symlinks, configure .env, .deploy.env et config-site.js, crée le repo GitHub, injecte les secrets GitHub Actions, teste la connexion SSH et déploie en préprod.

Pré-requis : avoir créé les domaines (prod + préprod) sur l’hébergeur, et avoir gh CLI installé.

Mode interactif (le script pose toutes les questions) :

cd ~/Sites
curl -sO https://raw.githubusercontent.com/TheoRoces/beely-template/main/init-project.sh
bash init-project.sh

Mode CLI (une seule commande, idéal pour l’automatisation) :

cd ~/Sites

curl -sO https://raw.githubusercontent.com/TheoRoces/beely-template/main/init-project.sh
bash init-project.sh \
  client=nom-du-projet \
  repo_owner=MonUsernameGitHub \
  ssh_port=65002 \
  prod_url=https://nom-du-projet.fr \
  prod_host=ADRESSE_IP_SERVEUR \
  prod_user=UTILISATEUR_SSH \
  prod_path=/home/UTILISATEUR_SSH/domains/nom-du-projet.fr/public_html/ \
  preprod_url=https://preprod.nom-du-projet.fr \
  preprod_host=ADRESSE_IP_SERVEUR \
  preprod_user=UTILISATEUR_SSH \
  preprod_path=/home/UTILISATEUR_SSH/domains/preprod.nom-du-projet.fr/public_html/ \
  baserow_token=VOTRE_TOKEN \
  baserow_table_id=VOTRE_TABLE_ID \
  site_name="Restaurant Le Gourmet" \
  ga4=G-ABC123XYZ9 \
  clarity=abcdef1234 \
  company="Le Gourmet SARL" \
  legal_form="SARL" \
  siret="987 654 321 00012" \
  registration="RCS Lyon" \
  representative="Pierre Martin" \
  legal_address="42 rue de la Gastronomie, 69001 Lyon" \
  legal_phone="+33 6 00 00 00 00" \
  legal_email=contact@legourmet.fr \
  hosting_name=Hostinger \
  hosting_url=https://www.hostinger.fr \
  dev_name="Beely Studio" \
  dev_url=https://beely.studio

Le script affiche un résumé, valide les paramètres (URLs, SIRET, email, connexion Baserow) et demande confirmation avant de lancer. Options disponibles : --help, --dry-run, --no-deploy, --no-github.

Astuce : si vous n’avez pas gh, le script vous guidera pour créer le repo manuellement sur GitHub.

Option 2 — Téléchargement direct (sans terminal)

Cliquez sur l'icône dans le header de cette page, ou utilisez ce lien :

Télécharger beely-template

1. Décompressez l'archive ZIP dans votre dossier de projets (ex : ~/Sites/)
2. Renommez le dossier beely-template-main en mon-projet
3. Ouvrez-le dans VSCode et lancez ./setup.sh --init dans le terminal intégré

Note : Le téléchargement ZIP ne contient pas le submodule .framework/. Le script setup.sh --init le téléchargera automatiquement pour vous.

Option 3 — Cloner avec Git (manuel)

Si vous avez Git installé, c'est la méthode recommandée car elle récupère tout en une commande :

# 💻 Terminal : Terminal.app (Mac) ou terminal VSCode
# 📂 Dossier : là où vous rangez vos sites (ex: ~/Sites/)

cd ~/Sites
git clone --recursive https://github.com/TheoRoces/beely-template.git mon-projet
cd mon-projet

L'option --recursive est importante : elle télécharge aussi le framework (submodule .framework/) en même temps.

Étape 2 — Lancer le setup

# 📂 Dossier : ~/Sites/mon-projet/ (la racine du projet)

./setup.sh --init

Ce script crée les symlinks (raccourcis) qui relient votre projet au framework. Il copie aussi les fichiers .env.example pour que vous puissiez les remplir.

Étape 3 — Ouvrir dans VSCode

# 📂 Dossier : ~/Sites/mon-projet/

code .

Ou bien : ouvrez VSCode, puis Fichier → Ouvrir un dossier et sélectionnez mon-projet.

Étape 4 — Personnaliser

Passez à la section Personnaliser le site ci-dessous.

Scénario B — Projet quasi vierge (index.html + quelques fichiers)

Vous avez déjà un projet avec un index.html et peut-être quelques fichiers CSS/JS, mais pas de structure complète. Vous voulez y ajouter le framework.

Étape 1 — Initialiser git (si pas déjà fait)

# 💻 Terminal : terminal VSCode (Ctrl+`)
# 📂 Dossier : la racine de votre projet (là où se trouve votre index.html)

git init
git add -A
git commit -m "Initial commit"

Si votre projet est déjà un dépôt git, passez cette étape.

Étape 2 — Ajouter le framework comme submodule

# 📂 Dossier : la racine de votre projet

git submodule add https://github.com/TheoRoces/beely-framework.git .framework

Cela crée un dossier .framework/ contenant tout le framework (CSS, JS, composants, icônes, configurateur, etc.).

Étape 3 — Créer les symlinks

Vous pouvez copier le script setup.sh depuis le template GitHub et l'exécuter, ou créer les symlinks manuellement :

# 📂 Dossier : la racine de votre projet

ln -s .framework/core core
ln -s .framework/api api
ln -s .framework/snippets snippets
ln -s .framework/configurateur configurateur

# Assets : symlinks pour icons/fonts, dossier images propre au projet
mkdir -p assets/images
ln -s ../.framework/assets/icons assets/icons
ln -s ../.framework/assets/fonts assets/fonts

# Composants : dossier vide (ajouter selon les besoins via snippets VSCode ou .framework/snippets/components/)
mkdir -p components
touch components/.gitkeep

cd pages && ln -s ../.framework/base-index.html base-index.html && cd ..
ln -s .framework/robots.txt robots.txt
ln -s .framework/generate-sitemap.js generate-sitemap.js

Étape 4 — Créer le fichier de configuration

Créez un fichier config-site.js à la racine de votre projet. Copiez le contenu depuis le template ou créez-le manuellement :

window.SITE_CONFIG = {
  name: 'Mon Site',
  favicon: '/favicon.ico',
};

Voir la section Personnaliser le site pour le détail complet.

Étape 5 — Adapter votre HTML

Remplacez les <link> et <script> de votre index.html pour utiliser le framework. Voici un avant/après :

Avant (votre HTML actuel) :

<head>
  <link rel="stylesheet" href="style.css">
</head>

Après (avec le framework) :

<head>
  <!-- Dark mode + Config (synchrone) -->
  <script src="core/js/darkmode.js"></script>
  <script src="config-site.js"></script>
  <script src="core/js/site.js"></script>

  <!-- CSS du framework (requis) -->
  <link rel="stylesheet" href="core/css/tokens.css">
  <link rel="stylesheet" href="core/css/base.css">
  <link rel="stylesheet" href="core/css/cookies.css">

  <!-- Vos styles perso (après le framework pour pouvoir overrider) -->
  <link rel="stylesheet" href="style.css">

  <!-- Composants (synchrone) -->
  <script src="core/js/components.js"></script>
  <script src="components/header.js"></script>
  <script src="components/footer.js"></script>

  <!-- JS interactifs (defer) -->
  <script src="core/js/cookies.js" defer></script>
</head>

Vous gardez vos fichiers CSS perso — il suffit de les charger après ceux du framework.

Étape 6 — Commiter et tester

# 📂 Dossier : la racine de votre projet

git add -A
git commit -m "Add Beely Framework"

Passez à Tester en local.

Scénario C — Projet existant structuré

Vous avez un site existant avec des dossiers /css, /js, /assets, etc. Vous voulez y intégrer le framework progressivement sans tout casser.

Étape 1 — Ajouter le framework

Suivez les étapes 1 à 3 du Scénario B (git init, submodule, symlinks).

Étape 2 — Intégration progressive

Vous n'avez pas besoin de tout intégrer d'un coup. Voici la stratégie recommandée :

1. Gardez vos fichiers CSS existants — renommez css/style.css en css/custom.css si nécessaire
2. Ajoutez les CSS du framework dans le <head> de chaque page, avant vos CSS custom :

<!-- Framework (ajouter) -->
<link rel="stylesheet" href="core/css/tokens.css">
<link rel="stylesheet" href="core/css/base.css">

<!-- Vos styles existants (garder, charger après) -->
<link rel="stylesheet" href="css/custom.css">

3. Ajoutez les JS du framework pour les fonctionnalités que vous voulez utiliser (composants, icônes, animations, etc.)
4. Remplacez les composants un par un : remplacez votre header HTML par le composant data-component="header", puis le footer, etc.
5. Testez après chaque modification pour vérifier que rien ne casse

Étape 3 — Supprimer les fichiers remplacés (quand prêt)

Une fois l'intégration terminée, vous pouvez supprimer les fichiers devenus inutiles (css/, js/, assets/ s'ils sont remplacés par le framework).

Conseil : commencez par une seule page pour vous familiariser avec le framework, puis étendez aux autres pages.

Personnaliser le site

1. Charte graphique (tokens.css)

Ouvrez core/css/tokens.css et modifiez les variables CSS :

:root {
  /* Couleurs de base (génèrent automatiquement les variantes) */
  --primary: #1a5ed6;       /* Couleur principale */
  --secondary: #8b5cf6;     /* Couleur secondaire */
  --tertiary: #ec4899;      /* Couleur tertiaire */

  /* Polices */
  --font-body: 'Inter', sans-serif;
  --font-heading: 'Inter', sans-serif;

  /* Arrondis, espacements, etc. */
}

Voir Design Tokens pour la référence complète.

2. Configuration du site (config-site.js)

Éditez config-site.js. Ce fichier centralise toute la configuration du projet :

• SITE_CONFIG : identité du site (nom, favicon)
• COOKIES_CONFIG : IDs analytics (ga4, gtm, clarity, etc.), textes du bandeau RGPD, lien vers la politique de confidentialité
• BLOG_CONFIG : connexion Baserow (voir section Site sans blog si non utilisé)
• LEGAL_CONFIG : informations légales de l'entreprise (nom, SIRET, adresse, hébergeur, etc.)

Identité du site (SITE_CONFIG)

window.SITE_CONFIG = {
  name: 'Mon Site',              // Titre par défaut (si <title> est vide)
  favicon: '/favicon.ico',       // Chemin vers le favicon
};

La configuration SSH de déploiement est dans un fichier séparé .deploy.env (non committé). Voir Déploiement.

Le favicon et le titre par défaut sont automatiquement appliqués par core/js/site.js : si aucune balise <link rel="icon"> n'est présente, le favicon configuré est injecté ; si le <title> est vide, le nom du site est utilisé.

Voir Cookies & Analytics pour le détail des autres sections.

3. Informations légales (LEGAL_CONFIG)

Dans config-site.js, complétez le bloc LEGAL_CONFIG avec vos informations :

window.LEGAL_CONFIG = {
  company: 'Ma Société SAS',
  legalForm: 'SAS',
  siret: '123 456 789 00000',
  registration: 'RCS Paris',
  representative: 'Jean Dupont',
  address: '123 rue Exemple, 75000 Paris',
  phone: '+33 1 23 45 67 89',
  email: 'contact@monsite.fr',
  website: 'https://monsite.fr',
  hosting: {
    name: 'Hostinger',
    address: 'Kaunas, Lituanie',
    url: 'https://www.hostinger.fr',
    contact: 'https://www.hostinger.fr/contact'
  },
  developer: {           // Optionnel, masqué si name est vide
    name: '', url: '', address: ''
  }
};

Les pages mentions-legales.html et confidentialite.html sont fournies et se remplissent automatiquement avec ces informations. Les champs vides affichent un placeholder [NOM_DU_CHAMP] pour vous aider à identifier les manques.

N'oubliez pas de configurer aussi privacyUrl dans la bannière cookies pour que le lien vers la politique de confidentialité apparaisse dans le bandeau :

banner: {
  privacyUrl: '/confidentialite.html',
  privacyText: 'Politique de confidentialité',
  // ...
}

Important : les textes légaux fournis sont des modèles génériques. Faites‑les valider par un professionnel du droit avant mise en production.

Voir Pages légales pour le détail de chaque champ.

4. Composants (header, footer, card)

Chaque composant se configure directement dans le HTML via des attributs data-* (pour les valeurs simples) et des <template data-slot> (pour le contenu HTML riche).

• Header : data-site-name, data-logo-link, data-logo-src, slots nav, cta, search
• Footer : data-copyright, slot content
• Card : data-title, data-text, data-image, data-image-alt, slot footer

Les composants (components/*.js) ne sont à modifier que si vous changez la structure HTML. Voir Composants pour le détail.

Créer des pages

Les pages sont créées dans le dossier pages/. Une seule ligne d'import suffit grâce au loader.

Loader (core/loader.js)

Le fichier core/loader.js charge automatiquement tous les CSS et JS du framework. Il détecte la profondeur de la page pour calculer les chemins relatifs. Plus besoin de lister 20+ imports individuels. Sans le loader, vous devriez copier-coller 20 lignes d'import dans chaque page HTML — le loader fait tout ça en une seule ligne.

Le loader charge dans l'ordre :

1. CSS : tokens, base, grid, forms, elements, animations, text-anim, icons, blog, cookies, legal, interactions
2. JS synchrones : darkmode, config-site, site, components
3. JS deferred : forms, elements, animations, text-anim, icons, blog, cookies, params, form-embed, legal, content, interactions

Pourquoi darkmode.js est synchrone ? Ce script doit s'exécuter avant le premier rendu du navigateur pour appliquer data-theme="dark" sur <html>. S'il était en defer, la page s'afficherait brièvement en thème clair avant de basculer en sombre (flash of unstyled theme). Les autres scripts synchrones (config-site, site, components) doivent aussi être disponibles avant le rendu pour que les composants s'initialisent correctement.

Les composants du projet (header.js, footer.js) restent en import séparé car ils sont spécifiques à chaque projet.

Structure minimale d'une page

Le contenu de la page suit le pattern section > container : <main> est un simple wrapper sémantique (pas de padding), .section gère le padding vertical, et .container gère le padding horizontal + la largeur maximale. Voir Structure de page pour le détail.

<!-- Dans pages/contact.html -->
<!DOCTYPE html>
<html lang="fr">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Ma Page — Mon Site</title>
  <meta name="description" content="Description SEO de la page.">

  <!-- Core : charge TOUS les CSS + JS du framework en une ligne -->
  <script src="../core/loader.js"></script>

  <!-- Composants du projet -->
  <script src="../components/header.js"></script>
  <script src="../components/footer.js"></script>
</head>
<body>

  <!-- Header : attributs + slots -->
  <div data-component="header"
       data-site-name="Mon Site"
       data-logo-link="/index.html">
    <template data-slot="nav">
      <a href="/index.html">Accueil</a>
      <a href="/contact.html">Contact</a>
    </template>
  </div>

  <main>
    <section class="section">
      <div class="container">
        <!-- Votre contenu ici -->
      </div>
    </section>
  </main>

  <!-- Footer -->
  <div data-component="footer"
       data-copyright="&copy; 2026 Mon Site">
    <template data-slot="content">
      <nav class="footer__links">
        <a href="/mentions-legales.html">Mentions légales</a>
        <a href="/confidentialite.html">Confidentialité</a>
      </nav>
    </template>
  </div>

</body>
</html>

Tester en local

Ouvrez le projet avec VS Code + Live Server ou n'importe quel serveur local :

# Option 1 : VS Code Live Server (extension)
# Clic droit sur index.html → "Open with Live Server"

# Option 2 : Python
python3 -m http.server 8000

# Option 3 : Node.js (npx)
npx serve .

Les liens internes utilisent .html pour fonctionner partout (Live Server, file://, etc.). En production, le .htaccess redirige vers des URLs propres.

python3 configurateur/configurator-server.py

Git & GitHub

Git est un outil qui sauvegarde l'historique de votre code (comme un « Ctrl+Z » illimité et partageable). GitHub est un site (github.com) qui stocke votre code en ligne (comme Google Drive pour le code).

Installer Git

Si vous n'avez pas encore Git installé :

• Mac : ouvrez le Terminal et tapez git --version. Si Git n'est pas installé, macOS vous proposera de l'installer automatiquement. Acceptez.
• Windows : téléchargez et installez git-scm.com/download/win. Gardez les options par défaut.
• Linux : sudo apt install git (Ubuntu/Debian) ou sudo dnf install git (Fedora).

Vérifiez l'installation : git --version dans le terminal (doit afficher un numéro de version).

Créer un compte GitHub

Si vous n'avez pas de compte GitHub, créez-en un gratuitement sur github.com/signup. Le plan gratuit suffit — les dépôts privés sont inclus.

Pourquoi utiliser Git ?

• Historique : chaque modification est sauvegardée avec un message (« Ajout page contact »). Vous pouvez revenir en arrière à tout moment.
• Sauvegarde en ligne : votre code est stocké sur GitHub. Si votre ordinateur plante, rien n'est perdu.
• Déploiement : le serveur de production peut récupérer automatiquement les dernières modifications depuis GitHub.
• Collaboration : plusieurs personnes peuvent travailler sur le même projet sans se marcher dessus.

1. Créer votre dépôt GitHub

Créez un nouveau dépôt sur github.com/new. Donnez‑lui un nom (ex : mon-projet), laissez Private sélectionné, ne cochez rien d'autre, cliquez Create repository. Puis changez le remote :

# Terminal : terminal VSCode (Ctrl+`)
# Dossier : la racine de votre projet

# Changer le remote
git remote set-url origin https://github.com/votre-user/votre-projet.git

# Pousser le code
git push -u origin main

Alternative : via le configurateur

Vous pouvez aussi configurer le remote depuis le configurateur visuel sans toucher au terminal :

1. Lancez le configurateur : python3 configurateur/configurator-server.py
2. Cliquez sur le bouton Publier (en haut à droite de la barre d'outils)
3. Dans la section GitHub, renseignez l'URL du remote dans le champ Remote origin
4. Cliquez sur le bouton ✓ pour enregistrer

Le statut passe à Connecté une fois le remote configuré. Vous pouvez ensuite utiliser le bouton Commit & Push directement depuis le configurateur.

2. Workflow quotidien

# Voir l'état des fichiers modifiés
git status

# Ajouter tous les fichiers modifiés + commit
git add -A
git commit -m "Add contact page with form validation"

# Pousser sur GitHub
git push

3. Bonnes pratiques commits

• Un commit = une modification logique
• Messages en anglais, courts et descriptifs : Add, Fix, Update, Remove
• Exemples : "Add hero section to homepage", "Fix mobile nav toggle"

4. Fichier .gitignore

Assurez-vous que les fichiers sensibles ou inutiles ne sont pas versionnés :

# Fichiers à ignorer dans .gitignore
.env
.deploy.env
.DS_Store
node_modules/
.claude/
data/
docs/

Mise en production

Le déploiement, la configuration serveur et la checklist de lancement ont leur page dédiée :

• Mise en production — SSH, rsync, .env, .htaccess, checklist de lancement

Site sans blog

Si votre site n'a pas besoin de blog, supprimez les fichiers liés et allégez la configuration.

Fichiers à supprimer

# Pages blog
blog.html                  # Page listing
blog/                      # Dossier contenant article.html

# Proxy API
api/                       # Dossier contenant baserow.php

# Fichier environnement (si le blog était le seul usage)
.env

CSS et JS à retirer des pages

Si vous n'utilisez pas le loader, supprimez ces lignes du <head> :

<!-- Supprimer cette ligne CSS -->
<link rel="stylesheet" href="core/css/blog.css">

<!-- Supprimer cette ligne JS -->
<script src="core/js/blog.js" defer></script>

Configuration à nettoyer

Dans config-site.js, supprimez ou videz la section BLOG_CONFIG.

Navigation à adapter

Retirez le lien « Blog » du slot nav dans le header de chaque page HTML.

Résumé

Modules optionnels

Vous pouvez retirer des modules selon vos besoins. Chaque module est indépendant :

Minimum requis : tokens.css + base.css + components.js + site.js + vos composants (header.js, footer.js).

Snippets (copier-coller)

Le dossier snippets/ contient un fichier HTML par élément, prêt à copier-coller dans vos pages. Chaque fichier commence par un bloc commentaire listant toutes les classes, attributs et options disponibles.

Lancer les tests

Le framework inclut une suite de tests automatisés, écrite en Python pur (bibliothèque standard, zéro dépendance externe).

# Le serveur local doit tourner (Live Server, Python http.server, ou configurateur)
python3 tests/test_framework.py

Le script vérifie le chargement des pages, les composants, les tokens CSS et les fonctionnalités clés du framework. Tous les tests doivent passer (100 %).