Hugo & Docusaurus

Publié le 22 juin 2022 par berenger benam

Hugo & Docusaurus

De nos jours, les sites Web statiques deviennent de plus en plus populaires. Mais comment choisir la bonne solution pour votre équipe de documentation ? Dans cette partie, nous comparerons deux générateurs de sites statiques populaires : Hugo & Docusaurus .

C'est quoi Hugo ?

Hugo est un générateur de site statique open source qui a été initialement publié en 2013. Comme Hugo est écrit en Golang (Go), il a rapidement gagné en popularité parmi les communautés Go et est depuis devenu l'une des solutions de documentation les plus connues pour des projets tels que Kubernetes et de nombreuses entreprises qui l'entourent.

Qu'est-ce que le Docusaure ?

Créé par Facebook, Docusaurus est écrit en JavaScript et utilise React. Docusaurus fournit un modèle de site Web de base que vous pouvez modifier selon vos besoins si vous connaissez Javascript. Le modèle de site Web fournit des pages de modèles d'API, de documents, d'aide et de blog intégrés. Ce site Web fonctionne sur Docusaurus.

Maintenant, comment choisir le bon entre les deux moteurs de documentation apparemment similaires ?

Voici quelques points à considérer.

votre site Web pour qu'il s'exécute localement aussi rapidement qu'en moins de 30 minutes. Hugo prend en charge tous les systèmes d'exploitation sur lesquels un compilateur Golang est exécuté, y compris MacOs, Windows, Linux, etc. Avec Hugo, vous pouvez utiliser la ligne de commande ou télécharger un binaire pour votre plateforme.

Docusaurus est un outil un peu plus orienté Unix et si vous êtes sur une machine Windows, vous devez activer un sous-système Windows pour l'environnement Linux. Ce blog se concentre sur une façon MacOs de faire les choses avec Hugo et Docusaurus.

Une Petite Démo :

Installation

Docusaurus est essentiellement un ensemble de paquet de npm .

Partie I :

Pré-requis

Node.js version 16.14 ou supérieure (qui peut être vérifiée en exécutant node -v). Vous pouvez utiliser nvm pour gérer plusieurs versions de Node sur une seule machine installée.
- Lors de l'installation de Node.js, il est recommandé de cocher toutes les cases liées aux dépendances.

Comment installer Node.js 16 sur Ubuntu

Dans ce guide, nous expliquerons comment installer Node.js 16 sur Ubuntu

ode.js est une plate-forme à usage général avec un runtime JavaScript basé sur le moteur JavaScript V8 de Chrome et est utilisé pour créer des applications réseau évolutives. Il est utilisé à la fois sur le backend et le frontend comme une pile complète rendant le développement plus cohérent.

npm est une abréviation de Node Package Manager qui est le plus grand référentiel de packages par défaut pour Node.js. Node.js 16 possède les fonctionnalités suivantes :

Utilisation du gestionnaire NVM

Méthode 1) Installez Node.js 16 sur Ubuntu à partir du référentiel Node Source PPA

Pour installer n'importe quelle version de Node.js, vous pouvez utiliser un PPA (archive de packages personnels) qui est maintenu par Node source. Ces PPA ont beaucoup plus de versions de Node.Js par rapport aux dépôts officiels d'Ubuntu. Tout d'abord, nous devrons installer le PPA afin d'installer Node.js 16. Depuis votre répertoire personnel, utilisez la commande cURL. Installez cURL au cas où vous ne l'auriez pas installé avec sudo Apt install cURL.

Placez-Vous dans le dossier le répertoire personnel et lancez cette commande :

Cette commande crée une liste de sources APT pour Nodesource Node.Js 16 repo qui peut être visualisée comme ci-dessous.

Avec le référentiel ajouté avec succès, vous pouvez maintenant installer Node.js 16 sur Ubuntu

Une fois installé, vérifiez la version de Node.js.

Méthode 2) Installez Node.js et npm à l'aide de NVM

À partir de NVM (Node Version Manager), vous pouvez installer Node.js 16 en procédant comme suit.

Installer l'outil NVM

Téléchargez et installez Node Version Manager comme ci-dessous.

À partir de la sortie ci-dessus, le chemin de nvm a été ajouté à la session en cours. Vérifiez maintenant la version installée de nvm.

Installer Node.js 16 et npm

