pagemark/README.md

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

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 :

# Mon Site
Le blog d'un passionné de technologie

md/footer.md — pied de page en 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 ↗ :

- [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 :

::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

python3 build.py

4. Tester en local

python3 -m http.server 3000

Puis ouvrez 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 :

- [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 :

![Description de l'image](/images/photo.jpg)

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 :

<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 :

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 :

#!/bin/bash
python3 build.py && rsync -avz --delete . user@serveur:/var/www/pagemark \
  --exclude='md/' --exclude='static/' --exclude='*.py' --exclude='*.md' --exclude='.git'

---

Licence

GPLv3