Aller au contenu
Arka Platform

Site statique de documentation

La documentation docs/ est publiée comme un site statique Astro Starlight hébergé dans le dépôt voisin arka-web/platform et déployé sur https://platform.arkalabs.app.

La source de vérité reste docs/ dans le dépôt arka-deck. Un script de synchronisation copie le contenu vers le dépôt platform où Starlight le consomme.

Architecture

Section intitulée « Architecture »
arka-deck/                         ← source de vérité
├── docs/produit/                  ← FR (/) + EN (.en/)
├── docs/dev/                      ← FR (/) + EN (.en/)
└── scripts/
    └── sync-docs-to-platform.mjs  ← copie docs/ vers le dépôt platform


arka-web/platform/                 ← site Astro Starlight (autre dépôt)
├── astro.config.mjs               ← config Starlight (i18n FR/EN, thème arka)
├── src/styles/arka.css            ← thème arka (light + dark, primary #c70f43)
└── src/content/docs/
    ├── index.mdx                  ← landing EN
    ├── fr/index.mdx               ← landing FR
    ├── arka-deck/                 ← contenu EN (synchronisé depuis docs/*.en/)
    └── fr/arka-deck/              ← contenu FR (synchronisé depuis docs/*/)

Synchronisation

Section intitulée « Synchronisation »
Fenêtre de terminal
# Depuis le dépôt arka-deck, sync vers le dépôt platform voisin
node scripts/sync-docs-to-platform.mjs


# Ou avec chemin explicite si la structure de workspace diffère
ARKA_PLATFORM_DIR=/path/to/arka-web/platform \
  node scripts/sync-docs-to-platform.mjs

Le script applique les transformations suivantes :

  • docs/produit/<x>.md → src/content/docs/fr/arka-deck/produit/<x>.md
  • docs/produit/<x>.en.md → src/content/docs/arka-deck/produit/<x>.md
  • docs/dev/<x>.md → src/content/docs/fr/arka-deck/dev/<x>.md
  • docs/dev/<x>.en.md → src/content/docs/arka-deck/dev/<x>.md
  • README.md → index.md (convention Starlight)
  • Extrait le # H1 comme title du frontmatter Starlight
  • Supprime le bandeau bilingue redondant (la première quote markdown qui contient les deux liens de bascule de langue)
  • Réécrit les liens vers docs/adr/, LICENSE, CONTRIBUTING.md, etc. en URLs GitHub absolues (ces ressources ne sont pas publiées sur le site)
  • Réécrit .en.md → .md dans les liens internes (Starlight route par dossier de langue, pas par suffixe)

Périmètre synchronisé : docs/produit/, docs/dev/.
Hors périmètre : docs/adr/, docs/archive/, docs/conventions/ (consultés directement sur GitHub).

Build et déploiement

Section intitulée « Build et déploiement »

Côté arka-web/platform/ :

Fenêtre de terminal
cd arka-web/platform
npm install
npm run dev      # http://localhost:4321
npm run build    # produit dist/

Le déploiement se fait par push sur main du dépôt platform (intégration Vercel ou GitHub Pages selon la config arkalabs).

URL publique : https://platform.arkalabs.app

Workflow type pour publier une modif de doc

Section intitulée « Workflow type pour publier une modif de doc »
  1. Modifier le contenu dans arka-deck/docs/produit/ ou docs/dev/ (FR + EN miroir).
  2. Commit + push dans arka-deck.
  3. Lancer le sync :
    Fenêtre de terminal
    node scripts/sync-docs-to-platform.mjs
  4. Aller dans arka-web/platform, vérifier les changements générés, commit + push.
  5. Le déploiement automatique de platform met le site à jour.

Thème arka (light + dark)

Section intitulée « Thème arka (light + dark) »

Le thème Starlight est défini dans arka-web/platform/src/styles/arka.css. Il reprend la charte d’arka-web/src/index.css :

  • Primary : #c70f43
  • Palette light (sand) : #FAF7F4 / #F0EBE5 / #E3DCD5 / #1C1816
  • Palette dark : #171718 / #1e1e1f / #ffffff / #9ca3af
  • Fonts : Inter (sans), JetBrains Mono (mono) chargées via Google Fonts

Toute modification de la charte doit aller dans arka.css.

Voir aussi

Section intitulée « Voir aussi »