Maintenant que NVM est installé, vérifiez les versions Node.js disponibles.

C’est la sortie :

À partir de la sortie ci-dessus, nvm a de nombreuses versions de Node.js. Continuez et installez la version Node.js 16.x que vous souhaitez sur Ubuntu.

Une fois terminé, vérifiez la version installée de Node.js.

Vous avez Node.js 16 installé. Si vous avez plusieurs versions de Node.js installées, listez-les avec :

Premiers pas avec Node.js

Maintenant que nous avons installé avec succès Node.js 16 sur notre système, construisons un serveur Web simple. Tout d'abord, créez un fichier.

Dans le fichier créé, ajoutez les lignes ci-dessous.

Ici, nous avons créé un simple serveur web pour imprimer « Salut Berenger »

Démarrez le serveur Web :

C'est ça! Nous avons triomphalement installé Node.js 16 sur Ubuntu

Partie II :

Structurer un site web d'un projet

La façon la plus simple d'installer Docusaurus est d'utiliser l'outil en ligne de commande qui vous aide à créer un squelette de site web Docusaurus. Vous pouvez exécuter cette commande n'importe où dans un nouveau dépôt vide ou dans un dépôt existant, elle créera un nouveau répertoire contenant les fichiers de structure.

npx create-docusaurus@latest my-website classic

Une fois la création du dossier my-website terminé déplacez-vous dans le dossier.

Nous recommandons le Template classic pour que vous puissiez commencer rapidement et il contient des fonctionnalités disponibles dans Docusaurus 1.

Le Template classic contient @docusaurus/preset-classic qui inclut une documentation standard, un blog, des pages personnalisées et un framework CSS (avec support du mode sombre). Vous pouvez être opérationnel très rapidement avec le Template classic et personnaliser les choses plus tard, lorsque vous serez plus familier avec Docusaurus.

npx create-docusaurus@latest my-website classic --typescript

UNIQUEMENT FB

Si vous configurez un nouveau site web Docusaurus pour un projet open source Facebook, utilisez le template facebook à la place, qui est fourni avec quelques valeurs par défaut utiles propres à Facebook : npx create-docusaurus@latest my-website facebook

Commandes d'installation alternatives

Vous pouvez également initialiser un nouveau projet en utilisant votre gestionnaire de projet préféré :

Structure du projet

En supposant que vous avez choisi le template classic et nommé votre site my-website, vous verrez les fichiers suivants générés dans un nouveau répertoire my-website/ :

Voici l’arborescence de notre projet :

Récapitulatif de la structure du projet

/blog/ - Contient les fichiers Markdown du blog. Vous pouvez supprimer le répertoire si vous avez désactivé le plugin du blog, ou vous pouvez changer son nom après avoir défini l'option path.
/docs/ - Contient les fichiers Markdown pour la documentation. Personnalisez l'ordre de la barre latérale des docs dans sidebars.js. Vous pouvez supprimer le répertoire si vous avez désactivé le plugin des docs, ou vous pouvez changer son nom après avoir défini l'option path.
/src/ - Fichiers de non-documentation comme les pages ou les composants React personnalisés. Vous n'êtes pas obligé de placer vos fichiers de non-documentation ici, mais les placer dans un répertoire centralisé permettent de les spécifier plus facilement au cas où vous auriez besoin de faire une sorte de vérification/traitement
- /src/pages - Tous les fichiers JSX/TSX/MDX de ce répertoire seront convertis en page de site.
/static/ - Répertoire statique. Tout contenu à l'intérieur sera copié à la racine du répertoire final de build
/docusaurus.config.js - Un fichier de configuration contenant la configuration du site. Ceci est l'équivalent de siteConfig.js dans Docusaurus v1
/package.json - Un site Web Docusaurus est une application React. Vous pouvez y installer et utiliser tous les paquets npm que vous souhaitez
/sidebars.js - Utilisé par la documentation pour spécifier l'ordre des documents dans la barre latérale.

Exécution du serveur de développement

Pour pré visualiser vos modifications au fur et à mesure que vous modifiez les fichiers, vous pouvez lancer un serveur de développement local qui servira votre site Web et reflétera les dernières modifications.

Lancez cette commande pour démarrer le projet : npm run start

Par défaut, une fenêtre du navigateur s'ouvre depuis l'adresse http://localhost:3000.

