Code source.

https://github.com/HackTechDev/github2gravarticle

github_to_article.py

Crée un article Grav à partir d'un dépôt GitHub : le README du dépôt devient le corps de l'article, et une entrée est ajoutée dans user/pages/01.carnet/blog.md.

Prérequis

Python 3.8 ou plus récent (bibliothèque standard uniquement, rien à installer)
Un accès à api.github.com (dépôts publics ; jeton facultatif, voir Remarques)

Installation

Cloner le dépôt puis créer un lien vers le script dans le dossier scripts/ du site Grav :

git clone https://github.com/HackTechDev/github2gravarticle.git
ln -s "$PWD/github2gravarticle/github_to_article.py" /chemin/du/site/scripts/github_to_article.py

Le script trouve seul la racine du site (le dossier qui contient user/pages) : un lien symbolique suffit, et un git pull dans le clone le met à jour.

Utilisation

Depuis la racine du site Grav (ou un de ses sous-dossiers) :

python3 scripts/github_to_article.py URL_DEPOT REPERTOIRE_SECTION [options]

Paramètre	Description
`URL_DEPOT`	URL du dépôt GitHub (`https://github.com/<compte>/<depot>`, avec ou sans `.git`, ou une de ses pages comme `…/tree/main`)
`REPERTOIRE_SECTION`	Répertoire de destination de l'article, sous `user/pages` (ex. `user/pages/07.appli`)

Options

Option	Défaut	Description
`--title TITRE`	premier titre `#` du README	Titre de l'article
`--slug SLUG`	titre sans accents ni ponctuation	Nom du dossier de l'article, sans le numéro
`--tags A B C`	topics GitHub du dépôt, sinon `Github`	Tags de l'article
`--date JJ-MM-AAAA`	aujourd'hui	Date de l'article et de l'entrée dans `blog.md`
`--no-blog`		Ne pas modifier `blog.md`
`--dry-run`		Afficher l'article et l'entrée `blog.md` sans rien écrire

Le titre par défaut est souvent le nom technique du projet (ex. downloadSubtitleTranslation) : il vaut mieux préciser --title.

Exemples

# Aperçu, sans rien écrire
python3 scripts/github_to_article.py https://github.com/HackTechDev/MonDepot user/pages/07.appli --dry-run

# Création avec un titre et des tags
python3 scripts/github_to_article.py https://github.com/HackTechDev/MonDepot user/pages/07.appli \
    --title "Mon titre" --tags Python Linux

# Article daté, sans l'ajouter à blog.md
python3 scripts/github_to_article.py https://github.com/HackTechDev/MonDepot user/pages/04.jeu-libre \
    --date 01-10-2026 --no-blog

Ce que fait le script

Récupération : lit les informations du dépôt (branche par défaut, topics) et son README via l'API GitHub.
Dossier de l'article : crée <numéro suivant>.<slug>/item.md dans la section. Par exemple, si le dernier article de 07.appli est 27.…, le nouveau sera 28.<slug>.
En-tête : même forme que les autres articles de la section (title, date, publish_date, taxonomy.tag, metadata…).
Image : la première image du README stockée dans le dépôt (Markdown ![…](…) ou <img src="…">, en png, jpg, gif ou webp) est copiée dans le dossier de l'article. Elle sert de hero_image et de og:image. Si le README n'en a pas, ces deux lignes sont omises.
Corps : section # Code source. avec le lien vers le dépôt, puis le README.
Liens : les liens relatifs du README (MANUEL.md, docs/x.md…) sont remplacés par leur adresse sur GitHub, et les images par leur adresse brute (raw.githubusercontent.com), y compris les images cliquables ([![…](…)](…)) les balises HTML <img src> / <a href> et les définitions de liens par référence ([ref]: chemin). Si le README est dans un sous-dossier (docs/README.md), les chemins partent de ce dossier. Les liens absolus, les ancres (#…), les blocs de code et le code inline (`…`) ne sont pas modifiés.
blog.md : ajoute * JJ/MM/AA : [Titre](/section/slug) à sa place chronologique (avant les entrées du même jour ou plus anciennes, donc en tête du mois pour un article du jour), en créant le titre du mois (#### Octobre) ou de l'année (### Année 2027) si besoin. La route retire les numéros des dossiers : user/pages/07.appli donne /appli.

Sécurités

Le script s'arrête sans rien écrire si :

le dépôt a déjà un article dans la section (son URL apparaît dans un item.md, sans tenir compte de la casse) ;
un article avec le même slug existe déjà dans la section ;
le répertoire n'existe pas ou n'est pas sous user/pages ;
le dépôt est introuvable ou GitHub ne répond pas ;
blog.md est illisible (sauf avec --no-blog).

Si une écriture échoue en cours de route, le dossier de l'article est supprimé. blog.md est écrit dans un fichier temporaire puis renommé, il n'est jamais laissé à moitié écrit.

Après la création

Le script ne fait ni commit ni mise en ligne. Ensuite :

git add user/pages
git commit -m "[Add] Mon titre"
./pushGit.sh
./syncUser.sh

Remarques

IPv4 en priorité : sur certaines machines, l'IPv6 vers GitHub reste bloquée jusqu'au timeout. Le script essaie donc l'IPv4 en premier.
Limite de l'API : sans authentification, GitHub autorise 60 requêtes par heure ; le script en fait deux par article (le README et l'image sont téléchargés depuis raw.githubusercontent.com, hors limite). Pour monter à 5000 requêtes par heure, définir un jeton : export GITHUB_TOKEN=…. Il n'est envoyé qu'à api.github.com.
Adresse du dépôt : l'article reprend l'adresse officielle donnée par GitHub (casse exacte, nouveau nom si le dépôt a été renommé).
Images : seule la première image est copiée dans le dossier de l'article ; les images affichées dans le corps restent hébergées sur GitHub.