Docusaurus - Installation
1. Description
Docusaurus est un framework NodeJS pour générer un site web statique à partir de fichiers Markdown.
Cette page décrit les étapes pour :
- installer le logiciel
docusaurus - créer un projet docusaurus : homelabasdoc (ce site web)
- configurer le projet via le fichier
docusaurus.config.ts - ajouter des menus via le fichier
sidebars.ts - créer un pipeline CI/CD Gitlab pour automatiquement générer et transférer les pages HTML sur une Page Gitlab, ainsi qu'un site Netlify
2. Documentations
3. Installation des prérequis
- Installer
NodeJS: il faut au minimum une version 18.
$ sudo dnf module list nodejs
$ sudo dnf module reset nodejs
$ sudo dnf module enable nodejs:18
$ sudo dnf module install nodejs:18/common
$ node --version
v18.20.6
4. Création du projet docusaurus
4.1. Créer le projet 'homelabasdoc'
$ npx create-docusaurus@latest homelabasdoc classic --typescript
5. Création du site 'homelabasdoc'
5.1. Créer un projet Docusaurus
$ npx create-docusaurus@latest homelabasdoc classic --typescript
[INFO] Creating new Docusaurus project...
[INFO] Installing dependencies with npm...
5.2. Générer le projet Docusaurus
$ yarn build
5.3. Démarrer en local un site Web de test
$ yarn run start
yarn run v1.22.22
docusaurus start
[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:3000/homelabasdoc/
√ Client
Compiled successfully in 2.29s
5.4. Tester le site web en local
- Ouvrir l'URL : http://localhost:3000/homelabasdoc/
6. Arborescence et catégories du site web
6.1. Créer l'arborescence du site web
- Voici la structure de mon site web : j'ai numéroté les répertoires afin de pouvoir les organiser dans les menus gérés automatiquement (le tri est fait par ordre alphabétique).
6.2. Personnaliser le nom des entrées des menus
info
Par défaut, le nom de l'entrée dans le menu est généré automatiquement à partir du nom du dossier et est "normalisé" (ie. convertit en minuscule notamment).
Afin de pouvoir renommer les entrées dans le menu, il faut créer dans le répertoire un fichier _category_.json.
- Par exemple, pour renommer l'entrée correspondant au dossier "01-bootstrap" en "Bootstrap Homelab", il faut créer le fichier suivant dans le dossier "01-bootstrap"
01-bootstrap/_config_.json
{
"label": "Bootstrap Homelab",
"position": 1,
"link": {
"type": "generated-index"
}
}
6.3. Configurer le projet docusaurus
- Modifier le fichier
docusaurus.config.ts
FIchier docusaurus.config.ts
docusaurus.config.ts
import {themes as prismThemes} from 'prism-react-renderer';
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
const config: Config = {
title: 'HomeLab As Doc',
tagline: 'Bienvenue dans mon homelab. Docs are cool !!',
favicon: 'img/favicon.ico',
// Set the production url of your site here
url: 'https://tzshare.gitlab.io',
baseUrl: '/homelabasdoc/',
// Build warnings
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
// Internationalization
i18n: {
defaultLocale: 'fr',
locales: ['fr'],
},
presets: [
[
'classic',
{
docs: {
breadcrumbs: true,
routeBasePath: '/',
sidebarPath: './sidebars.ts',
showLastUpdateTime: true,
showLastUpdateAuthor: false,
},
theme: {
customCss: './src/css/custom.css',
},
} satisfies Preset.Options,
],
],
themeConfig: {
image: 'img/hlad-logo.png',
navbar: {
title: 'HomeLabAsDoc',
logo: {
alt: 'Logo HomeLabAsDoc',
src: 'img/hlad-logo.png',
},
items: [
{
type: 'docSidebar',
sidebarId: 'bootstrapSidebar',
position: 'left',
label: 'Bootstrap',
},
{
type: 'docSidebar',
sidebarId: 'outilsSidebar',
position: 'left',
label: 'Outils',
},
{
type: 'docSidebar',
sidebarId: 'infraSidebar',
position: 'left',
label: 'Infra',
},
{
type: 'docSidebar',
sidebarId: 'devsecopsSidebar',
position: 'left',
label: 'DevSecOps',
},
{
href: '/tags',
label: '#Tags',
position: 'right',
},
{
href: '/about',
label: 'A propos',
position: 'right',
},
],
},
// Override footer
footer: {
style: 'dark',
copyright: `Copyright © ${new Date().getFullYear()} ThusZero - HomeLabAsDoc. Built with Docusaurus.`,
},
// Syntax highlighting
prism: {
theme: prismThemes.github,
darkTheme: prismThemes.dracula,
additionalLanguages: ['bash', 'shell-session', 'yaml'],
},
} satisfies Preset.ThemeConfig,
};
export default config;
- Modifier le fichier
sidebars.ts(à adapter suivant la structure du site web)
sidebars.ts
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
bootstrapSidebar: [{type: 'autogenerated', dirName: '01-bootstrap'}],
outilsSidebar: [{type: 'autogenerated', dirName: '02-outils'}],
infraSidebar: [{type: 'autogenerated', dirName: '03-infra'}],
devsecopsSidebar: [{type: 'autogenerated', dirName: '04-devsecops'}],
};
export default sidebars;