Quelques trucs et astuces pour écrire des articles Docusaurus

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 et afficher les articles liés sous chaque article.

Lire la suite​

Documentation officielle

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 <!-- truncate --> (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, chaque article a une introduction suivie d'une ligne <!-- truncate --> dans ma source Markdown.

Admonitions​

Documentation officielle

Sert à mettre en évidence un paragraphe de votre document, par exemple un encadré Attention à... ou Astuce : saviez-vous que....

<AlertBox variant="caution" title="Pay attention to...">
Never give your bank card code to a stranger.

</AlertBox>

Sera affiché par Docusaurus comme ceci :

Style inline​

Docusaurus supporte le style inline grâce à la notation <span> ... </span>.

La notation <span style={{color: 'blue'}}>I'm written in blue</span> 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​

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 :

/**
 * 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:
 * <Highlight color="#ff4081">Important note</Highlight>
 */

import type { JSX, ReactNode } from "react";?

interface Props {?
  children: ReactNode;
  color: string;
}

export default function Highlight({ children, color }: Props): JSX.Element {?
  return (
    <span
      style={{?
        backgroundColor: color,
        borderRadius: "2px",
        color: "#fff",
        padding: "0.2rem",
      }}
    >
      {children}
    </span>
  );
}

É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 :

import React from "react";

import MDXComponents from "@theme-original/MDXComponents";

// [...]

import Highlight from "@src/components/Highlight";

export default {
  // Reusing the default mapping
  ...MDXComponents,

  // [...]

  Highlight
};

Le vert Docusaurus et le bleu Facebook sont mes couleurs préférées.

Source : MDX and React

Mettre des lignes en évidence​

Documentation officielle

// 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, 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 :

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.