# Discovering Docusaurus A series of 3 article(s), in reading order. # Obtenir le nombre d'articles publiés > Découvrez la méthode simple et rapide pour afficher le nombre total d'articles publiés sur votre site Docusaurus à l'aide de composants personnalisés et de l'API du thème. --- ![Obtenir le nombre d'articles publiés](/img/v2/docusaurus_tips.webp) **TL;DR** Cet article montre une astuce rapide pour compter les articles publiés sur un blog Docusaurus : ouvrez la page `/blog/archive/` générée automatiquement, ouvrez la console de développement du navigateur et lancez une instruction `document.querySelectorAll` sur la liste des articles pour obtenir le total. Docusaurus ne proposait pas de moyen simple de récupérer le nombre d'articles du blog, mais il existe une astuce. *Si vous avez besoin de ce compteur **dans** votre site plutôt qu'une seule fois dans une console, le helper construit dans [Displaying related posts below our Docusaurus article](/blog/docusaurus-relatedposts) analyse déjà le front matter de chaque article et peut être réutilisé pour ça.* Il existe une page automatique appelée `archive`, comme [/blog/archive/](/blog/archive/). Sur cette page, tous les articles du blog sont affichés par année et par mois. Avec une instruction `document.querySelectorAll` dans la console, il est possible de faire le compte, comme suggéré sur ![La page archive](./images/archive.webp) Une fois la page archive affichée, appuyez sur `F12` pour lancer la **console de développement**. Cliquez sur l'onglet `Console` puis, dans la partie inférieure droite, copiez/collez l'instruction ci-dessous. ```js document.querySelectorAll("#__docusaurus_skipToContent_fallback > main > section > div > div > div > ul > li") ``` La première fois, la console vous préviendra que vous devez autoriser le collage (en français *autoriser le collage*). Tapez `allow paste` pour confirmer. Puis copiez/collez à nouveau. L'instruction `document.querySelectorAll` va récupérer chaque puce, c'est-à-dire la liste des articles. Vous verrez immédiatement le nombre, dans mon cas, comme illustré ci-dessous, `51` : ![Console](./images/console.webp) --- # Faire tourner son propre blog avec Docusaurus et Docker > Prenez le contrôle total de votre blog Docusaurus auto-hébergé dans un container Docker. Un guide pas à pas : personnalisation du site, montage de volumes et gestion du contenu. --- ![Faire tourner son propre blog avec Docusaurus et Docker](/img/v2/docusaurus_docker.webp) **TL;DR** Cet article de suivi montre comment personnaliser un blog Docusaurus dockerisé en copiant les fichiers clés (`docusaurus.config.js`, `src`, `static`) hors du container en cours d'exécution avec `docker compose cp`, puis en les montant comme volumes dans `compose.yaml`, de sorte que les modifications faites sur l'host soient reflétées en direct — titre du site, favicon, branding de la navbar, pages personnalisées et fichiers statiques. Cet article reprend là où [Running Docusaurus with Docker](/blog/docusaurus-docker/) s'était arrêté. Lisez-le d'abord et créez les fichiers nécessaires. Vous avez donc créé votre propre blog avec Docker et Docusaurus. En suivant les étapes expliquées dans l'article [Running Docusaurus with Docker](/blog/docusaurus-docker/), vous disposez maintenant d'un blog dont la liste des articles est stockée sur votre machine, dans un dossier `blog`. Allons plus loin. *Et quand votre blog est prêt à quitter votre machine, [Encapsulate an entire Docusaurus site in a Docker image](/blog/docker-docusaurus-prod) l'empaquette pour la production, tandis que [GitHub - Use Actions to deploy this blog](/blog/github-action) le publie automatiquement à chaque push. Une fois en ligne, [How to self-host Matomo](/blog/matomo-install) vous dit qui le lit.* Dans l'article précédent, nous avons créé un dossier sur votre disque ; nous allons le réutiliser. Lancez `cd /tmp/docusaurus` pour y entrer, puis ouvrez le dossier dans votre éditeur (de mon côté, je lance `code .`). Dans Visual Studio Code, vous devriez voir ceci (sinon, relisez et exécutez les commandes du premier article) : ![Point de départ dans vscode](./images/vscode_starting_point.webp) Et en lançant `docker compose up --detach --build` pour démarrer le blog, vous obtiendrez cet écran : > Screenshot — http\://localhost:3000 > > ![Blog au point de départ](./images/blog_starting_point.webp) ## Personnaliser le nom, le titre, les icônes et l'URL de votre site {#customize-the-name-title-icons-and-url-of-your-site} Pour l'instant, on voit *My Site* en haut à gauche de l'écran. Il y a un fichier très important dans Docusaurus : `docusaurus.config.js` (). Nous devons l'adapter à nos envies. > **Il nous faut le fichier sur notre ordinateur:** > > Ok, maintenant, un concept très important : nous devons garder sur notre ordinateur une copie de tout ce que nous voulons modifier. > > Pour copier un fichier depuis notre container vers notre disque, la commande à utiliser est `docker compose cp :/file/path/within/container /host/path/to/copy/file/to` Donc, pour copier le fichier `docusaurus.config.js` sur votre disque, lancez `docker compose cp blog:/app/docusaurus.config.js /tmp/docusaurus/docusaurus.config.js` (remplacez `/tmp/docusaurus` par le nom du dossier où vous avez créé votre blog, sur votre disque dur). Une fois la copie faite, vous retrouvez le fichier dans votre éditeur : ![Docusaurus.config.js sur le disque local](./images/docusaurus.config.js.webp) Et la deuxième chose à faire pour pouvoir modifier le fichier et refléter les changements dans notre container Docker, c'est de monter le fichier. Éditez votre fichier `compose.yaml` et ajoutez la ligne surlignée ci-dessous : ```yaml name: my_docusaurus_blog services: blog: build: . ports: - 3000:3000 user: 1000:1000 volumes: - ./blog:/app/blog //highlight-next-line - ./docusaurus.config.js:/app/docusaurus.config.js ``` On y est presque : il faut recréer notre container, donc on relance `docker compose up --detach`. En rafraîchissant la page web, on ne verra aucun changement mais... modifions maintenant le fichier `docusaurus.config.js`. Ouvrez donc `docusaurus.config.js` et cherchez `themeConfig`, puis, à l'intérieur, le nœud `navbar`. Vous trouverez quelque chose comme ceci : ![La navbar dans config.js](./images/navbar_default.webp) Changez le texte comme vous voulez, par exemple : ```js navbar: { title: 'Welcome world!', logo: { alt: 'It\'s a photo of me ... or not', src: 'https://i.pravatar.cc/300', }, } ``` Sauvez, rafraîchissez votre navigateur et vous obtenez : > Screenshot — http\://localhost:3000 > > ![Ma propre navbar](./images/navbar_me.webp) > **Vous venez d'apprendre un concept très important !:** > > Quand vous voulez pouvoir modifier un fichier présent dans un container, vous devez récupérer le fichier sur votre disque (1) puis synchroniser le fichier entre votre ordinateur et le container (2). > > Pour la première étape, la commande à utiliser est `docker compose cp` suivie du nom du container (regardez votre fichier `compose.yaml`, c'est le nom du service), puis vous indiquez où le fichier est stocké dans le container et où le copier sur votre disque. C'est pour ça que nous avons utilisé `docker compose cp blog:/app/docusaurus.config.js docusaurus.config.js`. > > La deuxième étape consiste à faire en sorte que les changements dans ce fichier copié soient reflétés entre votre host et le container : c'est pourquoi nous avons mis à jour la liste des `volumes` dans le fichier `compose.yaml`. Désormais, les changements faits sur votre disque ou par le container sont synchronisés des deux côtés. Étape suivante, toujours dans le fichier `docusaurus.config.js` : cherchez `title`, `favicon` et `url`, puis renseignez vos propres valeurs, par exemple : ```js const config = { title: 'MyBlog', favicon: 'https://www.iconarchive.com/download/i75799/martz90/circle/android.ico', url: 'https://yoursite.com', // ... }; ``` > Screenshot — http\://localhost:3002/blog > > ![Favicon](./images/favicon.webp) > **Un simple rafraîchissement suffit:** > > Cette fois, pas besoin de relancer la commande `docker up` : appuyez simplement sur `F5` pour voir vos changements directement dans le navigateur. > **Lisez la documentation officielle:** > > Vous pouvez faire bien plus en modifiant le fichier `docusaurus.config.js` ; référez-vous à la documentation officielle . ## Le dossier src/pages {#the-srcpages-folder} Le dossier `src/pages` contient des fichiers comme `index.md` qui seront convertis en `index.html` (votre page d'accueil, donc). Vous pouvez aussi créer un fichier appelé `tutorial.md` (qui deviendra `tutorial.html`) et créer une entrée de menu dans votre barre de navigation avec `/tutorial.html` comme cible. Vous devez copier le dossier du container vers votre host, comme vous l'avez déjà vu. Lancez la commande ci-dessous pour copier le dossier sur votre host : ```bash $ docker compose cp blog:/app/src src ``` Vous devez mettre à jour votre fichier `compose.yaml` et ajouter la ligne surlignée ci-dessous : ```yaml name: my_docusaurus_blog services: blog: build: . ports: - 3000:3000 user: 1000:1000 volumes: - ./blog:/app/blog - ./docusaurus.config.js:/app/docusaurus.config.js //highlight-next-line - ./src:/app/src ``` ## Le dossier static {#the-static-folder} Ce dossier contient les fichiers qui seront copiés dans votre répertoire racine lors du déploiement de votre blog. C'est donc l'endroit parfait pour mettre, par exemple, un fichier `.htaccess` ou `robots.txt`. > **Cas d'usage réel:** > > De mon côté, j'utilise le dossier static pour stocker mes images communes (celles que j'utilise plusieurs fois). J'ai donc créé un dossier `static/img` sur mon blog. Ce dossier sera copié vers `/img` (directement sous la racine) sur mon serveur. Accéder aux images dans mes articles devient alors facile : la source ressemblera à `/img/image_name.ext`. Lancez la commande ci-dessous pour copier le dossier sur votre host : ```bash $ docker compose cp blog:/app/static static ``` Et mettez à jour votre fichier `compose.yaml` comme ceci : ```yaml name: my_docusaurus_blog services: blog: build: . ports: - 3000:3000 user: 1000:1000 volumes: - ./blog:/app/blog - ./docusaurus.config.js:/app/docusaurus.config.js - ./src:/app/src //highlight-next-line - ./static:/app/static ``` ## Vous avez maintenant les bases {#you-now-have-the-basics} Poursuivez votre route, rendez-vous sur et lisez la documentation. Trouvez aussi l'inspiration dans la *Docusaurus Site Showcase* : . Le clavier est à vous ! N'attendez pas, commencez à écrire votre blog dès maintenant ! --- # Quelques trucs et astuces pour écrire des articles Docusaurus > Boostez vos articles Docusaurus avec quelques astuces essentielles. Apprenez à ajouter des Admonitions, à appliquer du style inline et à mettre en évidence des lignes de code. --- ![Quelques trucs et astuces pour écrire des articles Docusaurus](/img/v2/docusaurus_tips.webp) **TL;DR** Cet article est un pense-bête des fonctionnalités d'écriture essentielles de Docusaurus : le marqueur `truncate` pour les aperçus d'articles de blog, les admonitions pour les encadrés, le style inline avec ``, un composant `Highlight` personnalisé pour du texte coloré, et `// highlight-next-line` pour attirer l'attention sur les lignes modifiées dans un bloc de code. Si vous écrivez pour Docusaurus, il y a quelques astuces à connaître. Cet article est loin d'être exhaustif mais, pour moi, c'est un rappel des fonctionnalités vraiment essentielles à ne pas oublier. *Deux autres habitudes d'écriture à adopter tôt : garder vos [tags sous contrôle](/blog/docusaurus-tags) et [afficher les articles liés](/blog/docusaurus-relatedposts) sous chaque article.* ## Lire la suite {#read-more} [Documentation officielle](https://docusaurus.io/docs/blog#blog-list) En mode blog, votre article est divisé en deux parties : l'introduction avec un lien *Lire la suite*, puis le corps de l'article. Pour activer cette fonctionnalité, il suffit d'ajouter la ligne `` (précédée et suivie d'une ligne vide) là où vous souhaitez séparer l'introduction du corps. Si vous allez sur ma page [blog](/blog), chaque article a une introduction suivie d'une ligne `` dans ma source Markdown. ## Admonitions {#admonitions} [Documentation officielle](https://docusaurus.io/docs/markdown-features/admonitions) Sert à mettre en évidence un paragraphe de votre document, par exemple un encadré *Attention à...* ou *Astuce : saviez-vous que...*. ```markdown Never give your bank card code to a stranger. ``` Sera affiché par Docusaurus comme ceci : > **Attention à...:** > > Ne donnez jamais le code de votre carte bancaire à un inconnu. ## Style inline {#inline-style} Docusaurus supporte le style inline grâce à la notation ` ... `. La notation `I'm written in blue` donnera je suis écrit en bleu. Utilisé de temps en temps, c'est une manière très simple de changer le style d'un contenu sur votre page. ### Le composant Highlight {#highlight-component} Si votre ambition est de surligner du texte, il y a une meilleure solution : le **composant Highlight**. Créez le fichier `src/components/Highlight/index.tsx` : **src/components/Highlight/index.tsx** ```typescript /** * Highlight Component * * A simple React component used to emphasize inline content with a custom background color. * Typically used in blog posts or documentation pages within a Docusaurus site. * * Example usage: * Important note */ import type { JSX, ReactNode } from "react"; interface Props { children: ReactNode; color: string; } export default function Highlight({ children, color }: Props): JSX.Element { return ( {children} ); } ``` Éditez ensuite (ou créez) le fichier `src/theme/MDXComponents.js`. Si le fichier existe déjà, ajoutez simplement les lignes surlignées ci-dessous. S'il n'existe pas encore, créez-le avec le contenu ci-dessous : **src/theme/MDXComponents.js** ```javascript import React from "react"; import MDXComponents from "@theme-original/MDXComponents"; // [...] // highlight-next-line import Highlight from "@src/components/Highlight"; export default { // Reusing the default mapping ...MDXComponents, // [...] // highlight-next-line Highlight }; ``` Le **vert Docusaurus** et le **bleu Facebook** sont mes couleurs préférées. Source : [MDX and React](https://docusaurus.io/docs/markdown-features/react#exporting-components) ## Mettre des lignes en évidence {#highlight-lines} [Documentation officielle](https://docusaurus.io/docs/markdown-features/code-blocks#line-highlighting) `// highlight-next-line` est **vraiment** utile quand vous voulez mettre en évidence les modifications que vous avez faites dans un bloc de code. *Quand le code vit dans un vrai fichier plutôt qu'en inline, j'utilise mon propre [composant de snippets de code](/blog/docusaurus-snippets), qui lit le fichier au moment du build : l'article ne peut donc jamais être désynchronisé.* Imaginez que vous avez déjà écrit quelque chose comme *Cher lecteur, créez un fichier sur votre disque avec ce contenu...* et que vous fournissez un bloc de code avec ce contenu. Plus loin dans votre article, vous demandez *éditez le fichier et faites ceci, ajoutez telle et telle ligne, ici et là*. Avec `// highlight-next-line`, il est très facile de mettre les changements en évidence, par exemple : **compose.yaml** ```yaml name: kingsbridge services: joomla: image: joomla restart: always ports: - 8080:80 environment: - JOOMLA_DB_HOST=joomladb - JOOMLA_DB_PASSWORD=example # highlight-next-line user: 1000:1000 # highlight-next-line volumes: # highlight-next-line - ./site_joomla:/var/www/html joomladb: image: mysql:8.0.13 restart: always environment: - MYSQL_ROOT_PASSWORD=example # highlight-next-line user: 1000:1000 # highlight-next-line volumes: # highlight-next-line - ./db:/var/lib/mysql ``` Vous voyez immédiatement où j'ai fait des modifications dans le contenu du fichier. ---