archicratie-edition/docs/QUICKSTART.md

Quickstart — 10 minutes (Proposer → Ticket → Apply → Tests)

1) Pré-requis

• Node.js + npm
• Accès Gitea (compte) + PAT si usage API (apply-ticket)

2) Lancer le site

en bash : npm install npm run dev

Dans le navigateur, url : http://localhost:4321

3) Proposer une correction

Ouvre une page (ex: Prologue).

Sur un paragraphe : clique Proposer.

Choisis :

Type : Correction / Fact-check

Category (optionnel)

Un nouvel onglet Gitea s’ouvre sur une issue pré-remplie.

Rédige :

Proposition (remplacer par):

Justification:

4) Appliquer le ticket en local ( = numéro du ticket non pas id-paragraphe)

En bash :

dry-run (recommandé)

node scripts/apply-ticket.mjs --dry-run

appliquer

node scripts/apply-ticket.mjs git diff git add git commit -m "edit: apply ticket # (...)"

5) Vérifier avant push

npm test

6) Règle d’or

Ne jamais éditer dist/ à la main.

Toujours garder Chemin + Ancre + Proposition dans le ticket.

Déplacer/ajouter les deux docs que je t’ai donnés

• docs/MANUEL_REFERENCE.md
• docs/CONTRAT_TICKETS.md

(Tu peux reprendre mes versions telles quelles.)

---

Commandes terminal P0 (copier-coller)

En bash mkdir -p docs

crée/édite les fichiers avec ton éditeur habituel

README.md

docs/QUICKSTART.md

docs/MANUEL_REFERENCE.md

docs/CONTRAT_TICKETS.md

git status -sb npm test git add docs/QUICKSTART.md docs/MANUEL_REFERENCE.md docs/CONTRAT_TICKETS.md git commit -m "docs: add quickstart + reference manual + ticket contract" git push

Checklist express (60 secondes) — valider l’outil d’édition

Après npm run dev :

1. Ouvrir un chapitre (page “reading”).
2. Hover un paragraphe : les tools apparaissent à droite.
3. Cliquer Citer : une citation est copiée (ou prompt fallback).
4. Cliquer Marque-page puis vérifier le bouton Reprendre la lecture en haut.
5. Cliquer Proposer :
   • attendu : modal 2 étapes
   • puis ouverture Gitea en nouvel onglet

Si “Proposer” ne déclenche pas le modal (Firefox)

Console :

• document.querySelectorAll('a[data-propose]').length doit être > 0
• typeof document.getElementById("propose-modal")?.showModal doit retourner "function"

---

Dernière mise à jour : 2026-01-29

Ce quickstart couvre :

• dev local (Mac / Linux)
• build/test (anchors + aliases + pagefind)
• pointeur vers déploiement production DS220+

---

1) Pré-requis

• Node : >=22 <23
• npm : >=10 <11

Vérifie en bash : node -v npm -v

2) Installer / lancer en local

Dans le dossier projet : npm ci npm run dev

Puis ouvrir l’URL affichée (souvent http://localhost:4321 ).

3) Variables Gitea (fonction “Proposer”)

La fonction “Proposer” construit des liens vers Gitea à partir de :

PUBLIC_GITEA_BASE

PUBLIC_GITEA_OWNER (⚠️ casse sensible)

PUBLIC_GITEA_REPO

En local : tu peux les mettre dans .env.local (ou .env.development) : PUBLIC_GITEA_BASE=https://gitea.archicratie.trans-hands.synology.me PUBLIC_GITEA_OWNER=Archicratia PUBLIC_GITEA_REPO=archicratie-edition

4) Build “édition web” (avec Pagefind + aliases)

Important : toujours builder via npm (pour exécuter postbuild) : npm run build

Ce qui se passe :

astro build génère dist/

postbuild exécute :

scripts/inject-anchor-aliases.mjs (aliases d’ancres)

pagefind --site dist (index de recherche)

5) Tests (incassable)

npm test

Ce test enchaîne notamment :

vérif aliases d’ancres

build

audit dist (IDs dupliqués)

présence effective des aliases dans dist

check anchors (et option update)

check inline JS

6) Import éditorial (docx → mdx)

npm run import

Puis publication via build.

7) Production sur Synology DS220+

Le déploiement “propre” (Docker multi-stage + Nginx statique + DSM Reverse Proxy + blue/green) est documenté ici :

DEPLOY_PROD_SYNOLOGY_DS220.md

OPS_COCKPIT.md