Félicitations ! Vous venez de créer votre premier site Docusaurus ! Naviguez sur le site pour voir ce qui est disponible.

Si on veut faire de modification il suffit : de se placer dans le dossier docs

Voici le contenu du fichier :

TEST :

On redémarre le projet

Cliquez sur blog

Dans mon cas je n’ai pas changé l’image j’ai juste modifié l’url de git hub et cliquez sur

Berenger Benam

Donc c’est possible de modifie il suffit d’avoir quelque maitrise de Yml boom nickel !

Partie II :

Mise à jour de votre version de Docusaurus

Il y a de nombreuses façons de mettre à jour votre version de Docusaurus. Une façon garantie est de changer manuellement le numéro de version dans package.json à la version désirée. Notez que tous les paquets nommés @docusaurus/ doivent utiliser la même version.

Il faut avoir la même version : éditer le fichier package.json

Ensuite, dans le répertoire contenant le fichier package.json, exécutez la commande d'installation de votre gestionnaire de paquets :

Pour vérifier que la mise à jour a été effectuée avec succès, exécutez :

Vous devriez voir la version correcte en résultat.

Configuration

Docusaurus a une approche unique sur les configurations. Nous vous encourageons à rassembler les informations de votre site en un seul endroit. Nous gardons les champs de ce fichier et facilitons l'accès à cet objet de données à travers votre site.

Le fait de conserver un docusaurus.config.js bien maintenu vous aide, ainsi que vos collaborateurs et vos contributeurs open source, à pouvoir vous concentrer sur la documentation tout en étant en mesure de personnaliser le site.

Qu'est-ce qui va dans un docusaurus.config.js ?

Vous ne devriez pas avoir à écrire votre docusaurus.config.js à partir de zéro, même si vous développez votre site. Tous les templates sont fournis avec un docusaurus.config.js qui inclut les valeurs par défaut pour les options courantes.

Toutefois, il peut être utile d'avoir une compréhension de haut niveau de la façon dont les configurations sont conçues et mises en œuvre.

La configuration de haut niveau de Docusaurus peut être classée en plusieurs catégories :

Métadonnées du Site
Configuration de Déploiement
Théme,Plugin et Configuration Prédéfinies
Configurations Personnalisées

Pour une référence exacte à chacun des champs configurables, vous pouvez vous référer à . la référence API docusaurus.config.js.

Métadonnées du site :

Les métadonnées du site contiennent les métadonnées globales essentielles telles que title, url, baseUrl et favicon.

Ils sont utilisés à de nombreux endroits, comme le titre et les entêtes de votre site, l'icône de l'onglet du navigateur, les informations relatives au partage social (Facebook, Twitter) ou même pour générer le chemin d'accès correct pour servir vos fichiers statiques.

Configurations de déploiement

Les configurations de déploiement telles que projectName, organizationName et optionnellement deploymentBranch sont utilisées lorsque vous déployez votre site avec la commande deploy.

Thème, plugin et configurations prédéfinies

Indique les thème, les plugins et les presets de votre site dans les champs respectifs thèmes, plugins et presets. Il s'agit généralement de paquets npm :

Comment créer et déployer un site Hugo sur la plate-forme d'applications DigitalOcean

Hugo est un générateur de site statique et un cadre pour la création de sites Web. Avec Hugo, vous définissez vos thèmes en utilisant HTML et construisez votre contenu en utilisant Markdown ou d'autres traitements de texte. Hugo génère du HTML que vous pouvez héberger n'importe où.

Dans ce didacticiel, vous utiliserez Hugo pour créer un petit site Web statique et déployer le site sur la plate-forme d'applications de Digital Océan à l’aide de Git Hub. Ensuite, vous apporterez des modifications à votre site et verrez ces modifications déployées automatiquement.

Conditions préalables

Pour terminer ce tutoriel, vous aurez besoin de :

Un compte DigitalOcean
Un compte GitHub
Git installé sur votre machine locale. Vous pouvez suivre le tutoriel Contributing to Open Source: Getting Started with Git pour installer et configurer Git sur votre ordinateur.
Un éditeur de texte. Vous pouvez utiliser Visual Studio Code ou votre éditeur de texte préféré.

Étape 1 - Installation de Hugo

