Post

Docusaurus statique "DebianStretchNode" (VirtualBox/PC1)

Posté
Par Yann
12 min lire
Docusaurus statique "DebianStretchNode" (VirtualBox/PC1)

Debian Stretch

Debian 9

  • Serveur virtuel 64 bits VirtualBox : DebianStretchNode
  • machine : dbs
  • domaine :
  • root : ytreu49
  • Utilisateur : dbsuser
  • Mot de passe : dbsuser49

IP fixe , modifier le fichier /etc/network/interfaces

1
2
3
4
5

auto enp0s3
iface enp0s3 inet static
address 192.168.0.40
netmask 255.255.255.0
gateway 192.168.0.254

Sauver et redémarrer le serveur virtuel…
Accès ssh

1

ssh dbsuser@192.168.0.40

Node et Yarn

Node.js

Comment installer Node.js via une archive binaire sous Linux ?
Dézippez l’archive binaire dans le répertoire de votre choix pour installer Node, j’utilise /usr/local/lib/nodejs

1
2
3
4
5

wget https://nodejs.org/dist/v10.15.3/node-v10.15.3-linux-x64.tar.xz
VERSION=v10.15.3
DISTRO=linux-x64
sudo mkdir -p /usr/local/lib/nodejs
sudo tar -xJvf node-$VERSION-$DISTRO.tar.xz -C /usr/local/lib/nodejs

Définir la variable d’environnement ~/.profile, ajouter ci-dessous à la fin

1
2
3
4

# Nodejs
VERSION=v10.15.3
DISTRO=linux-x64
export PATH=/usr/local/lib/nodejs/node-$VERSION-$DISTRO/bin:$PATH

Rafraîchir le profil

1

. ~/.profile

Tester l’installation en utilisant

1
2
3
4

node -v
    v10.15.3

npm version

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{ npm: '6.4.1',
  ares: '1.15.0',
  cldr: '33.1',
  http_parser: '2.8.0',
  icu: '62.1',
  modules: '64',
  napi: '3',
  nghttp2: '1.34.0',
  node: '10.15.3',
  openssl: '1.1.0j',
  tz: '2018e',
  unicode: '11.0',
  uv: '1.23.2',
  v8: '6.8.275.32-node.51',
  zlib: '1.2.11' }

1
2

npx -v
    6.4.1

Pour créer un lien sudo :

1
2
3

sudo ln -s /usr/local/lib/nodejs/node-$VERSION-$DISTRO/bin/node /usr/bin/node
sudo ln -s /usr/local/lib/nodejs/node-$VERSION-$DISTRO/bin/npm /usr/bin/npm
sudo ln -s /usr/local/lib/nodejs/node-$VERSION-$DISTRO/bin/npx /usr/bin/npx

yarn

Installer Yarn

1
2
3
4

sudo apt install apt-transport-https curl
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt-get update && sudo apt-get install yarn

Note : En raison de l’utilisation de nodejs à la place du nom node dans certaines distributions, yarn peut se plaindre que node ne soit pas installé. Une solution de contournement est d’ajouter un alias dans votre fichier .bashrc, comme ceci :
alias node=nodejs
Ceci pointera le fil à n’importe quelle version du node que vous décidez d’utiliser.

Version

1
2

yarn --version
     1.16.0

Docusaurus

Docusaurus – Pour créer et maintenir vos sites de documentations, rédaction grâce à la syntaxe markdown avant d’être généré sous la forme de fichiers HTML statiques.

Installation

