docs: update CDN installation instructions (#349)

* wip: update installation instructions * refactor: update CDN installation instructions * feat: add french translation for new CDN instructions * docs: update CDN instructions
cds-snc · May 22, 2024 · e50337c · e50337c
1 parent 0f458f5
commit e50337c
Show file tree

Hide file tree

Showing 7 changed files with 138 additions and 45 deletions.
diff --git a/.eleventy.js b/.eleventy.js
@@ -6,14 +6,15 @@ const chroma = require('chroma-js');
 const markdownIt = require('markdown-it');
 const svgContents = require('eleventy-plugin-svg-contents');
 const codeClipboard = require('eleventy-plugin-code-clipboard');
+const { getLatestCdnVersion } = require('./utils/cdn-info');
 const { DateTime } = require('luxon');
 
 const contextMenu = require('./utils/context-menu');
 const displayTokens = require('./utils/display-tokens');
 const markdownAnchor = require('./utils/anchor');
 const slugify = require('./utils/slugify');
 
-const { execSync } = require('child_process')
+const { execSync } = require('child_process');
 
 module.exports = function (eleventyConfig) {
   // Pass through copies
@@ -154,10 +155,9 @@ module.exports = function (eleventyConfig) {
     return colourName;
   });
 
-  eleventyConfig.addFilter('stringify', (data) => {
-    return JSON.stringify(data, null, "\t")
-  })
-
+  eleventyConfig.addFilter('stringify', data => {
+    return JSON.stringify(data, null, '\t');
+  });
 
   /* Markdown Overrides */
   let markdownLibrary = markdownIt({
@@ -216,6 +216,11 @@ module.exports = function (eleventyConfig) {
     `;
   });
 
+  // Add shortcode for CDN info
+  eleventyConfig.addGlobalData('latestCdnVersion', async () => {
+    return await getLatestCdnVersion();
+  });
+
   eleventyConfig.addPairedShortcode(
     'docLinks',
     (children, locale, stage, figma, github) => {
@@ -307,8 +312,11 @@ module.exports = function (eleventyConfig) {
   });
 
   eleventyConfig.on('eleventy.after', () => {
-    execSync(`npx pagefind --site _site --exclude-selectors "gcds-side-nav, gcds-top-nav, gcds-breadcrumbs, .github-link, .figma-link, h1 > code, .component-preview" --glob \"**/*.html\"`, { encoding: 'utf-8' })
-  })
+    execSync(
+      `npx pagefind --site _site --exclude-selectors "gcds-side-nav, gcds-top-nav, gcds-breadcrumbs, .github-link, .figma-link, h1 > code, .component-preview" --glob \"**/*.html\"`,
+      { encoding: 'utf-8' },
+    );
+  });
 
   return {
     pathPrefix: process.env.PATH_PREFIX || '/',

diff --git a/src/_data/installation.js b/src/_data/installation.js
@@ -10,8 +10,8 @@ module.exports = {
       angular: 'Angular',
       react: 'React',
       vue: 'Vue',
-      node: 'Node with no framework',
-      cdn: 'No framework (without node)',
+      node: 'NodeJS with no Javascript framework',
+      cdn: 'Plain HTML - CDN',
       figma: "I'm a lost designer, looking for Figma",
       other: 'None of the above',
     },
@@ -23,18 +23,23 @@ module.exports = {
         heading: 'Install with npm',
         install: 'Navigate to the root folder of your project and run:',
         placeApp:
-          'Place the following code in the app.module.ts file of your app:',
+          'Place the following code in the <code>app.module.ts</code> file of your app:',
         placeStyles:
-          'Place the following code in the styles.scss file of your app:',
+          'Place the following code in the <code>styles.scss</code> file of your app:',
       },
       cdn: {
         paragraph:
           'Use these instructions to install GCDS components with no framework.',
         heading: 'Add the code',
+        version:
+          "Use the latest version of GC Design System. Version <code><span id='cdn-latest-version'></span></code>, released on <time id='cdn-latest-version-date'></time>, is the most recent. Pinned versions provide stability and predictability because the code will remain consistent and won't change unexpectedly, which can be crucial for maintaining the stability of an application. However, it requires manual updating of the CDN links whenever a newer version of GC Design System is released.",
         place:
-          'Place the following code in the <head> element of your project:',
+          'Place the following code in the <code>head</code> element of your project:',
         icons: 'to access icons, import Font Awesome',
-        note: 'Note: <script type="module"> requires a server to load properly. If developing locally, please use <script nomodule>.',
+        note: 'Note: <code>script type="module"</code> requires a server to load properly. If developing locally, please use <code>script nomodule</code>.',
+        subheading: 'Automatic updates using <code>@latest</code>',
+        latest:
+          'Use the <code>@latest</code> version of GC Design System to receive automatic updates whenever a new version is released. <strong>While it removes the need to manually update the CDN links, it adds the risk of introducing breaking changes to the codebase as new versions are automatically applied</strong>.',
       },
       choose: {
         paragraph:
@@ -49,7 +54,8 @@ module.exports = {
           "Use these instructions to install GCDS components if you're using npm (node package manager) with no framework.",
         heading: 'Install with npm',
         install: 'Navigate to the root folder of your project and run:',
-        place: 'Place the following code in the <head> element of your site:',
+        place:
+          'Place the following code in the <code>head</code> element of your site:',
         icons: 'to access icons, import Font Awesome',
       },
       other: {
@@ -63,7 +69,8 @@ module.exports = {
           "Use these instructions to install GCDS components if you're using React.",
         heading: 'Install with npm',
         install: 'Navigate to the root folder of your project and run:',
-        place: 'Place the following code in the index.js file of your app:',
+        place:
+          'Place the following code in the <code>index.js</code> file of your app:',
       },
       vue: {
         paragraph:
@@ -75,9 +82,8 @@ module.exports = {
         globalStyles:
           'Add the global styles to your app. There are multiple ways to achieve this.',
         styleOne:
-         'You can import it in your <code>main.js</code> file next to your <code>style.css</code>:',
-        styleTwo:
-         'or in your <code>App.vue</code> using the html style tag.',
+          'You can import it in your <code>main.js</code> file next to your <code>style.css</code>:',
+        styleTwo: 'or in your <code>App.vue</code> using the html style tag.',
       },
     },
     step3: {
@@ -92,17 +98,17 @@ module.exports = {
   },
   fr: {
     step1: {
-      heading: '1. Choisissez l’option qui vous convient le mieux',
+      heading: "1. Choisissez l'option qui vous convient le mieux",
       paragraph:
-        'La bibliothèque de composants SDGC fonctionne dans de multiples infrastructures ou peut être utilisée comme telle. Choisissez votre environnement de développement et suivez les instructions pour commencer votre projet.',
+        'La bibliothèque gcds-components fonctionne dans de multiples infrastructures ou peut être utilisée comme telle. Choisissez votre environnement de développement et suivez les instructions pour commencer votre projet.',
       label: 'Votre environnement de travail ',
       hint: "Sélectionnez l'option la plus pertinente",
       defaultValue: 'Choissisez une option',
       angular: 'Angular',
       react: 'React',
       vue: 'Vue',
-      node: 'Aucune infrastructure, avec nœud',
-      cdn: 'Aucune infrastructure, sans noeud',
+      node: 'NodeJS sans infrastructure JavaScript',
+      cdn: 'HTML simple — réseau CDN',
       figma: 'Je suis un·e concepteur·rice à la recherche de Figma',
       other: 'Autre chose',
     },
@@ -115,18 +121,23 @@ module.exports = {
         install:
           "Naviguez jusqu'au dossier racine de votre projet et exécutez :",
         placeApp:
-          'Insérez le code suivant dans le fichier app.module.ts de votre application :',
+          'Insérez le code suivant dans le fichier <code>app.module.ts</code> de votre application :',
         placeStyles:
-          'Insérez le code suivant dans le fichier styles.scss de votre application :',
+          'Insérez le code suivant dans le fichier <code>styles.scss</code> de votre application :',
       },
       cdn: {
         paragraph:
           'Pour installer les composants SDGC sans infrastructure, suivez ces instructions.',
         heading: 'Ajoutez le code',
+        version:
+          "Utilisez la version la plus récente de Système de design GC. La version <code><span id='cdn-latest-version'></span></code>, publiée le <time id='cdn-latest-version-date'></time>, est la plus récente. Les versions épinglées offrent stabilité et prévisibilité parce que le code ne changera pas de manière inattendue, ce qui peut être crucial pour maintenir la stabilité d'une application. Toutefois, il faut mettre à jour manuellement les liens CDN chaque fois qu'une version plus récente de Système de design GC est publiée.",
         place:
-          "Insérez le code suivant dans l'élément <head> de votre projet :",
+          "Insérez le code suivant dans l'élément <code>head</code> de votre projet :",
         icons: 'pour avoir accès aux icônes, installer Font Awesome',
-        note: 'Remarque : <script type="module"> nécessite un serveur pour le chargement. Pour le développement local, veuillez utiliser <script nomodule>.',
+        note: 'Remarque : <code>script type="module"</code> nécessite un serveur pour le chargement. Pour le développement local, veuillez utiliser <code>script nomodule</code>.',
+        subheading: 'Mises à jour automatiques grâce à <code>@latest</code>',
+        latest:
+          "Utilisez la version <code>@latest</code> de Système de design GC pour recevoir des mises à jour automatiques chaque fois qu'une nouvelle version est publiée. <strong>Bien que cette approche vous évite la mise à jour manuelle des liens CDN, elle court le risque d'introduire des modifications qui entraînent une rupture de compatibilité avec le code base à mesure que les nouvelles versions sont automatiquement appliquées</strong>.",
       },
       choose: {
         paragraph:
@@ -143,7 +154,8 @@ module.exports = {
         heading: "Installation à l'aide de npm",
         install:
           "Naviguez jusqu'au dossier racine de votre projet et exécutez :",
-        place: "Insérez le code suivant dans l'élément <head> de votre site :",
+        place:
+          "Insérez le code suivant dans l'élément <code>head</code> de votre site :",
         icons: 'pour avoir accès aux icônes, installer Font Awesome',
       },
       other: {
@@ -159,22 +171,22 @@ module.exports = {
         install:
           "Naviguez jusqu'au dossier racine de votre projet et exécutez :",
         place:
-          'Insérez le code suivant dans le fichier index.js de votre application :',
+          'Insérez le code suivant dans le fichier <code>index.js</code> de votre application :',
       },
       vue: {
         paragraph:
           'Si vous utilisez Vue, suivez ces instructions pour installer les composants SDGC.',
         heading: "Installation à l'aide de npm",
         install:
           "Naviguez jusqu'au dossier racine de votre projet et exécutez :",
-          place: 
-            'Dans votre fichier <code>main.js</code>, importez le plugiciel des composants Système de design GC et utilisez-le de la façon suivante :',
-          globalStyles: 
-            'Ajoutez les styles généraux à votre application. Vous pouvez les ajouter de plusieurs façons.',
-          styleOne:
-            'Vous pouvez soit les importer dans votre fichier <code>main.js</code> à côté de votre <code>style.css</code> :',
-          styleTwo:
-            'ou les insérer dans votre <code>App.vue</code> à l\'aide de la balise de style html.',
+        place:
+          'Dans votre fichier <code>main.js</code>, importez le plugiciel des composants Système de design GC et utilisez-le de la façon suivante :',
+        globalStyles:
+          'Ajoutez les styles généraux à votre application. Vous pouvez les ajouter de plusieurs façons.',
+        styleOne:
+          'Vous pouvez soit les importer dans votre fichier <code>main.js</code> à côté de votre <code>style.css</code> :',
+        styleTwo:
+          "ou les insérer dans votre <code>App.vue</code> à l'aide de la balise de style html.",
       },
     },
     step3: {

diff --git a/src/_includes/partials/installation/step-2-angular.njk b/src/_includes/partials/installation/step-2-angular.njk
@@ -9,7 +9,7 @@
   npm install @cdssnc/gcds-components @cdssnc/gcds-components-angular
   {% endhighlight %}
 
-  <p class="mt-500 mb-400">{{ installation[locale].step2.angular.placeApp }}</p>
+  <p class="mt-500 mb-400">{{ installation[locale].step2.angular.placeApp | safe }}</p>
 
 {% highlight "js" %}
 import { GcdsComponentsModule } from '@cdssnc/gcds-components-angular';
@@ -29,7 +29,7 @@ import { GcdsComponentsModule } from '@cdssnc/gcds-components-angular';
 export class AppModule { }
 {% endhighlight %}
 
-  <p class="mt-500 mb-400">{{ installation[locale].step2.angular.placeStyles }}</p>
+  <p class="mt-500 mb-400">{{ installation[locale].step2.angular.placeStyles | safe }}</p>
 
   {% highlight "js" %}
   @import '../node_modules/@cdssnc/gcds-components/dist/gcds/gcds.css';

diff --git a/src/_includes/partials/installation/step-2-cdn.njk b/src/_includes/partials/installation/step-2-cdn.njk
@@ -3,16 +3,66 @@
   <p class="mb-400">{{ installation[locale].step2.cdn.paragraph }}</p>
 
   <h3 class="mt-500 mb-400">{{ installation[locale].step2.cdn.heading }}</h3>
-  <p class="mb-400">{{ installation[locale].step2.cdn.place }}</p>
+  <p class="mb-400">{{ installation[locale].step2.cdn.version | safe }}</p>
+  <p class="mb-400">{{ installation[locale].step2.cdn.place | safe }}</p>
 
 {% highlight "html" %}
 <!-- Icons Font Awesome ({{ installation[locale].step2.cdn.icons }}) -->
 <link rel="stylesheet" href="{{ links.fontAwesome }}" crossorigin="anonymous">
 
 <!-- GC Design System -->
-<link rel="stylesheet" href="https://cdn.design-system.alpha.canada.ca/@cdssnc/gcds-components@latest/dist/gcds/gcds.css">
-<script type="module" src="https://cdn.design-system.alpha.canada.ca/@cdssnc/gcds-components@latest/dist/gcds/gcds.esm.js"></script>
-<script nomodule src="https://cdn.design-system.alpha.canada.ca/@cdssnc/gcds-components@latest/dist/gcds/gcds.js"></script>
+<link rel="stylesheet" href="https://cdn.design-system.alpha.canada.ca/@cdssnc/gcds-components@||version||/dist/gcds/gcds.css">
+<script type="module" src="https://cdn.design-system.alpha.canada.ca/@cdssnc/gcds-components@||version||/dist/gcds/gcds.esm.js"></script>
+<script nomodule src="https://cdn.design-system.alpha.canada.ca/@cdssnc/gcds-components@||version||/dist/gcds/gcds.js"></script>
 {% endhighlight %}
-  <small>{{ installation[locale].step2.cdn.note }}</small>
+
+  <small>{{ installation[locale].step2.cdn.note | safe }}</small>
+
+  <h3 class="mt-500 mb-400">{{ installation[locale].step2.cdn.subheading | safe }}</h3>
+  <p class="mb-400">{{ installation[locale].step2.cdn.latest | safe }}</p>
 </div>
+
+<script>
+  async function getLatestCdnVersion() {
+    const cdnLatestVersion = document.getElementById('cdn-latest-version');
+    const cdnLatestVersionDate = document.getElementById('cdn-latest-version-date');
+    const codeElements = document.querySelectorAll('.attr-value');
+
+    try {
+      // Fetch package metadata
+      const response = await fetch(
+        'https://registry.npmjs.org/@cdssnc/gcds-components',
+      );
+      const data = await response.json();
+
+      // Get latest version and release date
+      const latestVersion = data['dist-tags'].latest;
+      const releaseDate = new Date(data.time[latestVersion]);
+
+      // Format the release date to 'YYYY-MM-DD'
+      const formattedReleaseDate = `${releaseDate.getFullYear()}-${String(releaseDate.getMonth() + 1).padStart(2, '0')}-${String(releaseDate.getDate()).padStart(2, '0')}`;
+
+      // Update the latest version and release date in the description
+      cdnLatestVersion.textContent = latestVersion;
+      cdnLatestVersionDate.textContent = formattedReleaseDate;
+
+      // Update CDN links with the latest version
+      codeElements.forEach(element => {
+        element.textContent = element.textContent.replace('||version||', latestVersion);
+      });
+    } catch (error) {
+      console.error('Error fetching latest version:', error);
+
+      // Update the latest version and release date in the description
+      cdnLatestVersion.textContent = '{{ latestCdnVersion.version }}';
+      cdnLatestVersionDate.textContent = '{{ latestCdnVersion.releaseDate }}';
+
+      // Update CDN links with fallback version if fetch fails
+      codeElements.forEach(element => {
+        element.textContent = element.textContent.replace('||version||', '{{ latestCdnVersion.version }}');
+      });
+    }
+  }
+
+  getLatestCdnVersion();
+</script>
diff --git a/src/_includes/partials/installation/step-2-node.njk b/src/_includes/partials/installation/step-2-node.njk
@@ -9,7 +9,7 @@
   npm install @cdssnc/gcds-components
   {% endhighlight %}
 
-  <p class="mt-500 mb-400">{{ installation[locale].step2.node.place }}</p>
+  <p class="mt-500 mb-400">{{ installation[locale].step2.node.place | safe }}</p>
 
 {% highlight "html" %}
 <!-- Icons Font Awesome ({{ installation[locale].step2.node.icons }}) -->

diff --git a/src/_includes/partials/installation/step-2-react.njk b/src/_includes/partials/installation/step-2-react.njk
@@ -9,7 +9,7 @@
     npm install @cdssnc/gcds-components @cdssnc/gcds-components-react
   {% endhighlight %}
 
-  <p class="mt-500 mb-400">{{ installation[locale].step2.react.place }}</p>
+  <p class="mt-500 mb-400">{{ installation[locale].step2.react.place | safe }}</p>
 
   {% highlight "js" %}
     import '@cdssnc/gcds-components-react/gcds.css'

diff --git a/utils/cdn-info.js b/utils/cdn-info.js
@@ -0,0 +1,23 @@
+async function getLatestCdnVersion() {
+  try {
+    // Fetch package metadata
+    const response = await fetch(
+      'https://registry.npmjs.org/@cdssnc/gcds-components',
+    );
+    const data = await response.json();
+
+    // Get latest version and release date
+    const latestVersion = data['dist-tags'].latest;
+    const releaseDate = new Date(data.time[latestVersion]);
+
+    // Format the release date to 'YYYY-MM-DD'
+    const formattedReleaseDate = `${releaseDate.getFullYear()}-${String(releaseDate.getMonth() + 1).padStart(2, '0')}-${String(releaseDate.getDate()).padStart(2, '0')}`;
+
+    return { version: latestVersion, releaseDate: formattedReleaseDate };
+  } catch (error) {
+    console.error('Error fetching latest version:', error);
+    return { version: 'Unknown', releaseDate: 'Unknown' };
+  }
+}
+
+module.exports = { getLatestCdnVersion };