Pour créer votre site Hugo, vous allez installer l'Hugo outil de ligne de commande sur votre ordinateur local. Vous utiliserez cet outil pour générer votre site, créer des pages de contenu et lancer un petit serveur que vous utiliserez pour tester votre site avant de le déployer.

Hugo est disponible sous la forme d'un binaire unique. Le processus d'installation implique donc de télécharger le fichier sur votre machine et de le placer sur votre chemin.

Téléchargez Hugo à partir de la page des versions sur GitHub . Hugo est disponible en deux versions : la version régulière et la version étendue. Téléchargez la version étendue afin de bénéficier d'une prise en charge de la gestion des actifs et d'une prise en charge du prétraitement CSS. Enregistrez le fichier dans votre Downloads répertoire.

Une fois que vous avez téléchargé le fichier, vous devrez le décompresser et le placer quelque part sur votre système PATH afin de pouvoir exécuter le fichier à partir de n'importe quel répertoire.

Sous Windows, créez le répertoire C:\Hugo, décompressez le fichier que vous avez téléchargé et placez-le dans C:\hugo. Ajoutez ensuite ce dossier à votre variable d'environnement PATH. Pour ce faire, utilisez Windows Search et tapez « environnement ». Sélectionnez Modifier les variables d'environnement pour Mon compte. Sur l'écran qui apparaît, appuyez sur le bouton Variables d’environnement, localisez PATH dans la section Variables système et appuyez sur le bouton Modifier. Ajoutez c:\hugo\bin dans la zone de texte et appuyez sur OK pour enregistrer les paramètres. Appuyez sur OK dans les autres boîtes de dialogue pour les fermer.

Sur macOS ou Linux, copiez l'exécutable dans /usr/local/bin, car il est déjà inclus dans votre variable d'environnement PATH par défaut.

Tout d'abord, passez au répertoire Téléchargements et mettez à jour votre système avec la commande :

Cliquez sur ce lien pour Télécharger Hugo : https://github.com/gohugoio/hugo/releases

Décompressez le fichier :

Déplacez ensuite le fichier hugo vers /usr/local/bin:

Assurez-vous qu’Hugo est configuré en basculant vers votre répertoire personnel et en tapant la hugo commande :

Vous verrez le numéro de version imprimé à l'écran :

Maintenant qu’Hugo est installé, vous pouvez créer votre site.

Étape 2 - Création du projet Hugo

Créons un petit site sur les requins. Nous l'appellerons "bangui", et il contiendra des pages sur différents types de requins.

Pour créer un site, utilisez la hugo new site commande. Depuis votre répertoire personnel, exécutez la commande suivante :

Cela crée le répertoire bangui et affiche un message de bienvenue qui vous indique comment installer un thème pour votre site :

Au lieu d'installer un thème existant, vous ajouterez une petite quantité de HTML et de CSS à votre site pour définir son apparence. Les thèmes existants peuvent souvent nécessiter beaucoup de configuration, et cela sort du cadre de ce didacticiel. Basculez vers le bangui répertoire :

Archetypes : sont vos modèles de contenu. Vous pouvez utiliser la hugo commande pour créer de nouvelles pages Markdown, et elle utilisera les fichiers du archetypes répertoire comme modèle pour ces pages.
config.tomlest : le fichier de configuration du site, dans lequel vous spécifiez le domaine, le titre et le thème du site que vous souhaitez utiliser.
Content : est le répertoire qui contient le contenu de votre site.
Data : est l'endroit où vous pouvez stocker les fichiers JSON que vous pouvez utiliser lors de la génération de votre site.
Layouts : est l'endroit où vous placez les fichiers HTML qui définissent l'apparence de votre site ou remplacent les modèles d'un thème.
Resources : C’est là qu'Hugo place les fichiers qu'il génère, comme des images optimisées.
Static : contient des actifs statiques, tels que des fichiers, des feuilles de style, des scripts ou d'autres actifs que vous n'avez pas besoin qu'Hugo gère pour vous.
Themes : contient des thèmes que vous créez ou téléchargez.

Vous n'utiliserez pas de thème dans ce didacticiel ; vous définirez des fichiers HTML dans le layoutsrépertoire pour définir l'apparence de votre site.

Avant de poursuivre, ouvrez le fichier config.toml dans votre éditeur. Remplacez le baseURL champ par une chaîne vide et modifiez le titre pour qu'il indique « bangui » :