Docusaurus a été conçu de A à Z pour être facilement installé et utilisé pour rendre votre site web opérationnel rapidement.
Nous avons créé un script facile qui vous permettra de mettre en place toute l’infrastructure nécessaire :

  1. Assurez-vous d’avoir la dernière version de Node installée. Nous vous recommandons également d’installer Yarn.
    • Vous devez être sur Node >= 8.x et Yarn >= 1.5. * Créez un projet, s’il n’existe pas, et allez au répertoire racine de ce projet.
      sudo mkdir -p /srv/docusaurus && sudo chown $USER.$USER -R /srv/docusaurus && cd /srv/docusaurus
      Vous allez créer les documents dans ce répertoire. Le répertoire racine peut contenir d’autres fichiers. Le script d’installation de Docusaurus va créer deux nouveaux répertoires : docs et website.
      Généralement, un projet GitHub existant ou nouvellement créé sera l’emplacement de votre site Docusaurus, mais ce n’est pas obligatoire pour utiliser Docusaurus. * Exécutez le script d’installation Docusaurus : npx docusaurus-init * Si vous n’avez pas Node 8.2+ ou si vous préférez installer Docusaurus globalement, exécutez
      yarn global add docusaurus-init ou npm install --global docusaurus-init
      Ensuite, lancez docusaurus-init

Vérification de l’installation

En plus des fichiers et répertoires précédemment existants, votre répertoire racine contiendra désormais une structure similaire à :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

docusaurus
├── Dockerfile
├── docker-compose.yml
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   ├── exampledoc4.md
│   └── exampledoc5.md
└── website
    ├── README.md
    ├── blog
    │   ├── 2016-03-11-blog-post.md
    │   ├── 2017-04-10-blog-post-two.md
    │   ├── 2017-09-25-testing-rss.md
    │   ├── 2017-09-26-adding-rss.md
    │   └── 2017-10-24-new-version-1.0.0.md
    ├── core
    │   └── Footer.js
    ├── package.json
    ├── pages
    │   └── en
    │       ├── help.js
    │       ├── index.js
    │       └── users.js
    ├── sidebars.json
    ├── siteConfig.js
    ├── static
    │   ├── css
    │   │   └── custom.css
    │   └── img
    │       ├── favicon.ico
    │       ├── oss_logo.png
    │       ├── undraw_code_review.svg
    │       ├── undraw_monitor.svg
    │       ├── undraw_note_list.svg
    │       ├── undraw_online.svg
    │       ├── undraw_open_source.svg
    │       ├── undraw_operating_system.svg
    │       ├── undraw_react.svg
    │       ├── undraw_tweetstorm.svg
    │       └── undraw_youtube_tutorial.svg
    └── yarn.lock

Exécution du site Web d’exemple (website)

Après avoir exécuté le script d’initialisation Docusaurus, docusaurus-init, comme décrit dans la section Installation, vous aurez un site Web d’exemple exécutable à utiliser comme base de votre site.

1

cd website

Dans le répertoire du site Web, exécutez le serveur Web local à l’aide de la commande

1

yarn start # ou npm start.

1
2
3
4
5

yarn run v1.16.0
warning package.json: No license field
$ docusaurus-start
LiveReload server started on port 35729
Docusaurus server started on port 3000

Chargez le site d’exemple via http://192.168.0.40:3000 s’il ne s’ouvre pas déjà automatiquement. Si le port 3000 a déjà été pris, un autre port sera utilisé. Regardez les messages de la console pour voir lesquels.

Vous devriez voir l’exemple du site chargé dans votre navigateur Web. Il y a aussi un serveur LiveReload en cours d’exécution et toute modification apportée aux documents et fichiers dans le répertoire du site Web entraînera le rafraîchissement de la page. Une couleur de thème primaire et secondaire générée au hasard sera choisie pour vous.

Lancer le serveur derrière un proxy
Si vous êtes derrière un proxy d’entreprise, vous devez le désactiver pour les requêtes du serveur de développement. Cela peut être fait en utilisant la variable d’environnement NO_PROXY.

1
2

SET NO_PROXY=localhost
yarn start # (or npm run start)

Mise à jour de la version Docusaurus

A tout moment après l’installation de Docusaurus, vous pouvez vérifier votre version actuelle de Docusaurus en vous rendant dans le répertoire du site Web et en tapant yarn outdated

Vous verrez quelque chose comme ceci :

1
2
3
4
5
6
7
8
9
10
11

