Site web de documentation du SophiaHackLab

Le présent document constitue le code source du site web officiel de documentation du SophiaHackLab, un hackerspace collaboratif regroupant ingénieurs, artistes, scientifiques et entrepreneurs, situé à Sophia-Antipolis, France.

Ce site est développé avec Docusaurus, un générateur de sites web statiques moderne. Il permet de gérer aisément du contenu, comme des articles de blog ou de la documentation pour les projets du SHL: ajouter/modifier/supprimer des fichiers markdowns dans ce répertoire sur la branche main déploiera automatiquement ces changements sur le site web https://sophiahacklab.github.io/docusaurus/.

Structure du projet

.
├── docs/                   # Fichiers markdown de documentation
│   ├── intro.md            # Page d'introduction
│   ├── contributing.md     # Guide de contribution (dans la sidebar)
│   ├── test-reports.md     # Documentation des rapports de tests
│   └── projects/           # Documentation des projets
│       ├── fete_de_la_science/
│       ├── rov/
│       └── triviak/
│           ├── mini/
│           └── real/
├── blog/                   # Articles de blog
│   ├── 2025-01-06-campagne-dons-2025.md
│   ├── 2024-12-15-innovation-hackerspaces.md
│   ├── 2025-01-05-open-talks-rust.md
│   ├── authors.yml         # Auteurs du blog
│   └── tags.yml            # Tags du blog
├── src/                    # Composants React et pages
├── static/                 # Ressources statiques
├── tests/                  # Tests e2e Playwright
│   ├── homepage.spec.ts
│   ├── sidebar.spec.ts
│   └── projects.spec.ts
├── scripts/                # Scripts utilitaires
│   └── test-local.sh       # Script de test local
├── docusaurus.config.ts    # Configuration Docusaurus
├── playwright.config.ts    # Configuration Playwright
├── sidebars.ts             # Configuration de la sidebar (autogénérée)
└── DEPLOYMENT.md           # Instructions de déploiement

Contribuer

Le fichier CONTRIBUTING.md donne des détails concernant les contributions.

Démarrage rapide

Installation

npm install

Développement local

npm start

Cette commande lance un serveur de développement local à l'adresse http://localhost:3000 et ouvre une fenêtre de navigateur à cette adresse. La plupart des modifications sont reflétées instantanément sans nécessiter le redémarrage du serveur.

Build

npm run build

Cette commande génère le contenu statique dans le répertoire build et peut être déployée via tout service d'hébergement de contenu statique.

Tests

Playwright est utilisé pour les tests de bout en bout (end-to-end) sur les navigateurs Chromium, Firefox et WebKit.

Exécution des tests E2E (serveur de développement)

Exécuter les tests sur le serveur de développement:

npm start          # Dans un premier terminal
npm run test:e2e   # Dans un second terminal

Exécution de la suite complète de tests (build de production)

Build, déploiement, tests et génération de rapports en une seule commande:

npm run test:local

Ce script exécute les opérations suivantes:

1. Build du site Docusaurus
2. Démarrage d'un serveur de production local
3. Attente de la disponibilité du serveur
4. Exécution des tests e2e Playwright
5. Génération des rapports JUnit XML et HTML
6. Arrêt du serveur et affichage des résultats

Rapports de tests:

• JUnit XML: test-results/junit.xml
• Rapport HTML: test-results/html/index.html

Visualisation des rapports de tests

Ouvrir le rapport de tests HTML dans votre navigateur:

npm run test:report

Déploiement

GitHub Pages (automatisé)

Le site est automatiquement déployé sur sur une GitHub Page lors des modifications poussées sur la branche main (via GitHub Actions).

URL de production: https://sophiahacklab.github.io/docusaurus/

Workflows GitHub Actions

Deux workflows automatisés:

1. Workflow de déploiement (.github/workflows/deploy.yml)

• Déclenchement: Push sur la branche main
• Étapes:
  1. Checkout du code
  2. Installation de Node.js 20
  3. Installation des dépendances
  4. Build Docusaurus
  5. Upload de l'artefact de build
  6. Déploiement sur GitHub Pages
• Statut:

2. Workflow de tests E2E (.github/workflows/test.yml)

