GARANCE

Graphe des Archives nationales pour la Recherche, l'Accès et la Navigation des Connaissances Enrichies

Mise en ligne sous forme de site statique des données des référentiels des Archives Nationales publiées dans le dépôt https://github.com/ArchivesNationalesFR/Referentiels. Utilise 11ty comme outil de génération de site, et du JSON-LD framing pour structurer les notices des entités. Le framing est appliqué avec la librairie Javascript jsonld.js.

Structure des répertoires

garance
├── .eleventy.js
├── package.json
├── _json
│   ├── ... Fichiers JSON après lecture mais avant framing
├── src
│   ├── _data
│   |   ├── framings
│   |   |   ├── ... Fichiers de specs du framing
│   |   ├── i18n
│   |   |   ├── en
│   |   |   |   ├── ... Fichiers de traductions (CSV and JS)
│   |   |   ├── fr
│   |   |   |   ├── ... Fichiers de traductions (CSV and JS)
│   |   ├── ... Fichiers JSON après framing
│   ├── entities
│   ├── _layouts
│   ├── pages
│   |   ├── en
│   |   |   ├── ... Fichiers de contenu *.md (dont page d'accueil index.md)
│   |   ├── fr
│   |   |   ├── ... Fichiers de contenu *.md (dont page d'accueil index.md)
├── static
│   ├── ... CSS, javascript, images, etc.
├── scripts
│   ├── ... commandes exécutées pour traiter les données : frame et read
├── utils
│   ├── ... Javascripts utilisés dans la génération du site (mais pas dans le site lui-même)

`package.json`

Fichier de config principal de tout le projet. Contient notamment les dépendances aux librairies Javascript, et la définition des commances npm run read, npm run frame, npm run start et npm run read utiles pour la génération du site.

`.eleventy.js`

Fichier de config principal d'11ty. Il charge les filtres Javascripts utiles à la génération du site et donne les chemins nécessaires à 11ty

`_json`

Répertoire dans le lequel se retrouve le gros fichier JSON-LD garance.jsonqui est la concaténation de la lecture de tous les référentiels, et sur lequel est appliqué le framing. Ce répertoire est créé par la commande npm run read.

`scripts`

Répertoire contenant les commandes "frame" et "read" utilisées pour préparer les données avant la génération du site. En plus, une répertoire avec script python.

`src`

Répertoire contenant toutes les sources à partir desquelles le site est généré

`src/_data`

Répertoire contenant tous les fichiers de données sources qui alimentent le site. En particulier, ce répertoire est alimenté par le résultat du framing (commande npm run frame)

`src/_data/framings`

Fichiers de spécifications du framing JSON-LD, utilisés par la commande npm run frame et appliqué sur le fichier d'entrée _json/garance.json

`src/_data/i18n`

Répertoire contenant les traductions des libellés du site en anglais et en français.

`src/entities`

Répertoire contenant les markdowns qui déclenchent la génération des pages sous l'URL /entities. Ce sont des fichiers vides qui font appel à un layout sous src/_layouts qui fait effectivement le travail.

`src/_layouts`

Répertoire contenant les layouts qui se chargent de la génération du HTML à partir des données. Contient toute la mise en forme HTML du site à partir des données. En particulier le fichier jsonld.njk est un template générique d'affichage de n'importe quelle structure JSON-LD.

`src/pages`

Répertoire contenant les pages statiques du site (non produites à partir de fichiers de données JSON). Ces pages doivent exister en 2 variantes, anglaise et française.

`static`

Répertoire contenant tous les fichiers statiques du site final (images, Javascripts, CSS, etc...), qui est recopié tel quel dans la sortie.

`utils`

Répertoire contenant tous les scripts utiles pour la génération du site (mais pas dans le site lui-même). Ce sont des filtres Nunjuck pour l'affichage des données des données

Commandes de génération du site

1. Installer les dépendances

npm install

2. Faire un clone du repository Référentiels

git clone https://github.com/ArchivesNationalesFR/Referentiels.git

3. Lancer le read

npm run read <chemin vers le repository Référentiels> : appelle le script utils/read.js pour lire le contenu des RDF. Exemple : npm run read ../Referentiels Cette commande créé le fichier _json/garance.json

3. Lancer le framing

npm run frame Cette commande applique les specs de framing du dossier src/_data/framings sur le fichier _json/garance.json, pour produire des fichiers dans src/_data, par exemple src/_data/agents.json.

4. Lancer la génération du site

4.1 Génération initiale du site

npm run build pour la génération du site final. Le résultat finale est dans le répertoire dist

4.2 Lancer le serveur sans regénérer le site

npm run start-ignore-initial pour lancer le serveur sans regénération complète initiale du site. Le site sera toutefois regénéré de façon incrémentale si un fichier source est modifié.

5. Construire l'index Pagefind

npx pagefind pour construire l'index pagefind.

5. Développement sur une machine locale

npm run start pour lancer le serveur local avec génération initiale du site
Arrêter le serveur (CTRL+C) une fois le site généré
npx pagefind pour générer l'index pagefind
npm run start-ignore-initial pour relancer le serveur sans régénération initiale, mais qui prendra en compte l'index pagefind

Fichiers JSON générés par le framing

L'étape de framing génère les fichiers JSON suivants dans src/_data:

agents.json : toutes les données des notices d'agent (sans l'entête)
agentsHeader.json : toutes les données des entêtes des agents
places.json : toutes les données des notices de lieux (sans l'entête et les coordonnées)
placesHeader.json : les entêtes des lieux
placesLocation.json : les coordonnées des lieux
vocabularies.json : tous les vocabulaires SKOS
index.json : donne la liste des vocabulaires contrôlés

Fichiers de "filters" sous `src/utils`

Le dossier src/utils contient les fichiers suivants qui contiennent des "filters" Nunjucks, c'est-à-dire des fonctions utilitaires appelées par les layouts:

filters.js : filtres/fonctions génériques (affichages de dates, etc.)
jsonld.js : filtres génériques pour le parsing de JSON-LD, utilisé par le layout générique jsonld.njk
shapes.js : filtres génériques pour le parsing de shapes.json, qui est un fichier JSON qui encode quelques éléments d'une config SHACL - aussi utilisé par jsonld.njk
archives-nationales.js : filtres spécifiques pour le projet Garance

Fichier i18n de traductions

dans src/_data/i18n en particulier garance.js contient les libellés des entrées de menu qui correspondent aux vocabulaires contrôlés

Fichiers de layout

Sous src/_layouts :

vocabulary.njk : layout d'affichage des pages de vocabulaire contrôlés
jsonld.njk : layout d'affichage générique d'un objet JSON-LD en HTML
letters-agents.njk et letters-places.njk : indexs alphabétiques
main.njk : template racine principal dans lequel le résultat des autres templates est inclus
agentOrPlaceHeader.njk : template d'entête pour les agents et les lieux

### Fichier shapes.json

Ce fichier contient les paramétrages pour:

l'ordre d'affichage des propriétés pour chaque type d'entité (sh:order)
la propriété à utiliser pour trier des valeurs multiples : "dash:propertyRole": "dash:sortKeyRole"
Paramétrage PageFind :
- les propriétés à utiliser pour les meta dans Pagefind : "pagefind:meta": ["Date de début"]
- les propriétés à utiliser pour les facettes Pagefind : "pagefind:filter": ["Type de collectivité"]
- le poids dans l'index : "pagefind:weight": 3.0
- les propriétés à ignorer : "pagefind:ignore": true
la classe CSS à appliquer sur la propriété : "volipi:class": "horizontal",
un template spécifique d'affichage : "volipi:template": "renderRicoIdentifier",

Guide pour afficher une propriété supplémentaire dans l'entête

Travailler avec un tout petit sous-ensemble de notices pour tester plus rapidement en supprimant à la main des notices dans les dossiers des référentiels
Faire une branche séparée pour la modification de façon à pouvoir la faire valider
Modifier le framing d'entête des agents ou des lieux : src/_data/framings/agentsHeader-framing.json et ajouter une entrée pour lire et structurer le prédicat correspondant 1.1 Tester avec la commande de frame et vérifier que la sortie contient bien les données attendues
Ajouter un ou plusieurs filtres dans le fichier javascript src/utils/archives-nationales.js pour réaliser la lecture de la structure de données ajoutée dans le framing et renvoyer les bonnes données au layout d'affichage
Modifier la layout d'affichage de l'entête : src/_layouts/agentOrPlaceHeader.njk
Modifier éventuellement les règles CSS liées à l'affichage de l'entête : src/static/assets/css/garance.css

/!\ Instable / Non testé - Utilisation de Python pour le framing JSON-LD et les CVS RiC-O

Prérequis

Python 3.12

Installation pip

sudo apt install python3-pip

Aller au répertoire scripts\python

Création d'environnement Virtuel

python -m venv envgarance

Activer l'environnement

Windows : envgarance/Scripts/activate.bat
Linux : source envgarance/

Installation de paquets

pip install -r requirements.txt

Dans le répértoire script/python, on a 2 fichiers label.py et convertToJson.py:

Script `label.py`

Créer fichiers de traductions RiC-0 dans Français et Anglais. Les résultats se stocke dans les fichiers rico.csv et definition.csv.

Lancer le script Python

python label.py --input <Répertoire des fichiers de traductions RIC-O>

Exemple python label.py --input ../../rico

Script `convertToJson.py`

Convertir des fichiers RDF en un fichier JSON-LD.

Utilisation du Script:

    python convertToJson.py --generate READ --input <Répertoire de fichiers RDF> --context <Fichier de context> --output <>
    [--context] :

Exemple python convertToJson.py --generate READ --input .../Referentiels --context ../context.json --output garance.json

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
scripts		scripts
src		src
static		static
utils		utils
.eleventy.js		.eleventy.js
.gitignore		.gitignore
README.md		README.md
convert.sh		convert.sh
package-lock.json		package-lock.json
package.json		package.json
pagefind.yml		pagefind.yml
sticky-test.html		sticky-test.html
test-wkt-leaflet.html		test-wkt-leaflet.html

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

GARANCE

Structure des répertoires

package.json

.eleventy.js

_json

scripts

src

src/_data

src/_data/framings

src/_data/i18n

src/entities

src/_layouts

src/pages

static

utils