Enregistrez le fichier.

Ensuite, vous allez créer la mise en page et le contenu du site. Le site aura une page d'accueil et une section intitulée "Requins". Pour afficher votre contenu, Hugo a besoin de trois types de fichiers modèles :

Un modèle pour la page d'accueil
Un modèle pour une page de contenu, comme une page sur un seul requin
Un modèle qui affiche une liste de pages, comme une page qui répertorie tous les requins, ou toutes les balises ou catégories du site.

Commençons par créer le modèle de page d'accueil. Créez le fichier layouts/index.html et ouvrez-le dans votre éditeur. Ajoutez le code suivant au fichier pour définir le site :

Les {{ .Site.Title }} lignes saisissent le titre du config.toml fichier. La {{ .Title }}ligne et

{{ .Content }} la ligne récupèrent le titre et le contenu du document associé à la page d'accueil, que vous allez créer ensuite.

Enregistrez votre fichier.

Par défaut, Hugo crée toutes les nouvelles pages en mode brouillon. Ouvrez le fichier archetypes/default.md dans votre éditeur et modifiez-le pour qu'il draft soit false. De cette façon, toutes les nouvelles pages que vous créez ne seront pas en mode brouillon.

La replace ligne dans le title champ indique à Hugo de générer le titre de la page en fonction du nom du fichier.

Enregistrez le fichier.

Utilisez maintenant Hugo pour générer un fichier de contenu pour votre page d'accueil. Depuis le terminal, dans le répertoire de votre projet, tapez cette commande :

Cela génère le fichier content/index.md:

Le trait de soulignement dans le nom de fichier indique à Hugo qu'il s'agit de la page de contenu d'une page de liste ou de la page d'accueil, par opposition à un élément de contenu normal.

Ouvrez le content/_index.md fichier dans votre éditeur, ajoutez du texte et modifiez le titre :

On démarre le projet :

Résultat web :

Gestion des droits sur des projets (owner, developper etc…)

Le Product Owner est un métier de plus en plus plébiscité par les entreprises.Ce profil bien particulier est un expert de la gestion de projet agile qui, grâce à sa vision produit et métier, guider l'équipe scrum pour fournir un maximum de qualité aux utilisateurs.

Qui est le Product Owner ? Définition

Le Product Owner (PO) est un chef de projet en mode agile qui supervise et coordonne le développement et la livraison d’un produit numérique qui répond aux besoins des clients.

Véritable chef d’orchestre, la·le PO fait le pont entre la partie technique et la partie métier d’un projet. Garant·e du produit, elle ou il le porte vers des améliorations toujours plus poussées afin de maximiser la valeur offerte aux utilisateurs.

Le Product Owner travaille en étroite collaboration avec d'autres membres de l'équipe scrum, comme l'ingénieur devops ou le scrum master, pour fluidifier au maximum la gestion d'un projet. Garant·e du produit, elle ou il le porte vers des améliorations toujours plus poussées afin de maximiser la valeur offerte aux utilisateurs.

Les appellations peuvent varier d’une organisation à l’autre :

Chef de produit
Product Manager
Chief Product Officer (CPO)
Head of Product, etc.

Dans tous les cas, le « product » se réfère au livrable qu’il faut fournir au demandeur suite à l’exécution d’un projet, produit qui est généralement numérique (site web, produit SaaS, application mobile, application interne, etc.).

Quel est le rôle du Product Owner ?

Responsabilités du PO

Le PO est chargé de développer et d’optimiser un produit numérique ou informatique dans le cadre budgétaire et les délais impartis, afin de répondre le plus justement possible aux attentes des utilisateurs.

Sa vision est orientée produit, métier et efficacité : il s’assure que le développement réponde aux besoins des utilisateurs, dont il recueille et analyse les attentes.

Il a pour mission d’orchestrer le projet et de veiller à sa mise en œuvre par l’équipe de réalisation. Il travaille généralement en appliquant une méthode agile, comme la méthodologie Scrum, la plus utilisée, en collaborant avec les services suivants :

l’équipe R&D,
l’équipe support client,
l’équipe commerciale,
l’équipe marketing,
les clients.

Les missions du PO

Le Product Owner est orienté opérationnel, avec comme principales missions de :