• Déclenchement: Push sur main, Pull requests, déclenchement manuel
• Étapes:
  1. Checkout du code
  2. Installation de Node.js 20 avec cache npm
  3. Installation des dépendances via npm ci
  4. Installation des navigateurs Playwright avec dépendances
  5. Build Docusaurus
  6. Exécution des tests Playwright avec reporters JUnit, HTML et list
  7. Upload des résultats de tests (JUnit XML et HTML)
  8. Upload des captures d'écran en cas d'échec
  9. Publication du résumé des tests sur GitHub
• Timeout: 15 minutes maximum
• Rapports: Disponibles en tant qu'artefacts GitHub Actions pendant 30 jours
• Statut:

Paramètres du dépôt

Les GitHub Pages sont activées (projet Open Source):

1. Accéder à Settings → Pages
2. Définir Source sur "GitHub Actions"
3. Le site sera déployé automatiquement au prochain push

Déploiement manuel (debug)

Via SSH:

USE_SSH=true npm run deploy

Sans SSH:

GIT_USER=<Votre nom d'utilisateur GitHub> npm run deploy

Configuration

URLs basées sur l'environnement

Le site utilise une configuration d'URL basée sur l'environnement:

• Développement local: baseURL: '/' à http://localhost:3000
• GitHub Pages: baseURL: '/docusaurus/' à https://sophiahacklab.github.io/docusaurus/

Cette configuration est détectée automatiquement via la variable d'environnement BUILD_FOR_GITHUB_PAGES.

Internationalisation

Le site est configuré en français (fr) comme locale par défaut:

i18n: {
  defaultLocale: 'fr',
  locales: ['fr'],
}

Configuration du thème

Mode sombre forcé: Le site utilise un thème sombre monochrome personnalisé avec commutation du mode couleur désactivée:

colorMode: {
  defaultMode: 'dark',
  disableSwitch: true,
  respectPrefersColorScheme: false,
}

Stylisation personnalisée:

• Design monochrome ultra-minimaliste avec arrière-plans noir pur (#000000)
• Contraste maximum avec texte blanc/gris
• CSS personnalisé dans src/css/custom.css pour une esthétique minimaliste

Support des diagrammes Mermaid

Le site intègre des capacités de rendu de diagrammes Mermaid via @docusaurus/theme-mermaid:

themes: ['@docusaurus/theme-mermaid'],
markdown: {
  mermaid: true,
}

Il est possible de créer des diagrammes directement dans le markdown en utilisant des blocs de code mermaid.

Sidebar

La sidebar est automatiquement générée à partir de la structure du système de fichiers dans le répertoire docs/. Pour personnaliser l'ordre:

• Utiliser sidebar_position dans le frontmatter markdown
• Ajouter des fichiers _category_.json dans les répertoires
• Consulter la documentation sidebar de Docusaurus

Scripts disponibles

Script	Description
npm start	Démarrer le serveur de développement
npm run build	Build pour la production
npm run serve	Servir le build de production localement
npm run test:e2e	Exécuter les tests e2e Playwright
npm run test:local	Build, servir, tester et générer un rapport
npm run test:report	Ouvrir le rapport de tests HTML
npm run clear	Effacer le cache Docusaurus
npm run deploy	Déployer sur GitHub Pages

Blog

Le site comprend des articles de blog spécifiques au SHL, tels que:

• Campagne de dons 2025 - Informations sur le soutien au SHL via les dons
• Innovation dans les hackerspaces - Comment les hackerspaces catalysent les écosystèmes technologiques
• Open Talks: Rust - Annonce d'événement pour la présentation Rust (14 janvier 2025)

Tous les articles de blog comportent le branding SHL et sont correctement tagués pour une navigation facilitée.

À propos du SophiaHackLab

Le SophiaHackLab regroupe des ingénieurs, artistes, scientifiques, entrepreneurs et créatifs, qui partagent un espace de travail et de socialisation à Sophia-Antipolis, France.

• Site web: https://www.shl.contact/
• Localisation: Space Antipolis, Bâtiment 9, Sophia-Antipolis
• Contact: [email protected]

Licence

Cette documentation de projet est maintenue par le SophiaHackLab.