dernière version préliminaire
This commit is contained in:
4
.vscode/extensions.json
vendored
4
.vscode/extensions.json
vendored
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"recommendations": ["astro-build.astro-vscode"],
|
||||
"unwantedRecommendations": []
|
||||
}
|
||||
11
.vscode/launch.json
vendored
11
.vscode/launch.json
vendored
@@ -1,11 +0,0 @@
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"command": "./node_modules/.bin/astro dev",
|
||||
"name": "Development server",
|
||||
"request": "launch",
|
||||
"type": "node-terminal"
|
||||
}
|
||||
]
|
||||
}
|
||||
6
src/pages/posts/.obsidian/workspace.json
vendored
6
src/pages/posts/.obsidian/workspace.json
vendored
@@ -185,13 +185,13 @@
|
||||
},
|
||||
"active": "c9a5ae1d384a28a9",
|
||||
"lastOpenFiles": [
|
||||
"post-10.md",
|
||||
"post-6.md",
|
||||
"post-4.md",
|
||||
"post-5.md",
|
||||
"post-10.md",
|
||||
"post-9.md",
|
||||
"post-8.md",
|
||||
"post-7.md",
|
||||
"post-6.md",
|
||||
"post-5.md",
|
||||
"Configurer environnement de développement.md",
|
||||
"post-3.md",
|
||||
"post-2.md",
|
||||
|
||||
@@ -1,66 +1,57 @@
|
||||
---
|
||||
title: Première note réel
|
||||
pubDate: 2026-01-30
|
||||
description: Tutoriel Step By Step Obsidian
|
||||
author: Latchimy Nicolas
|
||||
image:
|
||||
tags:
|
||||
- astro
|
||||
- blogging
|
||||
- apprentissage-en-public
|
||||
title: "Log de Bord : Construction du Jardin Numérique v1"
|
||||
description: "Ce document est le journal de bord de la construction de mon site Astro. Il est basé sur le tutoriel officiel et adapté pour le projet 'HebelOS'."
|
||||
pubDate: "2026-01-30"
|
||||
version: "1.0.0"
|
||||
author: "Latchimy Nicolas"
|
||||
tags: ["astro", "log-de-bord", "tutoriel", "hebelos"]
|
||||
---
|
||||
# Première note réel
|
||||
|
||||
Publié le : 2026-01-30
|
||||
# Log de Bord : Tutoriel Astro
|
||||
|
||||
> [!NOTE] Information
|
||||
> Ce qui suit est la reprise complète du tutoriel chapitre par chapitre.
|
||||
Ce document est ma version personnalisée du tutoriel officiel d'Astro. Il sert de base à la construction de mon jardin numérique et de "Log" pour toutes les modifications à venir.
|
||||
|
||||
[^1]
|
||||
# astro DOCS
|
||||
> [!NOTE] Objectif
|
||||
> Utiliser ce guide comme référence principale pour chaque étape de développement, de la création des pages à l'ajout de l'interactivité.
|
||||
|
||||
## Bienvenue à bord
|
||||
---
|
||||
|
||||
### Créer votre premier blog avec Astro
|
||||
## Unité 0 : Bienvenue à Bord
|
||||
|
||||
Il est question de voir les fonctionnalités clés d'astro avec un petit (menu ou index[^2]) :
|
||||
**Objectif :** Comprendre la structure du tutoriel et les prérequis.
|
||||
|
||||
- [[post-5|Configurer environnement de développement]]
|
||||
- [[post-6|Créer des pages articles de blog]]
|
||||
- [[post-7|Construire avec les composants]]
|
||||
- [[post-8|Interroger et travailler avec des fichiers locaux]]
|
||||
- [[post-9|Ajouter de l’interactivité au site]]
|
||||
- [[post-10|Déployer le site sur le web]]
|
||||
### A propos des prérequis
|
||||
|
||||
[^3]
|
||||
### A propos
|
||||
Le tutoriel suppose une connaissance de base en HTML, CSS, JavaScript et Markdown. Pour toute question, la communauté est disponible sur le [Discord d'Astro](https://astro.build/chat) et les problèmes peuvent être signalés sur le [dépôt GitHub](https://github.com/withastro/docs/issues).
|
||||
|
||||
Demande quelques connaissance en HTML, Markdown, CSS et Javascript pour pouvoir faire toutes les étapes du tutoriel. A l'intérieur de cette section on trouve le lien pour le [discord](https://astro.build/chat) et le dépôt [github](https://github.com/withastro/docs/issues).
|
||||
---
|
||||
|
||||
## Unité 1 : Créer et déployer votre premier site Astro
|
||||
|
||||
## Créer et déployer votre premier site Astro
|
||||
**Objectif :** Mettre en place un environnement de développement fonctionnel, créer un projet Astro de base et le déployer.
|
||||
|
||||
### Embarquement : Unité 1 - Configuration
|
||||
### 1.1 Environnement de développement
|
||||
|
||||
Explication sur la section
|
||||
### Environnement de développement
|
||||
Mon environnement de travail pour ce projet :
|
||||
- **Terminal :** Ubuntu 24.04
|
||||
- **Éditeur de code :** Zed / VS Code
|
||||
- **Node.js & Paquets :** `pnpm` (plus robuste que `npm` pour ce projet).
|
||||
|
||||
- Terminal : Ubuntu 24.04
|
||||
- Editeur de code : Zed
|
||||
- Node.js
|
||||
- pnpm
|
||||
### 1.2 Créer le projet Astro
|
||||
|
||||
### Créer premier projet Astro
|
||||
|
||||
```shell
|
||||
# créer un nouveau projet avec pnpm
|
||||
pnpm create astro@latest .
|
||||
Pour initialiser le projet dans le répertoire courant en utilisant le modèle de blog :
|
||||
```bash
|
||||
# Nous utilisons pnpm pour sa robustesse
|
||||
pnpm create astro@latest . --template blog
|
||||
```
|
||||
|
||||
### Ecrire première ligne
|
||||
### 1.3 Écrire la première ligne de code
|
||||
|
||||
Le fichier `src/pages/index.astro` est le point d'entrée. Nous pouvons le modifier pour voir les changements en direct.
|
||||
|
||||
```astro
|
||||
---
|
||||
// Le frontmatter Astro (entre les '---') contient le JavaScript qui s'exécute sur le serveur.
|
||||
---
|
||||
|
||||
<html lang="fr">
|
||||
@@ -69,66 +60,315 @@ pnpm create astro@latest .
|
||||
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
|
||||
<meta name="viewport" content="width=device-width" />
|
||||
<meta name="generator" content={Astro.generator} >
|
||||
<title>Astro</title>
|
||||
<title>Mon Laboratoire</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Astro</h1>
|
||||
<h1>Mon Jardin Numérique - HebelOS</h1>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
-`<h1>Astro</h1>`
|
||||
+`<h1>Mon site Astro</h1>`
|
||||
### 1.4 Dépôt en ligne (Gitea)
|
||||
|
||||
### Dépôt en ligne
|
||||
- Créer un dépôt distant sur mon instance Gitea.
|
||||
- Lier le dépôt local au dépôt distant pour versionner le code.
|
||||
|
||||
- Créer son dépôt distant dans gitea
|
||||
- Faire le lien avec le dépot local
|
||||
### 1.5 Déploiement du site
|
||||
|
||||
### Déploiement du site sur le net
|
||||
> [!TODO] Note personnelle
|
||||
> Je dois documenter ici les étapes spécifiques de mon déploiement sur Raspberry Pi via Docker et Nginx Proxy Manager.
|
||||
|
||||
Je déploie sur raspberry pi mais il y a pas mal d'étape à décrire.[^4]
|
||||
---
|
||||
|
||||
## Ajouter, mettre en forme et lier des pages sur votre site
|
||||
## Unité 2 : Pages, Routes et Markdown
|
||||
|
||||
### Embarquement : Unité 2 - Pages
|
||||
**Objectif :** Créer de nouvelles pages, comprendre le routage basé sur les fichiers et commencer à utiliser Markdown pour le contenu.
|
||||
|
||||
Explication sur la section
|
||||
### Créer première page Astro
|
||||
### 2.1 Créer des pages Astro
|
||||
|
||||
- création about.astro même contenu que l'index
|
||||
- modification du contenu de about
|
||||
- ajout de liens de navigation sur toutes les pages
|
||||
- création blog.astro
|
||||
- publication des modification sur le web
|
||||
Astro utilise le routage basé sur les fichiers. Chaque fichier dans `src/pages/` devient une page de votre site.
|
||||
- `src/pages/index.astro` -> `mon-site.fr/`
|
||||
- `src/pages/about.astro` -> `mon-site.fr/about`
|
||||
- `src/pages/blog.astro` -> `mon-site.fr/blog`
|
||||
|
||||
### Ecrire premier article de blog en Markdown
|
||||
Il faut ajouter des liens de navigation (`<a href="/about">`) entre les pages pour les relier.
|
||||
|
||||
- création de la section posts qui accueil les .md
|
||||
- création des .md
|
||||
- rédaction de contenu markdown
|
||||
- Ajout des liens vers les articles
|
||||
### 2.2 Écrire le premier article en Markdown (.md)
|
||||
|
||||
### Ajout du contenu dynamique
|
||||
Les articles de blog sont créés dans `src/pages/posts/`. Chaque fichier `.md` devient automatiquement une page de blog.
|
||||
|
||||
- Définir et utiliser une variable dans about
|
||||
> [!TIP] Frontmatter
|
||||
> Le bloc de texte au début d'un fichier Markdown, délimité par `---`, s'appelle le **frontmatter**. C'est là que l'on stocke les métadonnées d'une page (titre, date, description) sous forme de paires clé-valeur (format YAML). Astro lit ces données pour les utiliser dans les layouts et les pages d'index.
|
||||
|
||||
### 2.3 Utiliser des variables (Contenu dynamique)
|
||||
|
||||
On peut définir des variables dans le frontmatter d'un fichier `.astro` et les utiliser dans le template HTML avec la syntaxe `{maVariable}`.
|
||||
|
||||
```astro
|
||||
---
|
||||
const pageTitle = "A propos de moi";
|
||||
const pageTitle = "À propos de moi";
|
||||
const identity = {
|
||||
firstName: "Nicolas",
|
||||
country: "France",
|
||||
hobbies: ["auto-hébergement", "BD", "RPG"],
|
||||
};
|
||||
const skills = ["HTML", "CSS", "JavaScript", "Astro", "Docker"];
|
||||
---
|
||||
<title>{pageTitle}</title>
|
||||
<h1>{pageTitle}</h1>
|
||||
|
||||
<p>Je m'appelle {identity.firstName}.</p>
|
||||
|
||||
<p>Mes compétences :</p>
|
||||
<ul>
|
||||
{skills.map((skill) => <li>{skill}</li>)}
|
||||
</ul>
|
||||
```
|
||||
|
||||
- Reproduire dans index et blog
|
||||
### 2.4 Affichage conditionnel
|
||||
|
||||
On peut utiliser des opérateurs JavaScript comme `&&` (ET logique) ou l'opérateur ternaire `? :` pour afficher des éléments sous certaines conditions.
|
||||
|
||||
```astro
|
||||
---
|
||||
const happy = true;
|
||||
const finished = true;
|
||||
---
|
||||
|
||||
{happy && <p>Je suis heureux d'apprendre Astro !</p>}
|
||||
|
||||
{finished ? <p>J'ai terminé ce tutoriel !</p> : <p>Je suis encore en train de travailler.</p>}
|
||||
```
|
||||
|
||||
### 2.5 Styles CSS
|
||||
|
||||
- **Styles locaux :** Une balise `<style>` dans un fichier `.astro` est automatiquement "scopée" (locale) : elle ne s'applique qu'aux éléments de ce fichier.
|
||||
- **Styles globaux :** Pour des styles qui s'appliquent à tout le site, on crée un fichier CSS (ex: `src/styles/global.css`) et on l'importe dans les pages ou les layouts.
|
||||
|
||||
---
|
||||
|
||||
[^1]: *Les "`mises en avant`" ne sont pas stylisé dans le rendu des "`.md`"*
|
||||
## Unité 3 : Composants Astro
|
||||
|
||||
[^2]: Penser à faire un lexique, dictionnaire, codex
|
||||
**Objectif :** Décomposer l'interface en petits morceaux réutilisables (composants) pour garder le code propre et maintenable.
|
||||
|
||||
[^3]: Les liens internes Obsidian n'apparaissent pas comme des liens, risque d'être problématique pour ma documentation.
|
||||
> [!NOTE] Convention de nommage
|
||||
> Les fichiers de composants commencent par une majuscule (ex: `MonComposant.astro`). C'est une convention pour les distinguer des pages, qui sont en minuscules.
|
||||
|
||||
[^4]: Faire le résumé du déploiement sur RaspberryPi
|
||||
### 3.1 Créer des composants réutilisables
|
||||
|
||||
On crée des fichiers `.astro` dans `src/components/`. Ces fichiers peuvent ensuite être importés et utilisés dans n'importe quelle page.
|
||||
|
||||
**Exemple : `src/components/Navigation.astro`**
|
||||
```astro
|
||||
---
|
||||
---
|
||||
<div class="nav-links">
|
||||
<a href="/">Accueil</a>
|
||||
<a href="/about/">À propos</a>
|
||||
<a href="/blog/">Blog</a>
|
||||
</div>
|
||||
```
|
||||
|
||||
### 3.2 Passer des données avec `Astro.props`
|
||||
|
||||
Les composants peuvent recevoir des données (appelées "props") depuis la page qui les utilise.
|
||||
|
||||
**Exemple : `src/components/Social.astro`**
|
||||
```astro
|
||||
---
|
||||
// On récupère les props passées au composant
|
||||
const { platform, username } = Astro.props;
|
||||
---
|
||||
<a href={`https://www.${platform}.com/${username}`}>{platform}</a>
|
||||
```
|
||||
**Utilisation dans `Footer.astro`**
|
||||
```astro
|
||||
---
|
||||
import Social from './Social.astro';
|
||||
---
|
||||
<footer>
|
||||
<Social platform="gitea" username="mon-pseudo" />
|
||||
<Social platform="linkedin" username="mon-profil" />
|
||||
</footer>
|
||||
```
|
||||
|
||||
### 3.3 Ajouter un script côté client
|
||||
|
||||
> [!NOTE] Difficulté personnelle
|
||||
> La création du menu hamburger interactif ("DIY") était une étape complexe. Le fait de la décomposer ici m'aide à la maîtriser.
|
||||
|
||||
Pour ajouter de l'interactivité, on crée un fichier JavaScript (ex: `src/scripts/menu.js`) et on l'importe dans une balise `<script>` à l'intérieur d'un composant ou d'une page.
|
||||
|
||||
**`src/scripts/menu.js`**
|
||||
```javascript
|
||||
document.querySelector('.hamburger').addEventListener('click', () => {
|
||||
document.querySelector('.nav-links').classList.toggle('expanded');
|
||||
});
|
||||
```
|
||||
**Dans `Header.astro`**
|
||||
```astro
|
||||
---
|
||||
import Navigation from './Navigation.astro';
|
||||
---
|
||||
<header>
|
||||
<button class="hamburger">Menu</button>
|
||||
<Navigation />
|
||||
</header>
|
||||
<script>
|
||||
import '../scripts/menu.js';
|
||||
</script>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Unité 4 : Layouts (Mises en page)
|
||||
|
||||
**Objectif :** Créer des modèles de page (`layouts`) pour partager une structure commune (header, footer, etc.) entre plusieurs pages.
|
||||
|
||||
### 4.1 Créer un layout de base
|
||||
|
||||
Un layout est un composant Astro spécial qui accepte du contenu via une balise `<slot />`.
|
||||
|
||||
**`src/layouts/BaseLayout.astro`**
|
||||
```astro
|
||||
---
|
||||
import Header from '../components/Header.astro';
|
||||
import Footer from '../components/Footer.astro';
|
||||
import '../styles/global.css';
|
||||
const { pageTitle } = Astro.props;
|
||||
---
|
||||
<html lang="fr">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>{pageTitle}</title>
|
||||
</head>
|
||||
<body>
|
||||
<Header />
|
||||
<h1>{pageTitle}</h1>
|
||||
|
||||
<!-- Le contenu de la page sera injecté ici -->
|
||||
<slot />
|
||||
|
||||
<Footer />
|
||||
<script>
|
||||
import "../scripts/menu.js";
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
### 4.2 Utiliser un layout dans une page
|
||||
|
||||
On importe le layout et on enveloppe le contenu de la page avec.
|
||||
|
||||
**`src/pages/index.astro`**
|
||||
```astro
|
||||
---
|
||||
import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
const pageTitle = "Page d'accueil";
|
||||
---
|
||||
<BaseLayout pageTitle={pageTitle}>
|
||||
<p>Ceci est le contenu de ma page d'accueil. Il sera placé dans le <slot />.</p>
|
||||
</BaseLayout>
|
||||
```
|
||||
|
||||
### 4.3 Combiner les layouts
|
||||
|
||||
On peut imbriquer les layouts. Par exemple, un `MarkdownPostLayout.astro` peut utiliser le `BaseLayout.astro` pour avoir une structure de base tout en ajoutant des éléments spécifiques aux articles de blog.
|
||||
|
||||
---
|
||||
|
||||
## Unité 5 : Collections de Contenu
|
||||
|
||||
**Objectif :** Utiliser l'API de contenu d'Astro pour organiser et valider les fichiers Markdown, et générer dynamiquement des pages.
|
||||
|
||||
### 5.1 Configurer les Collections
|
||||
|
||||
Dans `src/content/config.ts`, on définit un "schéma" pour chaque type de contenu. C'est un contrat qui garantit que tous vos fichiers Markdown ont les bonnes propriétés dans leur frontmatter.
|
||||
|
||||
```typescript
|
||||
// src/content/config.ts
|
||||
import { defineCollection, z } from 'astro:content';
|
||||
|
||||
const blogCollection = defineCollection({
|
||||
type: 'content',
|
||||
schema: z.object({
|
||||
title: z.string(),
|
||||
pubDate: z.date(),
|
||||
description: z.string(),
|
||||
author: z.string(),
|
||||
tags: z.array(z.string()),
|
||||
}),
|
||||
});
|
||||
|
||||
export const collections = {
|
||||
'blog': blogCollection,
|
||||
};
|
||||
```
|
||||
Vos articles de blog doivent maintenant se trouver dans `src/content/blog/`.
|
||||
|
||||
### 5.2 Lister les articles (`Astro.glob` ou `getCollection`)
|
||||
|
||||
Pour récupérer tous les articles d'une collection et les afficher sur une page (ex: `blog.astro`).
|
||||
|
||||
```astro
|
||||
---
|
||||
// src/pages/blog.astro
|
||||
import { getCollection } from 'astro:content';
|
||||
import BaseLayout from '../layouts/BaseLayout.astro';
|
||||
|
||||
const allPosts = await getCollection('blog');
|
||||
---
|
||||
<BaseLayout pageTitle="Mon Blog">
|
||||
<ul>
|
||||
{allPosts.map(post => (
|
||||
<li><a href={`/blog/${post.slug}/`}>{post.data.title}</a></li>
|
||||
))}
|
||||
</ul>
|
||||
</BaseLayout>
|
||||
```
|
||||
|
||||
### 5.3 Générer des pages dynamiquement
|
||||
|
||||
On peut créer des pages pour chaque article et chaque tag automatiquement.
|
||||
|
||||
- **Pages d'articles :** `src/pages/blog/[...slug].astro`
|
||||
- **Pages de tags :** `src/pages/tags/[tag].astro`
|
||||
|
||||
Ces fichiers utilisent une fonction `getStaticPaths()` pour dire à Astro quelles pages construire au moment du build.
|
||||
|
||||
### 5.4 Ajouter un flux RSS
|
||||
|
||||
Astro facilite la création d'un flux RSS pour que les lecteurs puissent s'abonner à votre blog.
|
||||
1. `pnpm add @astrojs/rss`
|
||||
2. Créer un fichier `src/pages/rss.xml.js` pour configurer le flux.
|
||||
|
||||
---
|
||||
|
||||
## Unité 6 : Îlots d'interactivité (Astro Islands)
|
||||
|
||||
**Objectif :** Comprendre comment ajouter des composants interactifs (frameworks UI ou JS vanilla) à des pages autrement statiques.
|
||||
|
||||
### 6.1 Construire son premier îlot
|
||||
|
||||
1. **Ajouter une intégration :** `pnpm astro add react` (ou `preact`, `svelte`, etc.).
|
||||
2. **Créer un composant de framework :** par exemple, `src/components/Counter.jsx`.
|
||||
3. **L'utiliser dans Astro avec une directive `client:*` :** C'est cette directive qui transforme un composant en "îlot".
|
||||
|
||||
```astro
|
||||
---
|
||||
import Counter from '../components/Counter.jsx';
|
||||
---
|
||||
<BaseLayout pageTitle="Test d'îlot">
|
||||
<p>Ce compteur est interactif, alors que le reste de la page est statique.</p>
|
||||
<Counter client:load />
|
||||
</BaseLayout>
|
||||
```
|
||||
- `client:load` : charge le JavaScript de l'îlot dès que la page se charge.
|
||||
- `client:idle` : attend que la page soit chargée pour charger le JS.
|
||||
- `client:visible` : attend que l'îlot soit visible à l'écran.
|
||||
|
||||
### 6.2 L'îlot en JavaScript "Vanilla" (Theme Toggle)
|
||||
|
||||
Un îlot n'a pas besoin d'un framework. Une simple balise `<script>` dans un fichier `.astro` est aussi un îlot. L'exemple du bouton pour changer de thème (clair/sombre) est parfait pour illustrer cela.
|
||||
|
||||
Félicitations, le log de bord de la V1 est complet !
|
||||
Reference in New Issue
Block a user