pages.md

Création des pages

Docusaurus permet de créer des pages de façons différentes, en Markdown (.md), en JavaScript (.js).

• Si nous n'avons pas besoin d'un layout spécifique pour la page à créer, nous créons une page en Markdown.
• Si, au contraire, nous avons besoin d'un Layout spécifique ou de charger un certains styles (CSS) pour notre nouvelle page, alors nous créons une page en JavaScript (.js).
• Enfin, nous pouvons également utiliser le MDX (une évolution du Markdown). Le MDX utilise la simplicité du Markdown, tout en permettant d'utiliser du JSX, d'importer des composants React. Son utilisation permet d'utiliser la coloration syntaxique, les éditeurs de code en direct... Voir doc MDX

L'utilisation du Markdown offre un meilleur retour sur investissement car il est beaucoup plus simple et rapide à écrire.

Créer une page en JavaScript

Pour créer une page en JavaScript, nous allons pouvoir nous appuyer sur de nombreux concepts de programmation introduits par React.js, comme les composants, le JSX (syntaxe utilisé par React) car Docusaurus est basé sur la librairie React.js.

Cette section demande des connaissances en JavaScript, et une maîtrise de l'ES6 (voir Pour aller plus loin), une version récente de JavaScript, apportant de nouvelles normes à ce langage, et dont React utilise certains aspects.

Le code affiché dans la seconde partie, nécessite la création d'une fonction qui fait appel à des notions propre à React.js. Nous allons créer un composant React. La création de ce composant va nous permettre de créer notre page en JavaScript (ce composant représente notre nouvelle page).

Afin de mieux comprendre ce chapitre, il peut être intéressant d'apprendre le fonctionnement de React, la création de composants et l'utilisation du JSX (une extension syntaxique de JavaScript utilisée par React).

Vous pouvez consulter la doc officielle de React.

Vous retrouverez à la fin de cette doc d'autres liens pour vous aider à comprendre certaines notions de programmation nécessaires à l'utilisation de React.

1. Dans le dossier pages, créer un fichier /src/pages/new-page-react.js
2. Y créer une fonction qui va permettre de rendre une vue:

import React from 'react';
import Layout from '@theme/Layout';

function Hello() {
  return (
    <Layout title="Bonjour">
      <div
        style={{
          display: 'flex',
          justifyContent: 'center',
          alignItems: 'center',
          height: '50vh',
          fontSize: '20px',
        }}>
        <p>
          Editez <code>pages/new-page-react.js</code> et sauvegardez pour recharger.
        </p>
      </div>
    </Layout>
  );
}
export default Hello;

Docusaurus génère un composant Layout par défaut, c'est un composant de mise en page qui va inclure d'autres composants tels que la _navbar_, le footer...

Il nous suffit alors de lancer le serveur de développement pour avoir accès à notre nouvelle page.

Nous pouvons désormais nous rendre sur l'URL: http://localhost:3000/new-page-react (le serveur utilise le port 3000 par défaut).

Pour de plus amples détails, veuillez consulter la doc de Docusaurus sur la création de pages.

Utiliser le TypeScript au lieu de JavaScript?

Docusaurus permet également de créer des pages TypeScript avec l'extension .tsx, en remplacement du JavaScript. Le TypeScript impose un typage fort (le JavaScript étant un langage très peu typé), si une erreur de type apparaît dans le code, TypeScript fera apparaître cette erreur, là où le JavaScript restera permissif. TypeScript présente des avantages certains en terme de qualité et de sécurité du code, mais il peut être difficile et long à apprendre et à maîtriser sur un framework comme React.

Pour installer et configurer TypeScript sur votre projet, consulter la page de Support TypeScript sur la doc de Docuraurus.

Comment créer une page en Markdown?

Dans le dossier pages, nous allons créer un nouveau fichier /src/pages/new-page-markdown.md :

---
title: titre de page
description: description de page
---


## Bonjour

Comment allez-vous ?

De la même manière, une page sera créée à l'adresse http://localhost:3000/new-page-markdown.

Les pages Markdown sont moins flexibles que les pages React, car elles utilisent toujours la mise en page du thème, mais elles sont bien plus simple et rapide à créer.

Voici un exemple de page Markdown.

Configuration

Comment ajouter un lien vers une page dans les composants Navbar et Footer:

Nous allons utiliser le fichier Docusaurus-config.js, dans lequel nous pourrons configurer notre Navbar et notre Footer très facilement.

Nous retrouvons dans ce fichier un objet, nommé themeConfig qui permet de définir des valeurs pour la navbar et le footer au travers d'un tableau d'objets clés / valeurs:

Reprenons nos pages précédentes, new-page-react.js et new-page-markdown.js. Nous pouvons configurer la navbar et le footer pour créer un lien vers ces pages:

themeConfig: {
    navbar: {
      items: [      
        {to: "/new-page-react", label: "TitreDuLien", position: "left"},
      ],
    },
    footer: {
      links: [
        {
          title: "Columne Name",
         items: [
            { to: "/new-page-markdown", label: "TitreDuLien"},
          ],
        },
      ],
    },
  },

Nous pouvons retrouver notre composant footer sous la forme d'un objet, qui va contenir par exemple un tableau items dans lequel une clé label va définir la valeur du titre du lien qui sera affiché : TitreDuLien.

Vous trouverez plus d'explications sur la configuration du fichier Docusaurus.config.js sur la page de la doc de Docusaurus.

Pour aller plus loin

Voici quelques liens et informations pour approfondir certaines notions abordées dans cette doc.

• Utiliser les Composants dans React.js.
• Une introduction au JSX.
• l'ECMAScript et l'ES6 : l'ECMAScript est une norme pour les langages de script tel que JavaScript. Vous pouvez retrouver toutes les versions d'ECMAScript avec leurs fonctionnalités ici. Une nouvelle version, nommée ECMAScript 2015, ou ES6, a apporté de nombreux changements au JavaScript. React utilise beaucoup l'ES6 (fonctions fléchées, les nouvelles méthodes de manipulation des tableaux, les classes, les instructions let, et const).
• Vous pouvez retrouver la liste des fonctionnalités apportées à JavaScript par l'ES6 ici.
• Pour retrouver toutes les fonctionnalités du JavaScript.