Skip to content
Arka Platform

Documentation static site

The docs/ documentation is published as an Astro Starlight static site hosted in the sibling repository arka-web/platform and deployed at https://platform.arkalabs.app.

The source of truth remains docs/ in the arka-deck repo. A sync script copies the content to the platform repo where Starlight consumes it.

Architecture

Section titled “Architecture”
arka-deck/                         ← source of truth
├── docs/produit/                  ← FR (/) + EN (/)
├── docs/dev/                      ← FR (/) + EN (/)
└── scripts/
    └── sync-docs-to-platform.mjs  ← copies docs/ to the platform repo


arka-web/platform/                 ← Astro Starlight site (different repo)
├── astro.config.mjs               ← Starlight config (FR/EN i18n, arka theme)
├── src/styles/arka.css            ← arka theme (light + dark, primary #c70f43)
└── src/content/docs/
    ├── index.mdx                  ← landing EN
    ├── fr/index.mdx               ← landing FR
    ├── arka-deck/                 ← EN content (synced from docs/*/)
    └── fr/arka-deck/              ← FR content (synced from docs/*/)

Synchronization

Section titled “Synchronization”
Terminal window
# From the arka-deck repo, sync to the sibling platform repo
node scripts/sync-docs-to-platform.mjs


# Or with explicit path if the workspace layout differs
ARKA_PLATFORM_DIR=/path/to/arka-web/platform \
  node scripts/sync-docs-to-platform.mjs

The script applies the following transformations:

  • 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 (Starlight convention)
  • Extracts the # H1 as the Starlight title frontmatter
  • Removes the redundant bilingual banner (the first markdown quote containing the two language-switch links)
  • Rewrites links to docs/adr/, LICENSE, CONTRIBUTING.md, etc. as absolute GitHub URLs (these resources are not published on the site)
  • Rewrites .en.md → .md in internal links (Starlight routes by language folder, not by suffix)

Synced scope: docs/produit/, docs/dev/.
Out of scope: docs/adr/, docs/archive/, docs/conventions/ (consulted directly on GitHub).

Build and deployment

Section titled “Build and deployment”

In arka-web/platform/:

Terminal window
cd arka-web/platform
npm install
npm run dev      # http://localhost:4321
npm run build    # produces dist/

Deployment is triggered by a push to main of the platform repo (Vercel or GitHub Pages depending on the arkalabs config).

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

Typical workflow to publish a doc change

Section titled “Typical workflow to publish a doc change”
  1. Edit content in arka-deck/docs/produit/ or docs/dev/ (FR + EN mirror).
  2. Commit and push to arka-deck.
  3. Run the sync:
    Terminal window
    node scripts/sync-docs-to-platform.mjs
  4. In arka-web/platform, verify generated changes, commit and push.
  5. Platform’s automatic deployment updates the live site.

Arka theme (light + dark)

Section titled “Arka theme (light + dark)”

The Starlight theme is defined in arka-web/platform/src/styles/arka.css. It mirrors the palette from arka-web/src/index.css:

  • Primary: #c70f43
  • Light palette (sand): #FAF7F4 / #F0EBE5 / #E3DCD5 / #1C1816
  • Dark palette: #171718 / #1e1e1f / #ffffff / #9ca3af
  • Fonts: Inter (sans), JetBrains Mono (mono) loaded via Google Fonts

Any theme change should go into arka.css.

See also

Section titled “See also”