Using globally installed version of Yarn
yarn outdated v1.5.1
warning package.json: No license field
warning No license field
info Color legend :
 "<red>"    : Major Update backward-incompatible updates
 "<yellow>" : Minor Update backward-compatible features
 "<green>"  : Patch Update backward-compatible bug fixes
Package    Current Wanted Latest Package Type    URL
docusaurus 1.0.9   1.2.0  1.2.0  devDependencies https://github.com/facebook/Docusaurus#readme
✨  Done in 0.41s.

S’il n’y a pas de version visible des commandes obsolètes, alors vous êtes à jour.

1
2
3
4

yarn outdated v1.16.0
warning package.json: No license field
warning No license field
Done in 0.33s.

Vous pouvez mettre à jour vers la dernière version de Docusaurus par :

1
2
3

yarn upgrade docusaurus --latest
ou
npm update docusaurus

Si vous constatez des erreurs après votre mise à niveau, essayez soit de vider votre cache Babel (généralement dans un répertoire temporaire, soit d’exécuter le serveur Docusaurus (par exemple, yarn start) avec la configuration d’environnement BABEL_DISABLE_CACHE=1.

Préparation du site

Après avoir installé Docusaurus, vous avez maintenant un squelette à partir duquel travailler pour votre site Web spécifique. Ce qui suit traite du reste de la structure de Docusaurus afin que vous puissiez préparer votre site.

Structure du répertoire

Comme vous pouvez le voir après avoir installé Docusaurus, le script d’initialisation a créé une structure de répertoire similaire à :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

root-directory
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   ├── exampledoc4.md
│   └── exampledoc5.md
└── website
    ├── blog
    │   ├── 2016-03-11-blog-post.md
    │   ├── 2017-04-10-blog-post-two.md
    │   ├── 2017-09-25-testing-rss.md
    │   ├── 2017-09-26-adding-rss.md
    │   └── 2017-10-24-new-version-1.0.0.md
    ├── core
    │   └── Footer.js
    ├── package.json
    ├── pages
    ├── sidebars.json
    ├── siteConfig.js
    └── static

Description des répertoires

  • Fichiers source de la documentation : Le répertoire docs contient des exemples de fichiers de documentation écrits en Markdown
  • Blog : Le répertoire website/blog contient des exemples de billets de blog écrits en Markdown.
  • Pages : Le répertoire website/pages contient des exemples de pages de premier niveau pour le site.
  • Fichiers et images statiques : Le répertoire website/static contient des ressources statiques utilisées par le site exemple.

Fichiers clés

  • Pied de page : Le fichier website/core/Footer.js est un composant React qui sert de pied de page pour le site généré par Docusaurus et doit être personnalisé par l’utilisateur.
  • Fichier de configuration : Le fichier website/siteConfig.js est le principal fichier de configuration
  • Encadrés (sidebars) : Le fichier sidebars.json contient la structure et l’ordre des fichiers de documentation.

Notes de préparation

Vous devrez conserver les fichiers website/siteConfig.js et website/core/Footer.js mais vous pouvez les modifier comme vous le souhaitez. La valeur de la clé customDocsPath dans website/siteConfig.js peut être modifiée si vous souhaitez utiliser un nom de répertoire ou un chemin différent. Le répertoire du website peut également être renommé comme vous le souhaitez.

Cependant, vous devriez conserver les répertoires website/pages et website/static. Vous pouvez modifier le contenu à l’intérieur comme vous le souhaitez. Au minimum, vous devriez avoir un fichier en/index.js ou en/index.html à l’intérieur du website/pages et une image à utiliser comme icône d’en-tête dans website/static

Création du site

La structure de votre site ressemble à ce qui suit :

1
2
3
4
5
6
7
8
9
10
11

root-directory
├── docs
└── website
    ├── blog
    ├── core
    │   └── Footer.js
    ├── package.json
    ├── pages
    ├── sidebars.json
    ├── siteConfig.js
    └── static

Cela suppose que vous avez supprimé les fichiers.md d’exemple qui ont été installés avec le script d’initialisation.

  • Tous les fichiers de documentation doivent être placés dans le répertoire docs en tant que fichiers markdown .md
  • Tous les billets de blog doivent se trouver dans le répertoire blog

Créez votre site de base

Pour créer un site entièrement fonctionnel, il vous suffit de quelques étapes :

1-Ajoutez votre documentation dans le répertoire /docs sous forme de fichiers .md, en vous assurant d’avoir le bon en-tête dans chaque fichier. L’en-tête le plus simple serait le suivant, où id est le nom du lien (p. ex. docs/intro.html) et le titre est le titre de la page Web.

1
2
3
4
5
6

---
id: intro
title: Getting Started
---

My new content here..

2-Ajoutez zéro ou plusieurs docs au fichier sidebars.json pour que votre documentation soit rendue dans une sidebar.

Si vous n’ajoutez pas votre documentation au fichier sidebars.json, les documents seront rendus, mais ils ne peuvent être liés qu’à partir d’autres documents et visités avec l’URL connue.

3-Modifiez le fichier website/siteConfig.js pour configurer votre site, en suivant les commentaires inclus dans la documentation et le fichier website/siteConfig.js pour vous guider.

4-Créez des pages personnalisées et/ou personnalisez le fichier website/core/Footer.js qui fournit le pied de page pour votre site.

5-Placez les ressources, telles que les images, dans le répertoire website/static/

6-Exécutez le site pour voir les résultats de vos changements.

1
2
3

cd website
yarn run start # or `npm run start`
# Navigate to http://localhost:3000

Personnalisation spéciale

Docs Landing Page

Si vous préférez que votre page d’accueil soit directement reliée à votre documentation, vous pouvez le faire via une redirection.

1-Supprimez le fichier index.js du répertoire website, s’il existe.

2-Ajoutez une page index.html statique personnalisée dans le répertoire website/static avec le contenu suivant :

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<!DOCTYPE HTML>
<html lang="en-US">
  <head>
    <meta charset="UTF-8">
    <meta http-equiv="refresh" content="0; url=docs/id-of-doc-to-land-on.html">
    <script type="text/javascript">
      window.location.href = 'docs/id-of-doc-to-land-on.html';
    </script>
    <title>Your Site Title Here</title>
  </head>
  <body>
    If you are not redirected automatically, follow this <a href="docs/id-of-doc-to-land-on.html">link</a>.
  </body>
</html>

Vous obtiendrez l’identifiant du document pour atterrir sur les métadonnées .md de cette page doc.

Blog seulement

Vous pouvez également utiliser Docusaurus pour héberger votre blog uniquement (en).

Publication de votre site

Vous devriez maintenant avoir un site qui fonctionne localement. Une fois que vous l’avez personnalisé à votre goût, il est temps de le publier. Docusaurus génère un site Web HTML statique qui est prêt à être servi par votre serveur Web préféré ou votre solution d’hébergement en ligne.

Création de pages HTML statiques

Pour créer une compilation statique de votre site Web, exécutez le script suivant à partir du répertoire du site Web :

1

yarn run build # ou `npm run build` ou `npm run build

Ceci générera un répertoire build à l’intérieur du répertoire website contenant les fichiers .html de tous vos documents et des autres pages incluses dans pages

Hébergement de pages HTML statiques

A ce stade, vous pouvez récupérer tous les fichiers à l’intérieur du répertoire website/build et les copier dans le répertoire html de votre serveur Web préféré.

Par exemple, Apache et Nginx servent par défaut le contenu de /var/www/html. Cela dit, le choix d’un serveur Web ou d’un fournisseur n’est pas du ressort de Docusaurus.

Lorsque vous servez le site à partir de votre propre serveur Web, assurez-vous que le serveur Web sert les fichiers d’asset avec les en-têtes HTTP appropriés. Les fichiers CSS doivent être servis avec l’en-tête de type contenu de text/css. Dans le cas de Nginx, cela signifierait inclure /etc/nginx/mime.types ; dans votre fichier nginx.conf. Voir ici pour plus d’informations.

Suite documentation Docusaurus en anglais…

virtuel
Cet article est sous licence CC BY 4.0 par l'auteur.