184 lines
3.9 KiB
Markdown
184 lines
3.9 KiB
Markdown
# 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 (<NUMERO> = numéro du ticket non pas id-paragraphe)
|
||
|
||
En bash :
|
||
|
||
# dry-run (recommandé)
|
||
node scripts/apply-ticket.mjs <NUMERO> --dry-run
|
||
|
||
# appliquer
|
||
node scripts/apply-ticket.mjs <NUMERO>
|
||
git diff
|
||
git add <fichier>
|
||
git commit -m "edit: apply ticket #<NUMERO> (...)"
|
||
|
||
## 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 |