Commit initial
This commit is contained in:
257
README.md
Normal file
257
README.md
Normal file
@@ -0,0 +1,257 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user