Pour tout problème contactez-nous par mail : support@froggit.fr | La FAQ :grey_question: | Rejoignez-nous sur le Chat :speech_balloon:

Skip to content
Snippets Groups Projects
Commit 8ee07c82 authored by Hugues's avatar Hugues Committed by Christophe Chaudier
Browse files

Resolve "doc: how to creat new page"

parent adad8a3c
No related branches found
No related tags found
1 merge request!13Resolve "doc: how to creat new page"
...@@ -34,10 +34,4 @@ If you are using GitHub pages for hosting, this command is a convenient way to b ...@@ -34,10 +34,4 @@ If you are using GitHub pages for hosting, this command is a convenient way to b
## Create a new page ## Create a new page
We have two different ways to create a new page, in JavaScript, or, in Markdown: [Follow this doc](doc/pages.md).
- 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.
# 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).
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment