Skip to contents

Vue d’ensemble

Chaque document de travail (WP) de l’OFCE vit dans son propre dépôt GitHub. Un WP produit deux sorties :

  • un mini-site HTML (site Quarto dont le docuement index.qmd est la page principale)
  • un PDF (LaTeX via wp-pdf ou Typst via wp-typst — wp-typst est le moteur ajouté par défaut par setup_wp() quand aucun des deux n’est déjà déclaré, car il gère nativement les figures SVG sans dépendance externe, fonctionne mieux que latex et surtout dont le template est maintenu ; wp-pdf reste malgré tout disponible en le déclarant explicitement)

Il peut contenir des annexes (annexes.qmd) et un historique des révisions (news.qmd), ainsi que tout autre document que l’on souhaite (code, explications de code, de données, etc…). Le document index.qmd est le document principal (il peut être le seul document). Le pdf est construit seulement à partir de index.qmd.

  1. On initialise ou corrige une installation avec setup_wp()
  2. On vérifie et diagnostique par check()
  3. On fait le rendu avec render() (on peut avoir à régler de nombreux problèmes de rendu)
  4. On publie avec publish() (envoyé en staging tant qu’il n’est pas validé, ou sur une url stable lorsqu’il est validé)
  5. On demande la validation par registry_request()

Note 1 : le bouton render de Rstudio ne produit pas le même résultat que render(). Le menu Addins de RStudio contient les items render/publish/etc…

Note 2 : tous les .qmd dans le répertoire seront rendus (et ajoutés dans la section Autres liens de \_quarto.yml). Si c’est un problème, ajoutez un \_ au début du nom u .qmd. Il sera exclu. Glisser le .qmd dans un sous-dossier dont le nom commence par _ fonctionne aussi.

Prérequis

la vignette vignette("prequisites") décrit ce qui est nécessaire pour que la procédure fonctionne. Il faut :

  1. Avoir installé git, gh sur son ordinateur
  2. Etre correctement identifié/loggé pour git et gh (github.com)
  3. Avoir généré/disposé des tokens (PAT) poriu l’identification
  4. Avoir transféré son dépôt sur le github de l’OFCE

La fonction check() réalise un diagnostic. La plupart de ces prérequis sont à faire une fois et une seule. N’hésitez pas à demander de l’aide en cas de difficulté.

Cycle de vie

État wp dans _quarto.yml Hébergement URL
Brouillon repo personnel null GitHub Pages ofce.github.io/{repo}/
Préliminaire repo sur OFCE null OFCE staging staging.ofce.fr/{repo}/{version}
Publié YYYY - N Serveur OFCE FTP www.ofce.fr/wp/{annee}/{N}/{version}/

Lorsque le docuement de travail est stagé sur le site staging.ofce.fr, il est possible de versionner. Le versionnage est impossible sur github gh-pages.

La fonction wp_version_up() incrémente la version. Il faut faire publish() ensuite.

