Resolve "doc: how to creat new page"

README.md

@@ -34,10 +34,4 @@ If you are using GitHub pages for hosting, this command is a convenient way to b
 
 ## Create a new page
 
-We have two different ways to create a new page, in JavaScript, or, in Markdown: 
-
-- If we don't need a specific layout, we recommend to create a page in Markdown, with `.md` extention.
-- If we need to specific layout, create a page in JavaScript with `.js` extention.
-
-This offers a better return on investment because the Markdown (`.md`) is faster to do.
-
+[Follow this doc](doc/pages.md).

doc/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](https://Docusaurus.io/fr/docs/markdown-features/react), d'importer des composants React. Son utilisation permet d'utiliser la coloration syntaxique, les éditeurs de code en direct... Voir doc [MDX](https://mdxjs.com/)
+
+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](https://fr.reactjs.org/), la création de [composants](https://fr.reactjs.org/docs/components-and-props.html) et l'utilisation du [JSX](https://fr.reactjs.org/docs/introducing-jsx.html) (une extension syntaxique de JavaScript utilisée par React). 
+
+Vous pouvez consulter la doc officielle de [React](https://fr.reactjs.org/).
+
+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:
+
+```/src/pages/new-page-react.js
+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](https://Docusaurus.io/fr/docs/creating-pages) 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](https://Docusaurus.io/fr/docs/typescript-support) 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` :
+
+```/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](https://Docusaurus.io/fr/examples/markdownPageExample).
+
+
+## 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
+
+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](https://Docusaurus.io/fr/docs/Docusaurus.config.js).
+
+## Pour aller plus loin
+
+Voici quelques liens et informations pour approfondir certaines notions abordées dans cette doc.
+
+- [Utiliser les Composants dans React.js](https://fr.reactjs.org/docs/components-and-props.html).
+- [Une introduction au JSX](https://fr.reactjs.org/docs/introducing-jsx.html).
+- 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](https://www.w3schools.com/js/js_versions.asp). 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](http://es6-features.org/#StringInterpolation).
+- [Pour retrouver toutes les fonctionnalités du JavaScript](https://developer.mozilla.org/fr/docs/Web/JavaScript/A_re-introduction_to_JavaScript).