porter la vision produit et planifier la roadmap produit ;
formuler et prioriser les besoins ;
gérer le backlog produit, qui liste et priorise les éléments du projet ;
superviser les étapes de développement ;
adopter une démarche d’amélioration continue du produit.

Compétences et qualités d'un bon PO

Pour réussir dans ses activités au quotidien, la le Product Owner doit faire preuve des qualités et compétences suivantes :

 Hard skills(Compétences techniques) :

compréhension du produit,
compétences techniques et sensibilité Tech,
sensibilité UX,
connaissances en design,
notions en business et marketing,
intérêt pour le growth hacking, utilisation du framework AARRR,
qualités analytiques : analyse de données, étude des KPI et esprit de synthèse,
expérience en management de projet, avec une bonne connaissance des approches agiles (tout particulièrement la méthodologie Agile Scrum).

Soft skills(Compétences générales) :

sens de l’organisation et bonne gestion des priorités,
capacité de prise de décisions : arbitrage entre les différents enjeux et parties prenantes,
communication et clarté d’expression,
sens de la négociation et diplomatie,
réactivité, exécution rapide et proactivité,
talent relationnel et sens de l’écoute,
disponibilité et flexibilité,
curiosité et créativité.

La boîte à outils du Product Owner

Les solutions logicielles dont peut se servir un Product Owner englobent une variété d’activités, de la gestion de projet en mode agile à la conception des prototypes. En voici une sélection, non exhaustive, qui peut être complétée ou adaptée selon le fonctionnement de toute organisation :

Logiciels de gestion de projet et de gestion de tâches 👉 Asana, GitLab, Jira, MeisterTask, Monday.com, Trello,
Logiciels de Knowledge Management 👉 Cocoom, Document 360, Elium,
Logiciels de prototypage et de graphisme 👉 Balsamiq Mockups, Mockplus, Pidoco, Mockflow, Sketch, Figma,
Logiciels de support client 👉 Help Scout, Intercom, Uservoice,
Logiciels DAM (gestion des actifs numériques) 👉 FileRobot
Logiciels d’analyse de données 👉 Google Analytics, Segment

CONCLUSION :

Le Product Owner joue un rôle de facilitateur dans son équipe et l'entreprise, le Product Owner endosse un rôle transverse. « Super chef de projet digital », il fait le pont entre les équipes internes : entre le business, le service marketing, l’équipe R&D et la partie design.Outre sa qualité de manager, avec un bagage solide dans les domaines Tech/digital, le PO reste enfin l’interlocuteur privilégié des utilisateurs.

2eme Partie :

Une documentation avec Docusaurus et GitLab Pages

Objectifs :

Nous allons voir ensemble comment publier hyper simplement une documentation avec Docusaurus et GitLab Pages.

Nous verrons également comment ajouter un moteur de recherche sans utiliser une solution externe d’indexation.

Création d’un nouveau projet Docusaurus en local

Vous devez disposer de Node.js sur votre poste pour la suite.

Créons tout d’abord un nouveau projet Docusaurus

npx create-docusaurus@latest BerengerDevOps classic

-Entrons dans le répertoire du projet

cd BerengerDevOps

Et lançons le serveur par la commande : npm start

Et Pour accéder il suffit de taper cette Url http://localhost:3000

Personnalisons du projet

Le fichier docusaurus.config.js

Une très grande partie de la configuration de notre Docusaurus va être effectuée dans le fichier docusaurus.config.js.

Nous y reviendrons plus tard quand nous allons héberger notre Doc sur GitLab Pages.

Commençons par modifier le titre et le slogan.

Puis changeons le nom dans le menu

Pour changer Image il faut envoyer votre photo dans le dossier /static/img qui se trouve dans le dossier du projet.

Ensuite, Nous pouvons aussi changer la phrase dans le footer

Test pour voir le résultat :

Le contenu de notre documentation

Suppression de la section Blog

Pour notre exemple, nous allons désactiver la partie blog.

Supprimons la partie Blog en deux étapes

Supprimons le répertoire blog

Supprimons le lien Blog de nos menus dans le fichier docusaurus.config.js

// La ligne à supprimer pour le Menu du Header !

{to: '/blog', label: 'Blog', position: 'left'},

// Les lignes à supprimer pour le footer :)