Pour être stagé sur le site ofce.fr ou publié, la propriété du dépôt doit être transférée à l’organisation OFCE. On recommande la convention de nommage suitante : wp-{initiales de l'auteur.e}-{nom court du projet}, le TOUT EN MINUSCULE. Par exemple wp-gaxt-trec.

L’accès aux modifications du document, ainsi que la possibilité de le publier (staging ou définitif) découle des droits du dépôt. Ils sont definis dans les settings accessible sur la page github.com du dépôt. Par défaut, ce sont les auteurs et les administrateurs du site, que le dépôt soit privé ou public.


1. Initialiser un nouveau WP

Il suffit de lancer setup_wp() dans un dépôt git qui contient (ou non) le matériau pour le document de travail. Le document principal s’appelle index.qmd (c’est obligatoire). setup_wp() crée le document s’il n’existe pas, ne le change pas s’il existe. On peut donc exécuter autant de fois que nécessaire setup_wp(), en particulier lors d’un problème ou d’un rendu non satisfaisant.

Il est possible de copier coller des contenus dans les document créés.

library(ofceweb)

# Depuis la racine du dépôt GitHub du WP
setup_wp(
  path          = ".",
  lang          = "fr",
  hypothesis    = FALSE,
  versionning   = TRUE
)

setup_wp() :

  1. Vérifie la connexion GitHub (gh::gh("GET /user"))
  2. Initialise la branche orpheline gh-pages (pré-publication GitHub Pages)
  3. Copie les gabarits (_quarto.yml, index.qmd, annexes.qmd, news.qmd)
  4. Copie les assets OFCE (www/) et installe/met à jour les extensions Quarto OFCE (_extensions/) via ofce::setup_quarto() (accès réseau nécessaire)
  5. Force-remplace les workflows GitHub Actions (.github/workflows/) depuis le package — les workflows ne doivent pas être édités manuellement
  6. Adapte _quarto.yml avec le titre, l’URL, le numéro WP, l’année, la langue
  7. Consulte le registre central ofce/wp-registry (accès réseau nécessaire) : si le dépôt y a une entrée confirmée, wp/annee sont synchronisés depuis cette entrée et draft est positionné en conséquence — voir « 5. Passer de brouillon à publié » ci-dessous ; en cas d’échec réseau, ces clés sont laissées inchangées.

Après setup_wp(), _quarto.yml est déjà correct et cohérent (draft, wp, annee, site-path, citation.*) : éditez-le ainsi que index.qmd pour renseigner les métadonnées définitives (auteurs, résumé, date) et bien sûr le contenu avant de commiter.

Vous trouverez dans le package {ofce} de nombreux outils pour faciliter le travail de rédaction et de mise en page. le site de référence du package {ofce} documente les meilleurs pratiques.


2. Vérifier la structure avant rendu

check() vérifie :

  • Connexion GitHub : gh::gh("GET /user") (warning non bloquant si absent)
  • Champs obligatoires dans _quarto.yml : annee, author, date, citation
  • index.qmd présent et déclarant les formats wp-html et wp-pdf / wp-typst
  • references.bib présent (warning sinon)
  • news.qmd présent (warning sinon)
  • Si WP publié : cohérence version / site-path, annee valide
  • Tous les .qmd non-index référencés dans website.other-links
  • Unicité des output-file PDF

Elle retourne un data frame de diagnostics et est automatiquement appelée par render_wp().


3. Rendre le WP

render(
  path        = ".",
  check       = TRUE,   # appeler check_wp() avant rendu
  render_site = TRUE,   # lancer un serveur local après rendu
  site2branch = FALSE   # pousser vers la branche de déploiement
)

Pipeline :

  1. check() si check (abandon si erreurs bloquantes)
    • Vérifie la connexion GitHub (gh::gh("GET /user"))
  2. Vide _site/
  3. quarto::quarto_render(output_format = "all") — HTML + PDF
  4. Reconstruction du sitemap
  5. Patch des hashes Bootstrap CSS
  6. wp_manifest() — écriture / mise à jour de manifest.json
  7. Synchronisation de FTP_SERVER_DIR (variable GitHub Actions)
  8. Réécriture des liens absolus en relatifs si render_site
  9. Pousse vers la branche de déploiement si site2branch
  10. Lance servr::httw("_site") si render_site

4. Déployer le WP

Le comportement dépend de la valeur de wp dans _quarto.yml :

  • Brouillon (wp: null) → quarto publish gh-pages (publie sur ofce.github.io/{repo}/) ou pousse en staging sur le site de l’ofce à l’adresse staging.ofce.fr/{repo}/{version}/. Sur cette page staging, le bandeau « Version préliminaire » complète automatiquement son texte avec un compteur de déploiement (« · déploiement n°N »), tiré de github.run_number à chaque exécution de ftp_stage.yml — indépendant du numéro de version (v0, v1, …).
  • Publié (wp: N) → site2branch() vers site-deploy, puis le workflow FTP transfère vers www.ofce.fr/wp/{annee}/{N}/{version}/

5. Passer de brouillon à publié

Le numéro WP (wp) et l’année (annee) sont la propriété du registre central ofce/wp-registry, pas de l’auteur·e : dès que le dépôt y a une entrée confirmée, setup_wp() synchronise wp/annee (et draft) depuis cette entrée, en écrasant toute valeur passée en argument ou déjà présente dans _quarto.yml.

  1. Demander un numéro via registry_request(), qui calcule le numéro (auto-incrémenté, ou fourni via wp =) et ouvre une PR contre ofce/wp-registry — annee est lu depuis _quarto.yml si absent, et contact depuis git config user.email si non fourni

    :

Un·e admin OFCE doit approuver et fusionner cette PR — la fonction n’attend pas la fusion (fire-and-forget).

La PR est ouverte directement sur une branche de ofce/wp-registry (PR intra-dépôt) — pas de fork personnel. C’est volontaire : le dépôt registre est configuré pour autoriser les membres de l’organisation ofce à pousser des branches et ouvrir des PR sans être collaborateur·rice avec droit d’écriture. Seule la fusion d’une PR dans le registre est protégée (branch protection + CODEOWNERS), pas le fait d’en ouvrir une — n’importe quel·le auteur·e de l’organisation ofce doit pouvoir demander un numéro.

Prérequis : un token GitHub authentifié (DEPLOY_PAT, ou des identifiants gitcreds déjà configurés) suffisant pour résoudre son propre compte (GET /user) et pousser une branche sur ofce/wp-registry — un PAT classique avec la portée repo (ou public_repo) d’un compte membre de l’organisation ofce convient.

  1. Une fois la PR fusionnée, relancer setup_wp() pour synchroniser _quarto.yml (wp, annee, draft, site-path, citation.url/citation.issue/stable_url) et mettre à jour les variables FTP (FTP_SERVER_DIR, FTP_REDIRECT_DIR) :
  1. Rendre et déployer :

publish() (qui enchaîne render() et deploy()) refait cette consultation du registre juste avant le rendu, pour rattraper un enregistrement survenu depuis le dernier setup_wp() — mais ne recalcule que draft/wp/annee, pas site-path/citation.* : si le numéro change à cette étape, relancer setup_wp() avant de publier à nouveau.

Pour un dépôt pas encore enregistré, wp=/annee= restent les seuls arguments qui pilotent _quarto.yml — utile pour un brouillon en attente de numéro (le bandeau « Version préliminaire » reste affiché tant que le registre ne confirme rien).


6. Chiffrement (optionnel)

Le chiffrement est géré exclusivement en CI (GitHub Actions), juste avant le transfert FTP. Aucune manipulation locale n’est requise.

Si le secret STATICRYPT_PASSWORD est défini sur le dépôt, le workflow ftp_deploy.yml chiffre automatiquement tous les fichiers HTML avant l’envoi au serveur. Si le secret est absent, le déploiement s’effectue avec chiffrement en utilisant la valeur par défaut du mot de passe STATICRYPT_PASSWORD (voir les administrateurs pour cette valeur).

# Activer le chiffrement
gh secret set STATICRYPT_PASSWORD --repo owner/mon-wp

# Désactiver le chiffrement
gh secret delete STATICRYPT_PASSWORD --repo owner/mon-wp

Le rendu local (render()) produit toujours du HTML en clair.


7. Incrémenter la version après une révision

wp_version_up()           # v0 -> v1, v1 -> v2, etc.
wp_version_up(custom_version = "v1_corr")   # version personnalisée

wp_version_up() met à jour en cascade :

  1. Le champ version dans _quarto.yml
  2. Le dernier segment de website.site-path
  3. Le server-dir dans .github/workflows/ftp_deploy.yml
  4. manifest.json (via wp_manifest())

Après l’incrémentation, rendre et déployer à nouveau :

render()
deploy()

# ou publish()

8. Une note sur la taille des pdf et l’accessibilité (en pdf et html)

Il est important que les fichiers pdf produits soient conformes aux meilleures pratiques. Outre la qualité du texte et des illustrations, la structure ou la pertinence du sujet et de son argumentation, deux aspects doivent être pris en compte :

  • la taille : pour garder les pdf dans des tailles raisonnables, il faut que le format des images soit en fig-format: svg. C’est mis par défaut, sauf quand le pdf est généré par latex (format: wp-pdf) et que le convertisseur rsvg-convert n’est installé. Sur MacOS c’est facile (brew install rsvg-convert), sur win c’est un peu plus pénible (sauf si vous avez installé choco auquel cas c’est choco install rsvg-convert). Si rsvg-convert n’est pas installé, le format des images sera png et le pdf très volumineux. Alternativement, format: wp-typst fonctionne toujours et donc est plus sûr.

  • l’accessibilité : pour être conforme au RGAA et aux critères d’accessibilité pour les personnes aveugles, malvoyantes ou daltioniennes, il faut générer un document qui suit un certain nombre de règles (voir ici). Pour que les pdf générés soient conformes et vérifiés, il faut que veraPDF soit installé pour quarto (par, dans le terminal, quarto install verapdf ; si java n’est pas installé installez le ici). Une fois installé et ajouté dans le format du pdf la clef pdf-standard: ua1, un diagnostic s’affichera et vous donnera le niveau de validation. La validation échouera probablement au premier passage, toutes vos illustrations devant avoir un alt-text. Dans un .qmd, pour un chunk de code, il faut ajouter systématiquement dans les attributs du chunk #| fig-alt: "une description du graphique". Pour le moment, ces tests ne sont pas imposés, mais ils vont devenir obligatoires.

  • l’accessibilité en html : Un diagnostic d’accessibilité est produit en activant axe: true dans le format html

---
format:
  wp-typst:
    pdf-standard: ua1
---

9. Manifeste JSON

wp_manifest() (appelée automatiquement par render_wp()) génère manifest.json à la racine du dépôt et dans _site/ :

{
  "title": "Mon document de travail",
  "authors": [{"name": "Prénom Nom", "affiliation": "OFCE, Sciences Po Paris"}],
  "abstract": "Résumé...",
  "wp": 6,
  "annee": 2026,
  "version": "v0",
  "date": "2026-05-19",
  "date_modified": "2026-05-31",
  "url": "https://www.ofce.fr/wp/2026/6/v0/",
  "pdf": "OFCEWP2026-6.pdf",
  "repo": "https://github.com/ofce/mon-wp/",
  "lang": "fr"
}

Ce manifeste est collecté par webhome via la GitHub API pour construire l’index des WPs de l’OFCE.


Structure d’un dépôt WP

mon-wp/
├── _quarto.yml          # métadonnées WP (wp, annee, version, auteurs, …)
├── index.qmd            # corps du document
├── annexes.qmd          # annexes (optionnel)
├── news.qmd             # historique des révisions
├── une_presentation.qmd # un quarto revealjs 
├── references.bib       # bibliographie
├── manifest.json        # manifeste JSON (généré par render_wp)
├── R/                   # codes
├── data/                # données (générés, téléchargées)
├── .sourcoise/          # cache d'exécution (si source_data/sourcoise est utilisé)
├── renv/                # contexte des packages (si renv est utilisé)
├── _arkiv/              # un dossier ignoré par quarto (_*) 
├── www/                 # assets OFCE (logos, icônes)
├── _extensions/ofce/    # extension Quarto ofce
└── .github/workflows/
    ├── ftp_deploy.yml   # déploiement FTP (WP publié)
    └── gh-pages.yml     # déploiement GitHub Pages (brouillon)