Le composant ProjectSetup - Une façon standardisée de partager des structures de projet

Sur mon blog, je partage souvent des composants que j'ai créés pour Docusaurus. Pour permettre aux lecteurs de reproduire facilement ces projets, je cherchais une manière interactive et standardisée de partager des arborescences de fichiers. C'est ce qui m'a amené à créer le composant ProjectSetup.

Il permet d'afficher la structure d'un projet de façon claire et interactive, avec un snippet de code pour chaque fichier. Mais sa vraie force, sa « killer feature », c'est ceci : en un seul clic sur le bouton « Generate install script », vous obtenez une commande shell. Copiez-la, collez-la dans votre terminal Linux, exécutez-la et... voilà. Toute l'arborescence du projet, dossiers et fichiers compris, est créée pour vous.

Pour ceux qui préfèrent, le composant propose aussi de télécharger le projet sous forme d'archive ZIP. Dans cet article, je vous montre comment ça fonctionne et comment l'intégrer pour partager efficacement vos propres projets.

Le voir à l'œuvre​

La meilleure façon de vous montrer comment utiliser ProjectSetup, c'est d'utiliser le composant lui-même. Voici comment installer le composant LogoIcon dans votre propre projet Docusaurus.

À ce stade, vous vous dites peut-être : oh la la, ça doit être fastidieux d'écrire le code HTML derrière cette jolie boîte 📦 Project setup: src/components/Blog/LogoIcon ci-dessus. En fait, pas du tout. Tout le rendu est pris en charge par le composant ProjectSetup lui-même. Voici le code Markdown que j'ai écrit dans mon article Docusaurus :

<ProjectSetup folderName="src/components/Blog/LogoIcon">
  <Guideline>
    Install the dependency: `npm install @iconify/react`
  </Guideline>
  <Snippet filename="src/components/Blog/LogoIcon/index.tsx" source="src/components/Blog/LogoIcon/index.tsx" />
</ProjectSetup>

Qu'est-ce que ProjectSetup ?​

ProjectSetup est un composant React qui permet d'afficher la structure de fichiers d'un projet de façon propre, interactive et standardisée. Il montre non seulement les fichiers et leur contenu, mais fournit aussi des outils pour générer le projet en une seule commande ou le télécharger au format ZIP.

Cet article illustre comment utiliser le composant ProjectSetup pour partager des structures de projet dans vos articles de blog Docusaurus, et ainsi permettre à vos lecteurs de reproduire vos projets et d'en tirer profit plus facilement.

Fonctionnalités principales​

• Affichage interactif des fichiers : les fichiers s'affichent dans des snippets repliables, avec coloration syntaxique.
• Génération de script shell : un script bash est généré automatiquement pour créer toute l'arborescence de dossiers et de fichiers.
• Téléchargement ZIP : les utilisateurs peuvent télécharger le projet complet sous forme d'archive ZIP.
• Instructions post-installation : vous pouvez ajouter des consignes à afficher après l'installation.

Dépendances​

Le composant ProjectSetup s'appuie sur deux autres composants :

1. LogoIcon : un composant simple qui affiche une icône selon le type de fichier, ce qui rend l'interface plus intuitive. Il utilise la très répandue bibliothèque @iconify/react. LogoIcon a été créé par Docux, allez jeter un œil à son travail : Component LogoIcon.
2. Snippet : ce composant se charge d'afficher chaque fichier. C'est un container repliable qui montre le nom du fichier, une icône pertinente et le code correspondant. Lisez mon article précédent sur le sujet : Un composant pour afficher des snippets de code dans un blog Docusaurus

Installer le reste​

Voici comment installer les composants Snippet et ProjectSetup restants dans votre propre projet Docusaurus.

1. Installer Snippet​

Mettons maintenant en place le composant Snippet. Il a un peu plus de dépendances.

2. Installer ProjectSetup​

Enfin, voici comment installer le composant ProjectSetup lui-même.

3. La page d'aide project_setup​

Le composant ProjectSetup renvoie vers une page d'aide qui explique comment l'utiliser. Vous pouvez personnaliser cette page en éditant le fichier src/pages/project_setup.mdx. Voici la mienne :

Conclusion​

Le composant ProjectSetup est un outil puissant pour partager des structures de projet dans vos articles de blog Docusaurus. Il offre une manière interactive d'explorer l'arborescence des fichiers, génère des scripts d'installation et propose un téléchargement ZIP, ce qui facilite la reproduction de vos projets. En l'utilisant, vous améliorez l'expérience d'apprentissage de vos lecteurs et les incitez à s'impliquer davantage dans votre contenu.