258 lines
6.7 KiB
Markdown
258 lines
6.7 KiB
Markdown
# PageMark
|
||
|
||
Générateur de site statique minimaliste alimenté par des fichiers Markdown.
|
||
|
||
Écrivez du contenu en `.md`, lancez `python3 build.py`, déployez les fichiers HTML générés.
|
||
|
||
## Fonctionnalités
|
||
|
||
- Pages et articles en Markdown avec coloration syntaxique
|
||
- Page d'accueil générée automatiquement (5 derniers articles, du plus récent au plus ancien)
|
||
- Catégorisation automatique des articles avec arborescence de dossiers
|
||
- Métadonnées par article : titre, date, auteur, catégorie, image de couverture
|
||
- Dark mode : automatique selon l'heure (light 08h30–17h30) + toggle manuel mémorisé
|
||
- Ancres cliquables sur les titres `h1`–`h4`
|
||
- HTML personnalisé dans les articles
|
||
- Menu avec filtrage automatique des liens invalides et distinction liens internes/externes
|
||
- Aucune dépendance JavaScript côté client
|
||
|
||
## Prérequis
|
||
|
||
- Python 3.x
|
||
- `pip install markdown`
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
git clone https://github.com/votre-repo/pagemark
|
||
cd pagemark
|
||
pip install markdown
|
||
```
|
||
|
||
## Structure du projet
|
||
|
||
```
|
||
pagemark/
|
||
├── build.py # Générateur de site (lancer pour builder)
|
||
├── README.md
|
||
├── static/
|
||
│ ├── style.css # Styles (light + dark mode)
|
||
│ └── theme.js # Gestion du dark mode (localStorage + heure)
|
||
└── md/
|
||
├── header.md # Nom du site (# Titre) + tagline (texte suivant)
|
||
├── footer.md # Pied de page
|
||
├── menu.md # Navigation (liste Markdown)
|
||
├── categories.md # Mapping catégories → dossiers de sortie
|
||
├── images/ # Images référençables via /images/fichier.jpg
|
||
└── pages/
|
||
├── index.md # Contenu optionnel affiché au-dessus des articles
|
||
└── *.md # Vos pages et articles
|
||
```
|
||
|
||
Les fichiers HTML sont générés à la racine du projet.
|
||
|
||
## Mise en route rapide
|
||
|
||
### 1. Configurer le site
|
||
|
||
**`md/header.md`** — la première ligne `# Titre` devient le logo dans la nav, le reste la tagline :
|
||
|
||
```markdown
|
||
# Mon Site
|
||
Le blog d'un passionné de technologie
|
||
```
|
||
|
||
**`md/footer.md`** — pied de page en Markdown :
|
||
|
||
```markdown
|
||
© 2026 Votre Nom
|
||
```
|
||
|
||
**`md/menu.md`** — liste de liens. Les liens internes sont filtrés automatiquement (masqués si la page n'existe pas), les liens externes s'ouvrent dans un nouvel onglet avec le suffixe `↗` :
|
||
|
||
```markdown
|
||
- [Accueil](/)
|
||
- [À propos](/racine/a-propos/)
|
||
- [GitHub](https://github.com/vous)
|
||
```
|
||
|
||
> Le chemin d'un lien interne doit correspondre au chemin de sortie généré (voir section Catégories).
|
||
|
||
### 2. Créer une page ou un article
|
||
|
||
Créez un fichier `.md` dans `md/pages/`. Les métadonnées se placent en tête de fichier :
|
||
|
||
```markdown
|
||
::Titre:Mon premier article
|
||
::Date:07/03/2026
|
||
::Auteur:Votre Nom
|
||
::Categories:Blog
|
||
::Image:/images/cover.jpg
|
||
|
||
Contenu de l'article en Markdown...
|
||
```
|
||
|
||
> Une page sans `::Date:` est une page statique (elle n'apparaît pas dans le listing de la page d'accueil).
|
||
|
||
### 3. Générer le site
|
||
|
||
```bash
|
||
python3 build.py
|
||
```
|
||
|
||
### 4. Tester en local
|
||
|
||
```bash
|
||
python3 -m http.server 3000
|
||
```
|
||
|
||
Puis ouvrez [http://localhost:3000](http://localhost:3000).
|
||
|
||
---
|
||
|
||
## Métadonnées
|
||
|
||
| Métadonnée | Syntaxe | Rôle |
|
||
|---|---|---|
|
||
| `::Titre:` | `::Titre:Mon titre` | Affiché en `<h1>` avant le contenu |
|
||
| `::Date:` | `::Date:dd/mm/YYYY` | Date de publication, utilisée pour le tri |
|
||
| `::Auteur:` | `::Auteur:Pseudo` | Nom de l'auteur |
|
||
| `::Categories:` | `::Categories:Blog-Tutos` | Catégorie et sous-catégorie |
|
||
| `::Image:` | `::Image:/images/cover.jpg` | Image de couverture dans les cards |
|
||
|
||
Toutes les métadonnées sont optionnelles. Seules les pages avec `::Date:` sont traitées comme des **articles** et apparaissent dans le listing de la page d'accueil.
|
||
|
||
---
|
||
|
||
## Catégories
|
||
|
||
Le fichier `md/categories.md` mappe les noms de catégories vers des dossiers de sortie :
|
||
|
||
```
|
||
- Blog:/blog
|
||
- News:/news
|
||
- Tutoriels:/tutos
|
||
```
|
||
|
||
**Exemple :** `::Categories:News-Tech`
|
||
|
||
1. `News` est résolu via `categories.md` → dossier `news`
|
||
2. `Tech` (sous-catégorie) → sous-dossier `tech`
|
||
3. Fichier `mon-article.md` → généré dans `news/tech/mon-article/index.html`
|
||
4. URL : `/news/tech/mon-article/`
|
||
|
||
Si une catégorie n'est pas dans `categories.md`, son nom en minuscules est utilisé comme dossier.
|
||
|
||
---
|
||
|
||
## Navigation
|
||
|
||
**`md/menu.md`** contient une liste Markdown de liens :
|
||
|
||
```markdown
|
||
- [Accueil](/)
|
||
- [Blog](/blog/)
|
||
- [GitHub](https://github.com/vous)
|
||
```
|
||
|
||
| Type de lien | Comportement |
|
||
|---|---|
|
||
| Chemin relatif (`/page/`) | Lien **interne** — affiché uniquement si la page a été générée |
|
||
| URL complète (`https://`) | Lien **externe** — toujours affiché, suffixe `↗`, `target="_blank"` |
|
||
|
||
---
|
||
|
||
## Images
|
||
|
||
Placez vos images dans `md/images/` et référencez-les dans le Markdown :
|
||
|
||
```markdown
|
||
|
||
```
|
||
|
||
Pour l'image de couverture d'un article (affichée dans les cards de la page d'accueil) :
|
||
|
||
```
|
||
::Image:/images/cover.jpg
|
||
```
|
||
|
||
---
|
||
|
||
## HTML personnalisé
|
||
|
||
Du HTML peut être inséré directement dans n'importe quel fichier `.md` :
|
||
|
||
```html
|
||
<div style="background: var(--accent-soft); padding: 1rem; border-radius: 8px;">
|
||
Bloc personnalisé — les variables CSS du thème sont disponibles.
|
||
</div>
|
||
```
|
||
|
||
Les variables CSS `var(--bg)`, `var(--text)`, `var(--accent)`, etc. s'adaptent automatiquement au dark mode.
|
||
|
||
---
|
||
|
||
## Dark mode
|
||
|
||
| Comportement | Détail |
|
||
|---|---|
|
||
| **Par défaut** | Light de 08h30 à 17h30, dark le reste du temps |
|
||
| **Manuel** | Bouton `☾` / `☀` dans la barre de navigation |
|
||
| **Mémorisation** | Le choix est sauvegardé via `localStorage` — il prend le dessus sur le comportement automatique |
|
||
|
||
---
|
||
|
||
## Ancres de titres
|
||
|
||
Les titres `h1` à `h4` reçoivent automatiquement un `id` et un lien `#` cliquable au survol. Cela permet de créer des liens directs vers une section :
|
||
|
||
```
|
||
https://monsite.com/mon-article#sous-titre
|
||
```
|
||
|
||
L'`id` est généré à partir du texte du titre (minuscules, tirets à la place des espaces).
|
||
|
||
---
|
||
|
||
## Déploiement avec nginx
|
||
|
||
Copiez les fichiers générés vers votre serveur. Configuration nginx minimale :
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name monsite.com;
|
||
root /var/www/pagemark;
|
||
|
||
location / {
|
||
try_files $uri $uri/index.html =404;
|
||
}
|
||
}
|
||
```
|
||
|
||
La directive `try_files $uri $uri/index.html` permet de résoudre `/mon-article/` → `/mon-article/index.html` sans redirection.
|
||
|
||
---
|
||
|
||
## Workflow recommandé
|
||
|
||
```
|
||
1. Éditer md/pages/mon-article.md
|
||
2. python3 build.py
|
||
3. Copier les fichiers générés sur le serveur
|
||
```
|
||
|
||
Pour automatiser le déploiement, un simple script shell suffit :
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
python3 build.py && rsync -avz --delete . user@serveur:/var/www/pagemark \
|
||
--exclude='md/' --exclude='static/' --exclude='*.py' --exclude='*.md' --exclude='.git'
|
||
```
|
||
|
||
---
|
||
|
||
## Licence
|
||
|
||
MIT
|