Documents de travail (Working Papers)
working-papers.RmdVue 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-pdfou Typst viawp-typst—wp-typstest le moteur ajouté par défaut parsetup_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-pdfreste 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.
- On initialise ou corrige une installation avec
setup_wp() - On vérifie et diagnostique par
check() - On fait le rendu avec
render()(on peut avoir à régler de nombreux problèmes de rendu) - On publie avec
publish()(envoyé en staging tant qu’il n’est pas validé, ou sur une url stable lorsqu’il est validé) - On demande la validation par
registry_request()
Note 1 : le bouton
renderde Rstudio ne produit pas le même résultat querender(). 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 liensde\_quarto.yml). Si c’est un problème, ajoutez un\_au début du nom u.qmd. Il sera exclu. Glisser le.qmddans 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 :
- Avoir installé
git,ghsur son ordinateur - Etre correctement identifié/loggé pour
gitetgh(github.com) - Avoir généré/disposé des tokens (PAT) poriu l’identification
- 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
settingsaccessible sur la pagegithub.comdu 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
)- Vérifie la connexion GitHub (
gh::gh("GET /user")) - Initialise la branche orpheline
gh-pages(pré-publication GitHub Pages) - Copie les gabarits (
_quarto.yml,index.qmd,annexes.qmd,news.qmd) - Copie les assets OFCE (
www/) et installe/met à jour les extensions Quarto OFCE (_extensions/) viaofce::setup_quarto()(accès réseau nécessaire) - Force-remplace les workflows GitHub Actions
(
.github/workflows/) depuis le package — les workflows ne doivent pas être édités manuellement - Adapte
_quarto.ymlavec le titre, l’URL, le numéro WP, l’année, la langue - 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/anneesont synchronisés depuis cette entrée etdraftest 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()check() vérifie :
- Connexion GitHub :
gh::gh("GET /user")(warning non bloquant si absent) - Champs obligatoires dans
_quarto.yml:annee,author,date,citation -
index.qmdprésent et déclarant les formatswp-htmletwp-pdf/wp-typst -
references.bibprésent (warning sinon) -
news.qmdprésent (warning sinon) - Si WP publié : cohérence
version/site-path,anneevalide - Tous les
.qmdnon-index référencés danswebsite.other-links - Unicité des
output-filePDF
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 :
-
check()sicheck(abandon si erreurs bloquantes)- Vérifie la connexion GitHub (
gh::gh("GET /user"))
- Vérifie la connexion GitHub (
- Vide
_site/ -
quarto::quarto_render(output_format = "all")— HTML + PDF - Reconstruction du sitemap
- Patch des hashes Bootstrap CSS
-
wp_manifest()— écriture / mise à jour demanifest.json - Synchronisation de
FTP_SERVER_DIR(variable GitHub Actions) - Réécriture des liens absolus en relatifs si
render_site - Pousse vers la branche de déploiement si
site2branch - Lance
servr::httw("_site")sirender_site
4. Déployer le WP
deploy()Le comportement dépend de la valeur de wp dans
_quarto.yml :
-
Brouillon (
wp: null) →quarto publish gh-pages(publie surofce.github.io/{repo}/) ou pousse en staging sur le site de l’ofce à l’adressestaging.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é degithub.run_numberà chaque exécution deftp_stage.yml— indépendant du numéro deversion(v0,v1, …). -
Publié (
wp: N) →site2branch()verssite-deploy, puis le workflow FTP transfère verswww.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.
-
Demander un numéro via
registry_request(), qui calcule le numéro (auto-incrémenté, ou fourni viawp =) et ouvre une PR contreofce/wp-registry—anneeest lu depuis_quarto.ymlsi absent, etcontactdepuisgit config user.emailsi 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.
- 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) :
setup_wp()- 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-wpLe 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éewp_version_up() met à jour en cascade :
- Le champ
versiondans_quarto.yml - Le dernier segment de
website.site-path - Le
server-dirdans.github/workflows/ftp_deploy.yml -
manifest.json(viawp_manifest())
Après l’incrémentation, rendre et déployer à nouveau :
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é parlatex(format: wp-pdf) et que le convertisseurrsvg-convertn’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échocoauquel cas c’estchoco install rsvg-convert). Sirsvg-convertn’est pas installé, le format des images serapnget le pdf très volumineux. Alternativement,format: wp-typstfonctionne 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 clefpdf-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 unalt-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: truedans le format html
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)