{

label: 'Blog',

to: '/blog',

Etape à suivre : on se place dans le dossier Blog et supprimer son contenu

on actualise la page et essayer de cliquer sur le Blog

On remarqué le message Not Found cela veut dire la page n’a pas trouvé nickel.

Et une chose il faut supprimer aussi le contenu du dossier Blog qui se trouve dans docusaurus.config.js

On supprime cette ligne

Idem dans la ligne footer on enlève aussi les lignes concernant Blog

On supprime cette partie

Si on retourne sur la page le menu Blog n’est plus là.

Ajoutons une nouvelle section dans notre documentation

Ajoutons un nouveau répertoire docs/BerengerDevOps

On se place dans le dossier docs et créer un nouveau dossier BerengerDevOps-Doc

Ensuite on crée un fichier _category_.json

Voici son contenu :

Créons un fichier _category_.json à la racine de ce répertoire et ajoutons-y quelques informations

{

"label": "BerengerDevOps - Doc",

"position": 4

}

Explication et pourquoi j’ai choisi la position 4 dans mon fichier _category_.json

On remarque dans le dossier Docs sur la capture il existe un sous dossier par défaut du nom de tutorial-extras et il existe un fichier _category_.json qui utilise la position 3 voir la capture en bas

Voici la raison au temps pour moi de choisir la position 4 sinon ça ne marchera, pas avec docusaurus la norme de numérotation compte énormément si on veut ajouter des sous dossiers et mettre des choses il faut apprendre comment on numérote la position de chaque dossier à publier.

Jusqu’à là on vient juste de créer le sous dossier de notre page et sans lui ajouter son contenu.

On crée un fichier demo.md

Voici son contenu

---

sidebar_position: 1

---

# Ceci est un H1

## Ceci est un H2

### Ceci est un H3

**Texte en gras**

*Texte en italique*

Ceci est une liste :

* Berenger

* Benam

> Ceci est un citation

:::danger Ceci est le titre du bloc !

Ceci est un blog de **DevOps**

:::

:::success

Ceci est un blog de **success**

:::

On va ajouter du code PHP a l’intérieur de notre fichier demo.md

Voici l’exemple :

```js
// Ceci est un extrait de code JS
const foo = {
bar: 'Berenger Benam',
}
```

```php
// Ceci est un extrait de code PHP
$foo = ['bar' => 'Berenger Benam'];
```
//ajout berenger
```php
// Ceci est un extrait de code PHP
$foo = ['bar' => 'Berenger Benam'];
//Quelle est la sortie de ce code?
$nbr1= 2;
$nbr2 = 2;
print $nbr1 . "+". $nbr2;
```

Voici le résultat sur la page

Donc sur cette page on a la possibilité de copier le code PHP.

On remarque pour prendre compte La coloration syntaxique on sait que par défaut le fichier md reconnait les codes js par contre pour PHP il faut ajouter la prise en compte de La coloration syntaxique avant que ça marche.

Sur cette capture on constate la coloration du code PHP n’est pas prise en compte deuxième ligne //ceci est un extrait de code PHP

Pour la prise en compte La coloration syntaxique on va dans le fichier docusaurus.config.js

On recherche la ligne prism (footer)

prism: {

theme: lightCodeTheme,

darkTheme: darkCodeTheme,

// Ajoutons le php avec cette ligne

additionalLanguages: ['php'],

Test sur la page :

Cette fois-ci la prise en compte de la coloration syntaxique de code php marche bien super !

-Comment Ajouter une Image dans la page de Docusaurus

On crée un dossier img-docusaurus puis envoyer la photo qu’on veut afficher a l’interieur.

Dans mon cas j’ai une photo dans mon répertoire personnel et je vais l’envoyer dans le dossier

img-docusaurus

Puis on édite le fichier demo.md et ajouter a la fin cette ligne

![photo Berenger](./img-docusaurus/berenger.jpg)

TEST :

Voici la photo qu’on vient d’ajouter à notre page.

Et c’est possible d’ajouter une Photo via son URL depuis GitHub ou bien GitLab.

Voici mon dépôt GitHub que je vais utiliser pour ce TP.

Mais a la fin il faut mettre ?row=true a la fin de l’url pour que ça marche.

Résultat :

Déploiement

Pour créer les fichiers statiques de votre site Web pour la production, exécutez :

npm run build

Les paramètres suivants sont requis docusaurus.config.js pour optimiser le routage et diffuser les fichiers à partir de l'emplacement correct :

Tester votre build localement

Il est important de tester votre build localement avant de le déployer en production. Docusaurus fournit une docusaurus servecommande pour cela :

npm run serve

Par défaut, cela chargera votre site à http://localhost:3000/

- Comment Ajouter un fichier PDF dans Docusaurus

il faut envoyer le fichier dans votre répertoire du projet et dans mon cas je l'ai mis ici (Voir la capture en bas)

Voici le fichier Rapport_Ansible_Berenger.pdf que je voulais inséré dans ma page Docusaurus.

Puis on édite le fichier demo.md

Voici la ligne a ajouté pour la prise en compte le fichier Pdf.

[Cliquez Ici pour lire mon Rapport sur Ansible et Jenkins](./Rapport_Ansible_Berenger.pdf)

Il suffit de cliquer sur le lien en bas de image

On remarque que ça marche très bien et on a la possibilité de télécharger même le fichier PDF sur l'ongle a droit.

Les tableaux

Faire de Tableau Avec le fichier md

Les barres verticales (|) permettent d’éditer des tableaux avec Markdown. Chaque cellule du tableau est séparée d’une barre verticale. Pour créer des lignes de titre qui se distinguent du reste du tableau, vous devrez souligner les cellules concernées avec les tirets du 6.

Il n’est pas nécessaire d’aligner les barres verticales les unes en dessous des autres. Si elles sont alignées, la lisibilité du tableau est cependant meilleure dans la version brute du document Markdown. La même chose s’applique aux barres verticales latérales. Elles n’ont aucune utilité pour la compilation du document.

Voici le résultat :

-Ajout de lien Url dans le fichier md.

Pour ajouter un lien dans le fichier Markdown et voici la syntaxe simple

[Ajout de lien dans le fichier markdown](https://www.ec2lt.sn/)

Test :

On clique sur Ajout de lien dans le fichier markdown

Voici le lien de l’École EC2LT

- Mettre les sous Chapitres dans le fichier MarkDown

Résultat :

Syntaxe MarkDown idée de balisage Audio et Vidéo en markdown

Un des problèmes empêchant cela est le manque d’un syntaxe markdown adaptée. Il faut que le balisage soit concis et discret pour que le code non interprété reste lisible.

Personnellement, sur mon blog perso j’en suis venu à faire cela :

Première Partie comment ajouter une Url vidéo dans le fichier md.

!::[La seule école de formation en télécommunications et réseaux qui pratique: EC2LT](https://www.youtube.com/watch?v=zo_oC_52CE8)

Sur cette capture j'ai ajouté L’URL du site EC2LT depuis YouTube.

Résultat :

Si on clique sur La seule école de formation en télécommunications et réseaux qui pratique: EC2LT il va rediriger sur le site EC2LT

Super !

partie 2 : Comment Ajoute une url Audio dans le fichier md.

!:[Cliquez sur ce lien pour Ecouter la Radio Ndeke-Luka de Bangui](https://www.radiondekeluka.org/popup_radio.php?)

Sur cette capture on ajouter URL de la radio Ndeke-Luka de Bangui

Résultat :

On clique sur Cliquez sur ce lien pour Ecouter la Radio Ndeke-Luka de Bangui

Super !

Deux avantages :

Ça reste assez discret
Il est même plus facile de discriminer les balises image/audio/video entre elles que de discriminer les balises image/lien entre elles (![titre-image](//url-image) et [titre-lien](//url-lien))

On peut imaginer une variante (mais j’aime moins parce que ce n’est pas indépendant de la langue de celui qui écrit, et on est plus facilement tenté de prononcer le balisage):

![titre-image](//url-image)
!a[titre-audio](//url-audio)
!v[titre-video](//url-video)

Ça ou autre ponctuation, j’aime bien l’idée de conserver et d’étendre la syntaxe ![titre](//url) pour tout média, l’idée d’insérer un discriminant entre le ! et le [ fait que c’est très simple à coder. Il est plus facile de distinguer !:[ de ![ que de distinguer [ sans ! précédent.

On pourrait imaginer aussi un caractère différent de : plutôt que le doubler pour la vidéo, par exemple!#[titre](//url), mais j’aime bien l’idée d’étendre selon la complexité du média (il y a rarement des vidéos sans son), c’est mnémotechnique.