@hgdc/docs 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs.schema.json +4 -0
- package/package.json +3 -2
- package/src/build/base-links.ts +35 -0
- package/src/build/outputs.ts +17 -4
- package/src/core/config.ts +8 -0
- package/src/core/llms.ts +8 -5
- package/src/core/navigation.ts +24 -0
- package/src/integration.ts +42 -6
- package/src/overrides/Head.astro +14 -12
- package/src/overrides/PageTitle.astro +95 -94
- package/src/overrides/Sidebar.astro +60 -60
- package/template/.astro/content-modules.mjs +15 -15
- package/template/.build/.well-known/llms.txt +17 -17
- package/template/.build/404.html +5 -5
- package/template/.build/_astro/Search.astro_astro_type_script_index_0_lang.Cn3-p701.js +1 -0
- package/template/.build/_astro/common.C-MpX45O.css +3 -0
- package/template/.build/_astro/{ui-core.Clh5jUUO.js → ui-core.CrG20ya_.js} +1 -1
- package/template/.build/_hgdc/corpus.json +1 -1
- package/template/.build/demarrer/premiere-doc/index.html +15 -15
- package/template/.build/demarrer/premiere-doc.md +3 -3
- package/template/.build/explications/donnees/index.html +11 -11
- package/template/.build/explications/donnees.md +1 -1
- package/template/.build/explications/fonctionnement/index.html +13 -12
- package/template/.build/explications/fonctionnement.md +3 -3
- package/template/.build/guides/agents/index.html +16 -11
- package/template/.build/guides/agents.md +16 -2
- package/template/.build/guides/assistant/index.html +14 -12
- package/template/.build/guides/assistant.md +5 -1
- package/template/.build/guides/composants/index.html +19 -19
- package/template/.build/guides/composants.md +8 -10
- package/template/.build/guides/ecrire/index.html +13 -12
- package/template/.build/guides/ecrire.md +1 -1
- package/template/.build/guides/navigation/index.html +13 -12
- package/template/.build/guides/publier/index.html +26 -17
- package/template/.build/guides/publier.md +9 -9
- package/template/.build/guides/theme/index.html +13 -12
- package/template/.build/guides/theme.md +1 -1
- package/template/.build/index.html +12 -11
- package/template/.build/index.md +11 -11
- package/template/.build/llms-full.txt +95 -69
- package/template/.build/llms.txt +17 -17
- package/template/.build/pagefind/fragment/fr-ch_2a431a9.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_456586a.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_68e734b.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_72b91f4.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_8f256dd.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_95a15cc.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_aa80c55.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_ab79738.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_cfa4336.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_dab8f5e.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_de60b43.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_e02aa49.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_e254a54.pf_fragment +0 -0
- package/template/.build/pagefind/index/fr-ch_a71411b.pf_index +0 -0
- package/template/.build/pagefind/pagefind-entry.json +1 -1
- package/template/.build/pagefind/pagefind.fr-ch_2f3ea8fccf961.pf_meta +0 -0
- package/template/.build/reference/api-assistant/index.html +12 -12
- package/template/.build/reference/api-assistant.md +13 -3
- package/template/.build/reference/cli/index.html +11 -11
- package/template/.build/reference/cli.md +5 -5
- package/template/.build/reference/docs-json/index.html +11 -11
- package/template/.build/reference/docs-json.md +2 -2
- package/template/.build/reference/mcp/index.html +11 -11
- package/template/node_modules/.vite/deps/_metadata.json +8 -8
- package/src/build/public-files.test.ts +0 -29
- package/src/core/core.test.ts +0 -253
- package/template/.build/_astro/Search.astro_astro_type_script_index_0_lang.g9hoxVJg.js +0 -1
- package/template/.build/_astro/common.8GHCkW7i.css +0 -3
- package/template/.build/pagefind/fragment/fr-ch_148313b.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_424fd16.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_5a4d77d.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_6c36edc.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_73d7887.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_8234ed3.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_8f8a19e.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_9f1b981.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_a19039d.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_d72cc1e.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_d732215.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_e78d58b.pf_fragment +0 -0
- package/template/.build/pagefind/fragment/fr-ch_e92f972.pf_fragment +0 -0
- package/template/.build/pagefind/index/fr-ch_f94c95d.pf_index +0 -0
- package/template/.build/pagefind/pagefind.fr-ch_fb78ab42961f4.pf_meta +0 -0
|
@@ -1,30 +1,30 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Docs
|
|
2
2
|
|
|
3
|
-
> Écrire une documentation en MDX, la publier avec
|
|
3
|
+
> Écrire une documentation en MDX, la publier avec Host et y brancher un assistant IA qui cite ses sources.
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
Source : /
|
|
7
|
+
Source : /docs/
|
|
8
8
|
|
|
9
|
-
# Bienvenue dans
|
|
9
|
+
# Bienvenue dans Docs
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Docs transforme un dossier de pages MDX en site de documentation. Tu écris dans ton dépôt Git, Host publie le site à chaque push, et la console `docs.hgdc.ch` branche un assistant qui répond à tes visiteurs à partir de ta doc, et de rien d’autre.
|
|
12
12
|
|
|
13
|
-
[Ta première doc](/demarrer/premiere-doc/)
|
|
13
|
+
[Ta première doc](/docs/demarrer/premiere-doc/)
|
|
14
14
|
|
|
15
|
-
[Un dossier, un fichier `docs.json` et une page : ton site tourne en local en cinq minutes.](/demarrer/premiere-doc/)
|
|
15
|
+
[Un dossier, un fichier `docs.json` et une page : ton site tourne en local en cinq minutes.](/docs/demarrer/premiere-doc/)
|
|
16
16
|
|
|
17
|
-
[Publier avec
|
|
17
|
+
[Publier avec Host](/docs/guides/publier/)
|
|
18
18
|
|
|
19
|
-
[Relie le dépôt à
|
|
19
|
+
[Relie le dépôt à Host : chaque push met le site à jour.](/docs/guides/publier/)
|
|
20
20
|
|
|
21
|
-
[L'assistant IA](/guides/assistant/)
|
|
21
|
+
[L'assistant IA](/docs/guides/assistant/)
|
|
22
22
|
|
|
23
|
-
[Il répond aux questions de tes visiteurs et cite les pages qu’il a utilisées.](/guides/assistant/)
|
|
23
|
+
[Il répond aux questions de tes visiteurs et cite les pages qu’il a utilisées.](/docs/guides/assistant/)
|
|
24
24
|
|
|
25
|
-
[Pour les agents](/guides/agents/)
|
|
25
|
+
[Pour les agents](/docs/guides/agents/)
|
|
26
26
|
|
|
27
|
-
[`llms.txt`, une version Markdown de chaque page et un serveur MCP en lecture.](/guides/agents/)
|
|
27
|
+
[`llms.txt`, une version Markdown de chaque page et un serveur MCP en lecture.](/docs/guides/agents/)
|
|
28
28
|
|
|
29
29
|
## Ce que tu obtiens
|
|
30
30
|
|
|
@@ -40,11 +40,11 @@ Le fichier `docs.json` reprend celui de Mintlify : nom, couleurs, logo, navigati
|
|
|
40
40
|
|
|
41
41
|
> **Tout reste en Suisse quand c'est possible**
|
|
42
42
|
>
|
|
43
|
-
> Le site est servi par
|
|
43
|
+
> Le site est servi par Host. Les questions des visiteurs sont gardées 90 jours au plus. Voir [Données et confidentialité](/docs/explications/donnees/).
|
|
44
44
|
|
|
45
45
|
---
|
|
46
46
|
|
|
47
|
-
Source : /demarrer/premiere-doc/
|
|
47
|
+
Source : /docs/demarrer/premiere-doc/
|
|
48
48
|
|
|
49
49
|
# Ta première doc en cinq minutes
|
|
50
50
|
|
|
@@ -108,23 +108,23 @@ Il te faut Node.js 22 ou plus récent, ou Bun. Tout le reste s’installe avec l
|
|
|
108
108
|
|
|
109
109
|
## Et ensuite
|
|
110
110
|
|
|
111
|
-
- [Publier avec
|
|
112
|
-
- [Écrire en MDX](/guides/ecrire/) pour les titres, les liens, les images et le code.
|
|
113
|
-
- [docs.json](/reference/docs-json/) pour toutes les options.
|
|
111
|
+
- [Publier avec Host](/docs/guides/publier/) pour mettre le site en ligne.
|
|
112
|
+
- [Écrire en MDX](/docs/guides/ecrire/) pour les titres, les liens, les images et le code.
|
|
113
|
+
- [docs.json](/docs/reference/docs-json/) pour toutes les options.
|
|
114
114
|
|
|
115
115
|
---
|
|
116
116
|
|
|
117
|
-
Source : /guides/publier/
|
|
117
|
+
Source : /docs/guides/publier/
|
|
118
118
|
|
|
119
|
-
# Publier avec
|
|
119
|
+
# Publier avec Host
|
|
120
120
|
|
|
121
|
-
|
|
121
|
+
Host construit ton site à chaque push et le sert depuis son serveur. La console `docs.hgdc.ch` relit ensuite le site publié pour indexer l’assistant.
|
|
122
122
|
|
|
123
123
|
## Mettre la doc en ligne
|
|
124
124
|
|
|
125
125
|
1. **Importer le dépôt**
|
|
126
126
|
|
|
127
|
-
Dans
|
|
127
|
+
Dans Host, crée un projet à partir de ton dépôt GitHub. Host reconnaît une doc Docs (un `docs.json` et le paquet `@hgdc/docs` dans `package.json`) : il la construit avec `hgdc-docs build` et publie le dossier `dist/`. Aucun fichier de configuration à ajouter.
|
|
128
128
|
|
|
129
129
|
2. **Fusionner la pull request de Host**
|
|
130
130
|
|
|
@@ -134,11 +134,11 @@ HGDC Host construit ton site à chaque push et le sert depuis son serveur. La co
|
|
|
134
134
|
|
|
135
135
|
Chaque push sur la branche principale publie le site en production. Les autres branches ont leur préversion.
|
|
136
136
|
|
|
137
|
-
## Activer
|
|
137
|
+
## Activer Docs
|
|
138
138
|
|
|
139
139
|
1. **Cliquer sur « Activer Docs »**
|
|
140
140
|
|
|
141
|
-
Sur la vue d’ensemble du projet dans
|
|
141
|
+
Sur la vue d’ensemble du projet dans Host, la carte **Assistant et recherche avec Docs** propose **Activer Docs**. Host crée le projet dans la console, dans la même organisation. Il faut être admin de l’organisation, et la doc doit déjà être en production.
|
|
142
142
|
|
|
143
143
|
2. **Publier une fois de plus**
|
|
144
144
|
|
|
@@ -146,19 +146,19 @@ HGDC Host construit ton site à chaque push et le sert depuis son serveur. La co
|
|
|
146
146
|
|
|
147
147
|
3. **Laisser faire**
|
|
148
148
|
|
|
149
|
-
À chaque mise en production, Host prévient la console, qui relit `/_hgdc/corpus.json` et indexe les pages en quelques secondes. La carte de Host affiche **
|
|
149
|
+
À chaque mise en production, Host prévient la console, qui relit `/_hgdc/corpus.json` et indexe les pages en quelques secondes. La carte de Host affiche **Docs est activé** et mène à la console. En plus, la console relit le site tous les quarts d’heure : un appel perdu se rattrape seul.
|
|
150
150
|
|
|
151
151
|
> **Note**
|
|
152
152
|
>
|
|
153
|
-
> Le projet apparaît dans la console dès que tu t’y connectes avec ton compte
|
|
153
|
+
> Le projet apparaît dans la console dès que tu t’y connectes avec ton compte H family. Ses réglages (domaines, assistant) s’y changent comme pour n’importe quel projet.
|
|
154
154
|
|
|
155
155
|
## Ton domaine
|
|
156
156
|
|
|
157
|
-
Le domaine se branche dans
|
|
157
|
+
Le domaine se branche dans Host, comme pour n’importe quel site : Host annonce la nouvelle adresse à la console à la mise en production suivante. Si la doc répond sur plusieurs adresses (`docs.acme.ch` et `aide.acme.ch`), ajoute les autres dans **Réglages › Domaines** : l’assistant ne répond qu’aux pages servies par ces adresses.
|
|
158
158
|
|
|
159
159
|
## Relier un projet existant
|
|
160
160
|
|
|
161
|
-
Le dossier `dist/` est un site statique, il se dépose chez n’importe quel hébergeur. Hors de
|
|
161
|
+
Le dossier `dist/` est un site statique, il se dépose chez n’importe quel hébergeur. Hors de Host, ou pour un projet créé directement dans la console, relie la doc à la main.
|
|
162
162
|
|
|
163
163
|
1. **Créer le projet dans la console**
|
|
164
164
|
|
|
@@ -184,7 +184,7 @@ Le dossier `dist/` est un site statique, il se dépose chez n’importe quel hé
|
|
|
184
184
|
|
|
185
185
|
---
|
|
186
186
|
|
|
187
|
-
Source : /guides/ecrire/
|
|
187
|
+
Source : /docs/guides/ecrire/
|
|
188
188
|
|
|
189
189
|
# Écrire en MDX
|
|
190
190
|
|
|
@@ -196,7 +196,7 @@ Le haut de la page, entre deux lignes `---`, décrit la page.
|
|
|
196
196
|
|
|
197
197
|
```mdx
|
|
198
198
|
---
|
|
199
|
-
title: Publier avec
|
|
199
|
+
title: Publier avec Host
|
|
200
200
|
sidebarTitle: Publier
|
|
201
201
|
description: Mettre la doc en ligne et brancher l'assistant.
|
|
202
202
|
---
|
|
@@ -252,7 +252,7 @@ Les fichiers qui commencent par `_` (comme `_brouillon.mdx`), `README.md`, `CHAN
|
|
|
252
252
|
|
|
253
253
|
---
|
|
254
254
|
|
|
255
|
-
Source : /guides/composants/
|
|
255
|
+
Source : /docs/guides/composants/
|
|
256
256
|
|
|
257
257
|
# Composants
|
|
258
258
|
|
|
@@ -304,9 +304,9 @@ Ces composants s’utilisent directement dans une page `.mdx`, sans `import`. Il
|
|
|
304
304
|
|
|
305
305
|
## Cartes
|
|
306
306
|
|
|
307
|
-
[Avec un lien](/guides/publier/)
|
|
307
|
+
[Avec un lien](/docs/guides/publier/)
|
|
308
308
|
|
|
309
|
-
[Toute la carte est cliquable.](/guides/publier/)
|
|
309
|
+
[Toute la carte est cliquable.](/docs/guides/publier/)
|
|
310
310
|
|
|
311
311
|
Sans lien
|
|
312
312
|
|
|
@@ -314,7 +314,9 @@ Pour présenter une idée.
|
|
|
314
314
|
|
|
315
315
|
```mdx
|
|
316
316
|
<CardGroup cols={2}>
|
|
317
|
-
<Card title="Avec un lien" href="/guides/publier/">
|
|
317
|
+
<Card title="Avec un lien" href="/guides/publier/">
|
|
318
|
+
Toute la carte est cliquable.
|
|
319
|
+
</Card>
|
|
318
320
|
<Card title="Sans lien">Pour présenter une idée.</Card>
|
|
319
321
|
</CardGroup>
|
|
320
322
|
```
|
|
@@ -323,13 +325,9 @@ Pour présenter une idée.
|
|
|
323
325
|
|
|
324
326
|
## Onglets
|
|
325
327
|
|
|
326
|
-
|
|
327
|
-
npm install --save-dev @hgdc/docs
|
|
328
|
-
```
|
|
328
|
+
`bash npm install --save-dev @hgdc/docs`
|
|
329
329
|
|
|
330
|
-
|
|
331
|
-
bun add --dev @hgdc/docs
|
|
332
|
-
```
|
|
330
|
+
`bash bun add --dev @hgdc/docs`
|
|
333
331
|
|
|
334
332
|
```mdx
|
|
335
333
|
<Tabs>
|
|
@@ -340,7 +338,7 @@ bun add --dev @hgdc/docs
|
|
|
340
338
|
|
|
341
339
|
## Accordéons
|
|
342
340
|
|
|
343
|
-
Faut-il un compte
|
|
341
|
+
Faut-il un compte H family pour écrire ?
|
|
344
342
|
|
|
345
343
|
Non. Le site se construit sans compte. Le compte sert à la console : publication suivie et assistant.
|
|
346
344
|
|
|
@@ -360,7 +358,7 @@ Chaque composant a une forme Markdown : un encadré devient une citation qui com
|
|
|
360
358
|
|
|
361
359
|
---
|
|
362
360
|
|
|
363
|
-
Source : /guides/navigation/
|
|
361
|
+
Source : /docs/guides/navigation/
|
|
364
362
|
|
|
365
363
|
# Navigation, onglets et versions
|
|
366
364
|
|
|
@@ -428,7 +426,7 @@ En bas de chaque page, les liens Précédent et Suivant suivent l’ordre de la
|
|
|
428
426
|
|
|
429
427
|
---
|
|
430
428
|
|
|
431
|
-
Source : /guides/theme/
|
|
429
|
+
Source : /docs/guides/theme/
|
|
432
430
|
|
|
433
431
|
# Thème et logo
|
|
434
432
|
|
|
@@ -446,7 +444,7 @@ Pour une couleur différente en mode sombre, ajoute `"dark": "#5eead4"`.
|
|
|
446
444
|
|
|
447
445
|
> **Note**
|
|
448
446
|
>
|
|
449
|
-
> Dans la console, **Réglages › Thème** montre l’effet d’une couleur en clair et en sombre, et prépare la ligne à copier dans `docs.json`.
|
|
447
|
+
> Dans la console, **Réglages › Thème** montre l’effet d’une couleur en clair et en sombre, son contraste sur un fond blanc, et prépare la ligne à copier dans `docs.json`.
|
|
450
448
|
|
|
451
449
|
## Logo
|
|
452
450
|
|
|
@@ -466,7 +464,7 @@ Sans favicon, le site n’en annonce pas d’autre que `/favicon.svg` s’il exi
|
|
|
466
464
|
|
|
467
465
|
---
|
|
468
466
|
|
|
469
|
-
Source : /guides/assistant/
|
|
467
|
+
Source : /docs/guides/assistant/
|
|
470
468
|
|
|
471
469
|
# L'assistant IA
|
|
472
470
|
|
|
@@ -495,10 +493,12 @@ L’assistant est actif dès que `docs.json` porte l’identifiant `project` et
|
|
|
495
493
|
|
|
496
494
|
Chaque organisation dispose d’un nombre de questions par mois, toutes docs confondues : 500 dans l’offre de départ. La console affiche la consommation. Au-delà, l’assistant répond qu’il a atteint sa limite, et HGDC relève le plafond sur demande.
|
|
497
495
|
|
|
498
|
-
Pour éviter qu’un seul visiteur épuise le quota, chaque visiteur a droit à 6 questions par minute, et chaque doc à 30.
|
|
496
|
+
Pour éviter qu’un seul visiteur ou un script épuise le quota, chaque visiteur a droit à 6 questions par minute et 40 par jour, et chaque doc à 30 par minute et 200 par jour. HGDC relève le plafond journalier d’une doc sur demande.
|
|
499
497
|
|
|
500
498
|
## Tester et lire le journal
|
|
501
499
|
|
|
500
|
+
En haut de la page **Assistant**, les 30 derniers jours : nombre de questions, part de réponses sourcées, et les **questions sans réponse**, regroupées et classées de la plus posée à la moins posée. Chacune ouvre le journal filtré : c’est la liste des pages à écrire.
|
|
501
|
+
|
|
502
502
|
**Assistant › Tester l’assistant** pose une question comme un visiteur. Le **journal** garde les questions des 90 derniers jours avec leur état :
|
|
503
503
|
|
|
504
504
|
| État | Ce que ça veut dire |
|
|
@@ -507,17 +507,19 @@ Pour éviter qu’un seul visiteur épuise le quota, chaque visiteur a droit à
|
|
|
507
507
|
| Hors doc | Rien dans la doc ne répond. Souvent une page à écrire. |
|
|
508
508
|
| Erreur | Le modèle n’a pas répondu ; le visiteur a été invité à réessayer. |
|
|
509
509
|
|
|
510
|
+
Au-dessus du journal, cherche une question par ses mots, ou filtre par état : **État › Hors doc** ne garde que les questions sans réponse. Les filtres restent dans l’adresse de la page : tu peux la garder en favori ou l’envoyer à un collègue.
|
|
511
|
+
|
|
510
512
|
> **Astuce**
|
|
511
513
|
>
|
|
512
514
|
> Lis les questions « hors doc » une fois par semaine : c’est la liste des pages qui manquent, écrite par tes visiteurs.
|
|
513
515
|
|
|
514
516
|
---
|
|
515
517
|
|
|
516
|
-
Source : /guides/agents/
|
|
518
|
+
Source : /docs/guides/agents/
|
|
517
519
|
|
|
518
520
|
# llms.txt et MCP
|
|
519
521
|
|
|
520
|
-
Les assistants de code et les agents lisent la documentation pour écrire du code juste.
|
|
522
|
+
Les assistants de code et les agents lisent la documentation pour écrire du code juste. Docs leur donne trois portes d’entrée, sans rien à configurer.
|
|
521
523
|
|
|
522
524
|
## llms.txt
|
|
523
525
|
|
|
@@ -546,6 +548,20 @@ Dans Claude Code :
|
|
|
546
548
|
claude mcp add --transport http acme-docs https://docs.hgdc.ch/mcp/<identifiant du projet>
|
|
547
549
|
```
|
|
548
550
|
|
|
551
|
+
Dans Cursor (`.cursor/mcp.json`) :
|
|
552
|
+
|
|
553
|
+
```json
|
|
554
|
+
{ "mcpServers": { "acme-docs": { "url": "https://docs.hgdc.ch/mcp/<identifiant du projet>" } } }
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
Dans VS Code (`.vscode/mcp.json`) :
|
|
558
|
+
|
|
559
|
+
```json
|
|
560
|
+
{ "servers": { "acme-docs": { "type": "http", "url": "https://docs.hgdc.ch/mcp/<identifiant du projet>" } } }
|
|
561
|
+
```
|
|
562
|
+
|
|
563
|
+
L’aperçu du projet donne ces lignes déjà remplies. Le serveur reste ouvert quand l’assistant du site est coupé : il ne fait que chercher, sans modèle.
|
|
564
|
+
|
|
549
565
|
Le serveur propose trois outils :
|
|
550
566
|
|
|
551
567
|
| Outil | Rôle |
|
|
@@ -554,15 +570,15 @@ Le serveur propose trois outils :
|
|
|
554
570
|
| `get_page` | Rend une page complète en Markdown, à partir de son chemin. |
|
|
555
571
|
| `list_pages` | Liste les pages avec leur titre et leur chemin. |
|
|
556
572
|
|
|
557
|
-
Le détail du protocole est dans la [référence MCP](/reference/mcp/).
|
|
573
|
+
Le détail du protocole est dans la [référence MCP](/docs/reference/mcp/).
|
|
558
574
|
|
|
559
575
|
---
|
|
560
576
|
|
|
561
|
-
Source : /reference/docs-json/
|
|
577
|
+
Source : /docs/reference/docs-json/
|
|
562
578
|
|
|
563
579
|
# docs.json
|
|
564
580
|
|
|
565
|
-
`docs.json` vit à la racine du dossier de la doc. Il reprend le format de Mintlify : les champs que
|
|
581
|
+
`docs.json` vit à la racine du dossier de la doc. Il reprend le format de Mintlify : les champs que Docs ne gère pas sont acceptés et ignorés. Pour l’autocomplétion dans ton éditeur, ajoute `"$schema": "https://docs.hgdc.ch/docs.schema.json"`.
|
|
566
582
|
|
|
567
583
|
## Champs
|
|
568
584
|
|
|
@@ -570,7 +586,7 @@ Source : /reference/docs-json/
|
|
|
570
586
|
| -------------------- | ---------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
571
587
|
| `name` | texte | oui | Nom de la doc, en tête du site et dans `llms.txt`. 80 caractères au plus. |
|
|
572
588
|
| `description` | texte | non | Une phrase de présentation. |
|
|
573
|
-
| `navigation` | objet | oui | Pages, groupes, onglets ou versions. Voir [Navigation](/guides/navigation/).
|
|
589
|
+
| `navigation` | objet | oui | Pages, groupes, onglets ou versions. Voir [Navigation](/docs/guides/navigation/). |
|
|
574
590
|
| `project` | texte | non | Identifiant du projet dans la console. Active l’assistant et l’indexation. |
|
|
575
591
|
| `language` | `fr`, `en`, `de`, `it` | non | Langue de l’interface du site. `fr` par défaut. |
|
|
576
592
|
| `colors.primary` | couleur `#rrggbb` | non | Couleur des liens et des éléments actifs. |
|
|
@@ -606,7 +622,7 @@ docs.json invalide :
|
|
|
606
622
|
|
|
607
623
|
---
|
|
608
624
|
|
|
609
|
-
Source : /reference/cli/
|
|
625
|
+
Source : /docs/reference/cli/
|
|
610
626
|
|
|
611
627
|
# La commande hgdc-docs
|
|
612
628
|
|
|
@@ -624,11 +640,11 @@ Options : `--port 4000` change le port de `dev` et `preview`, `--help` affiche l
|
|
|
624
640
|
|
|
625
641
|
## Variables d’environnement
|
|
626
642
|
|
|
627
|
-
| Variable | Rôle
|
|
628
|
-
| ---------------- |
|
|
629
|
-
| `HGDC_DOCS_SITE` | Adresse publique du site (`https://docs.acme.ch`). Rend les liens de `llms.txt` absolus et produit le sitemap. Sur
|
|
630
|
-
| `HGDC_DOCS_OUT` | Dossier de sortie, `dist/` par défaut.
|
|
631
|
-
| `HGDC_DOCS_API` | API de l’assistant, `https://docs.hgdc.ch` par défaut.
|
|
643
|
+
| Variable | Rôle |
|
|
644
|
+
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
645
|
+
| `HGDC_DOCS_SITE` | Adresse publique du site (`https://docs.acme.ch`). Rend les liens de `llms.txt` absolus et produit le sitemap. Sur Host, l’adresse de production est reprise seule. |
|
|
646
|
+
| `HGDC_DOCS_OUT` | Dossier de sortie, `dist/` par défaut. |
|
|
647
|
+
| `HGDC_DOCS_API` | API de l’assistant, `https://docs.hgdc.ch` par défaut. |
|
|
632
648
|
|
|
633
649
|
## Ce que contient dist/
|
|
634
650
|
|
|
@@ -642,7 +658,7 @@ Options : `--port 4000` change le port de `dev` et `preview`, `--help` affiche l
|
|
|
642
658
|
|
|
643
659
|
---
|
|
644
660
|
|
|
645
|
-
Source : /reference/api-assistant/
|
|
661
|
+
Source : /docs/reference/api-assistant/
|
|
646
662
|
|
|
647
663
|
# API de l'assistant
|
|
648
664
|
|
|
@@ -680,10 +696,20 @@ L’en-tête `Origin` doit être l’adresse du site ou un des domaines déclar
|
|
|
680
696
|
{
|
|
681
697
|
"id": "j97f…",
|
|
682
698
|
"status": "answered",
|
|
683
|
-
"answer": "Importe le dépôt dans
|
|
699
|
+
"answer": "Importe le dépôt dans Host[^1], puis synchronise le projet dans la console[^2].",
|
|
684
700
|
"sources": [
|
|
685
|
-
{
|
|
686
|
-
|
|
701
|
+
{
|
|
702
|
+
"n": 1,
|
|
703
|
+
"title": "Publier avec Host",
|
|
704
|
+
"section": "Avec Host",
|
|
705
|
+
"url": "https://docs.acme.ch/guides/publier/#avec-host"
|
|
706
|
+
},
|
|
707
|
+
{
|
|
708
|
+
"n": 2,
|
|
709
|
+
"title": "Publier avec Host",
|
|
710
|
+
"section": "Relier la console",
|
|
711
|
+
"url": "https://docs.acme.ch/guides/publier/#relier-la-console"
|
|
712
|
+
}
|
|
687
713
|
]
|
|
688
714
|
}
|
|
689
715
|
```
|
|
@@ -707,7 +733,7 @@ Chaque erreur porte aussi `error.message`, une phrase en français à montrer te
|
|
|
707
733
|
|
|
708
734
|
---
|
|
709
735
|
|
|
710
|
-
Source : /reference/mcp/
|
|
736
|
+
Source : /docs/reference/mcp/
|
|
711
737
|
|
|
712
738
|
# Serveur MCP
|
|
713
739
|
|
|
@@ -761,11 +787,11 @@ Le serveur est public et en lecture seule : il ne donne accès qu’à ce que le
|
|
|
761
787
|
|
|
762
788
|
---
|
|
763
789
|
|
|
764
|
-
Source : /explications/fonctionnement/
|
|
790
|
+
Source : /docs/explications/fonctionnement/
|
|
765
791
|
|
|
766
792
|
# Comment ça marche
|
|
767
793
|
|
|
768
|
-
|
|
794
|
+
Docs tient en trois pièces : un modèle de site, Host qui le publie, et la console qui l’indexe pour l’assistant.
|
|
769
795
|
|
|
770
796
|
## 1. Le modèle de site
|
|
771
797
|
|
|
@@ -773,9 +799,9 @@ Le paquet `@hgdc/docs` contient un site Astro Starlight complet. `hgdc-docs buil
|
|
|
773
799
|
|
|
774
800
|
Pendant le build, chaque page est aussi convertie en Markdown à partir du HTML final. Les composants sont donc déjà rendus : ce que lit un agent est exactement ce que voit un visiteur.
|
|
775
801
|
|
|
776
|
-
## 2. La publication par
|
|
802
|
+
## 2. La publication par Host
|
|
777
803
|
|
|
778
|
-
|
|
804
|
+
Host lance le build dans GitHub Actions à chaque push, puis sert le dossier `dist/` sur ton domaine. La doc est une source comme une autre : préversion par branche, retour arrière, domaine.
|
|
779
805
|
|
|
780
806
|
## 3. L’indexation par la console
|
|
781
807
|
|
|
@@ -798,7 +824,7 @@ Une question passe par deux recherches : par mots (les termes exacts, comme `doc
|
|
|
798
824
|
|
|
799
825
|
---
|
|
800
826
|
|
|
801
|
-
Source : /explications/donnees/
|
|
827
|
+
Source : /docs/explications/donnees/
|
|
802
828
|
|
|
803
829
|
# Données et confidentialité
|
|
804
830
|
|
|
@@ -814,7 +840,7 @@ La console ne stocke ni l’adresse IP ni l’identité des visiteurs. L’IP se
|
|
|
814
840
|
|
|
815
841
|
## Qui traite quoi
|
|
816
842
|
|
|
817
|
-
- **Le site** est servi par
|
|
843
|
+
- **Le site** est servi par Host.
|
|
818
844
|
- **La recherche du site** tourne dans le navigateur du visiteur : aucune requête ne part.
|
|
819
845
|
- **Les embeddings** des passages et des questions sont calculés par Mistral AI, dans l’Union européenne.
|
|
820
846
|
- **Les réponses** sont rédigées par Claude, le modèle d’Anthropic, appelé directement ou par OpenRouter. La question et les passages trouvés lui sont envoyés.
|
package/template/.build/llms.txt
CHANGED
|
@@ -1,38 +1,38 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Docs
|
|
2
2
|
|
|
3
|
-
> Écrire une documentation en MDX, la publier avec
|
|
3
|
+
> Écrire une documentation en MDX, la publier avec Host et y brancher un assistant IA qui cite ses sources.
|
|
4
4
|
|
|
5
5
|
Chaque page existe en Markdown à la même adresse suivie de `.md`. `llms-full.txt` contient toute la documentation en un seul fichier.
|
|
6
6
|
|
|
7
7
|
## Guides · Démarrer
|
|
8
8
|
|
|
9
|
-
- [Bienvenue dans
|
|
10
|
-
- [Ta première doc en cinq minutes](/demarrer/premiere-doc.md): Créer le dossier, écrire docs.json et une page, puis voir le site en local.
|
|
11
|
-
- [Publier avec
|
|
9
|
+
- [Bienvenue dans Docs](/docs/index.md): Ta documentation en MDX, publiée par Host, avec recherche, llms.txt et un assistant IA qui cite ses sources.
|
|
10
|
+
- [Ta première doc en cinq minutes](/docs/demarrer/premiere-doc.md): Créer le dossier, écrire docs.json et une page, puis voir le site en local.
|
|
11
|
+
- [Publier avec Host](/docs/guides/publier.md): Mettre la doc en ligne avec Host, activer Docs en un clic et brancher l'assistant.
|
|
12
12
|
|
|
13
13
|
## Guides · Écrire
|
|
14
14
|
|
|
15
|
-
- [Écrire en MDX](/guides/ecrire.md): Titres, liens, images, code et métadonnées d'une page.
|
|
16
|
-
- [Composants](/guides/composants.md): Encadrés, étapes, cartes, onglets et accordéons, disponibles dans chaque page sans import.
|
|
17
|
-
- [Navigation, onglets et versions](/guides/navigation.md): Organiser les pages en groupes, en onglets et en versions dans docs.json.
|
|
18
|
-
- [Thème et logo](/guides/theme.md): Poser ta couleur, ton logo et ton favicon dans docs.json.
|
|
15
|
+
- [Écrire en MDX](/docs/guides/ecrire.md): Titres, liens, images, code et métadonnées d'une page.
|
|
16
|
+
- [Composants](/docs/guides/composants.md): Encadrés, étapes, cartes, onglets et accordéons, disponibles dans chaque page sans import.
|
|
17
|
+
- [Navigation, onglets et versions](/docs/guides/navigation.md): Organiser les pages en groupes, en onglets et en versions dans docs.json.
|
|
18
|
+
- [Thème et logo](/docs/guides/theme.md): Poser ta couleur, ton logo et ton favicon dans docs.json.
|
|
19
19
|
|
|
20
20
|
## Guides · Assistant et agents
|
|
21
21
|
|
|
22
|
-
- [L'assistant IA](/guides/assistant.md): Ce que fait l'assistant, d'où viennent ses réponses, et comment le régler.
|
|
23
|
-
- [llms.txt et MCP](/guides/agents.md): Rendre la doc lisible par les outils d'IA, avec llms.txt, des pages en Markdown et un serveur MCP.
|
|
22
|
+
- [L'assistant IA](/docs/guides/assistant.md): Ce que fait l'assistant, d'où viennent ses réponses, et comment le régler.
|
|
23
|
+
- [llms.txt et MCP](/docs/guides/agents.md): Rendre la doc lisible par les outils d'IA, avec llms.txt, des pages en Markdown et un serveur MCP.
|
|
24
24
|
|
|
25
25
|
## Référence · Configuration
|
|
26
26
|
|
|
27
|
-
- [docs.json](/reference/docs-json.md): Tous les champs du fichier de configuration d'un site
|
|
28
|
-
- [La commande hgdc-docs](/reference/cli.md): Les commandes dev, build et preview, et les variables d'environnement du build.
|
|
27
|
+
- [docs.json](/docs/reference/docs-json.md): Tous les champs du fichier de configuration d'un site Docs.
|
|
28
|
+
- [La commande hgdc-docs](/docs/reference/cli.md): Les commandes dev, build et preview, et les variables d'environnement du build.
|
|
29
29
|
|
|
30
30
|
## Référence · API
|
|
31
31
|
|
|
32
|
-
- [API de l'assistant](/reference/api-assistant.md): La requête que le widget envoie, la réponse et les codes d'erreur.
|
|
33
|
-
- [Serveur MCP](/reference/mcp.md): Transport, méthodes et outils du serveur MCP en lecture d'un projet.
|
|
32
|
+
- [API de l'assistant](/docs/reference/api-assistant.md): La requête que le widget envoie, la réponse et les codes d'erreur.
|
|
33
|
+
- [Serveur MCP](/docs/reference/mcp.md): Transport, méthodes et outils du serveur MCP en lecture d'un projet.
|
|
34
34
|
|
|
35
35
|
## Explications · Sous le capot
|
|
36
36
|
|
|
37
|
-
- [Comment ça marche](/explications/fonctionnement.md): Du push au site publié, puis à l'assistant qui répond.
|
|
38
|
-
- [Données et confidentialité](/explications/donnees.md): Ce qui est stocké, où, combien de temps, et qui y accède.
|
|
37
|
+
- [Comment ça marche](/docs/explications/fonctionnement.md): Du push au site publié, puis à l'assistant qui répond.
|
|
38
|
+
- [Données et confidentialité](/docs/explications/donnees.md): Ce qui est stocké, où, combien de temps, et qui y accède.
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":"1.5.2","languages":{"fr-ch":{"hash":"fr-
|
|
1
|
+
{"version":"1.5.2","languages":{"fr-ch":{"hash":"fr-ch_2f3ea8fccf961","wasm":"fr-ch","page_count":15}},"include_characters":["_","‿","⁀","⁔","︳","︴","﹍","﹎","﹏","_"]}
|
|
Binary file
|