Aller au contenu
@aws/nx-plugin
Blog

Astro Docs

Ce générateur crée un site de documentation propulsé par Astro et le thème de documentation Starlight. Il configure la localisation, les extraits de contenu réutilisables, les liens internes sensibles à la locale et un plugin starlight-blog par défaut.

Par défaut, il crée également un pipeline de traduction automatisé propulsé par un Strands Agent sur Amazon Bedrock.

Utilisation

Section intitulée « Utilisation »

Générer un site de documentation Astro

Section intitulée « Générer un site de documentation Astro »

Vous pouvez générer un nouveau site de documentation Astro de deux manières :

  1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
  2. Ouvrez la console Nx dans VSCode
  3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
  4. Recherchez @aws/nx-plugin - ts#astro-docs
  5. Remplissez les paramètres requis
    • Cliquez sur Generate

    Options

    Section intitulée « Options »
    Paramètre Type Par défaut Description
    name Requis string docs Le nom du projet de documentation.
    directory string . Le répertoire parent dans lequel le projet de documentation est placé.
    subDirectory string - Le sous-répertoire dans lequel le projet de documentation est placé. Par défaut, le nom du projet en kebab-case.
    noTranslation boolean Désactiver le pipeline de traduction automatique de la documentation (Strands Agent sur Amazon Bedrock + une cible de projet `translate`).
    noBlog boolean Désactiver le plugin `starlight-blog` et l'article de blog exemple.
    skipInstall boolean Ignorer l'installation des dépendances après l'exécution du générateur.

    Sortie du générateur

    Section intitulée « Sortie du générateur »

    Par défaut, le générateur crée la structure de projet suivante dans docs/ à la racine de l’espace de travail (configurable via les options name, directory et subDirectory) :

    • astro.config.mjs Configuration Astro + Starlight (locales, barre latérale, plugin blog)
    • tsconfig.json Étend astro/tsconfigs/strict avec des alias de chemin @components / @assets
    • project.json Projet Nx avec les cibles build, start, preview (et translate si activé)
    • Répertoirescripts
      • translate.ts Pilote de traduction — un agent Strands avec un outil d’édition de fichiers délimité (omis avec --noTranslation)
      • translate.config.json Locales source/cible, motifs glob, id du modèle, région (omis avec --noTranslation)
    • Répertoiresrc
      • Répertoirecomponents
        • link.astro Composant de lien sensible à la locale (résout les chemins par rapport à la locale actuelle)
        • snippet.astro Composant de chargement d’extraits sensible à la locale
      • Répertoirecontent
        • Répertoiredocs
          • Répertoireen
            • index.mdx Page d’accueil
            • Répertoireguides
              • getting-started.mdx Guide d’exemple référençant les composants link et snippet
            • Répertoireblog
              • welcome.mdx Article de blog d’exemple (omis avec --noBlog)
            • Répertoiresnippets
              • example.mdx Extrait réutilisable d’exemple
      • Répertoirestyles
        • custom.css Personnalisations du thème Starlight
    • README.md README du projet

    Localisation

    Section intitulée « Localisation »

    Le générateur utilise par défaut une seule locale (en) et redirige l’URL racine vers celle-ci. Pour ajouter d’autres langues :

    1. Ajoutez une entrée sous locales dans astro.config.mjs (par exemple ko: { label: '한국어' }).
    2. Créez un répertoire correspondant sous src/content/docs/<locale>/.
    3. Remplissez-le manuellement, ou utilisez la cible de traduction décrite ci-dessous.

    Traduction

    Section intitulée « Traduction »

    Sauf si vous avez passé --noTranslation, le générateur ajoute une cible translate à project.json, vous pouvez donc exécuter :

    Terminal window
    pnpm nx translate docs -- --all
    pnpm nx translate docs -- --languages jp,ko
    pnpm nx translate docs -- --dry-run

    Lorsqu’il est exécuté sans --all, le script ne traduit que les fichiers qui ont changé depuis le dernier commit de traduction sur la branche actuelle — ce qui signifie que vous pouvez le réexécuter en toute sécurité sur chaque PR de documentation sans retraduire l’ensemble du site.

    Configuration de la traduction

    Section intitulée « Configuration de la traduction »

    Modifiez scripts/translate.config.json pour changer :

    ChampObjectif
    sourceLanguageLocale à partir de laquelle traduire (par défaut en).
    targetLanguagesLocales vers lesquelles traduire. Vide par défaut. Par exemple ["fr", "de", "es", "ja", "ko"].
    docsDirChemin vers le répertoire de contenu de documentation, relatif à la racine du projet.
    includeMotifs glob (relatifs à <docsDir>/<sourceLanguage>) pour les fichiers à traduire.
    excludeMotifs glob à ignorer.
    modelIdModèle Bedrock à utiliser pour les traductions.
    awsRegionRégion AWS avec laquelle le client Bedrock est configuré. Peut également être défini via AWS_REGION.
    concurrencyNombre maximum d’invocations d’agent simultanées.
    translationCommitMessageMarqueur de message de commit pour les commits de traduction (par défaut docs: update translations).

    Liens internes sensibles à la locale

    Section intitulée « Liens internes sensibles à la locale »

    Le générateur fournit un composant Link qui résout automatiquement les chemins de documentation internes par rapport à la locale actuelle, de sorte qu’une seule source de vérité produit la bonne URL dans chaque langue :

    import Link from '@components/link.astro';
    

    <Link path="guides/getting-started">Read the getting-started guide</Link>

    Extraits

    Section intitulée « Extraits »

    Les fragments de contenu réutilisables se trouvent dans src/content/docs/<locale>/snippets/. Le composant Snippet généré charge l’extrait qui correspond à la locale actuelle :

    import Snippet from '@components/snippet.astro';
    

    <Snippet name="example" />

    Configuration de la CI

    Section intitulée « Configuration de la CI »

    Aucun workflow CI n’est généré par défaut — ajoutez-en un qui :

    1. Configure les identifiants AWS avec la permission d’invoquer Bedrock InvokeModel sur le modèle configuré.

    2. Exécute la cible translate sur les pull requests qui touchent votre documentation en langue source :

      Terminal window
      pnpm nx translate docs

    3. Commit les traductions résultantes dans la branche de la PR. Le message de commit doit correspondre à la valeur translationCommitMessage dans scripts/translate.config.json (par défaut docs: update translations) afin que les exécutions incrémentielles ultérieures puissent détecter le commit de base et ne retraduire que les fichiers qui ont changé depuis.