Merge pull request #19023 from github/sublanding-fixes

Sublanding page updates

Author: sarahs

content/README.md

@@ -207,7 +207,7 @@ defaultPlatform: linux
 - type: `String`. This should reference learning tracks' names defined in [`data/learning-tracks/*.yml`](../data/learning-tracks/README.md).
 - Optional
 
-**Note: the first learning track is by-default the featured track.*
+**Note: the featured track is set by a specific property in the learning tracks YAML. See that [README](../data/learning-tracks/README.md) for details.*
 
 ### `includeGuides`
 - Purpose: Render a list of articles, filterable by `type` and `topics`. Only applicable when used with `layout: product-sublanding`.

data/learning-tracks/README.md

@@ -1,3 +1,30 @@
 # Learning Tracks (aka Learning Paths)
 
-Learning tracks are a collection of articles that help you master a particular subject. Learning tracks are defined on a per-product basis.
+Learning tracks are a collection of articles that help you master a particular subject. Learning tracks are defined on a per-product basis. For example, see https://docs.github.com/en/actions/guides.
+
+Learning track data for a product is defined in two places:
+
+1. A simple array of learning track names is defined in the product sublanding index page frontmatter.
+
+    For example, in `content/actions/guides/index.md`:
+    ```
+    learningTracks:
+      - getting_started
+      - continuous_integration
+      - continuous_deployment
+      - deploy_to_the_cloud
+      - hosting_your_own_runners
+      - create_actions
+    ```
+
+2. Additional data for each track is defined in a YAML file named for the **product** in the `data` directory.
+
+    For example, in `data/learning-tracks/actions.yml`, each of the items from the content file's `learningTracks` array is represented with additional data such as `title`, `description`, and an array of `guides` links.
+
+    One learning track in this YAML **per version** must be designated as a "featured" learning track via `featured_track: true`, which will set it to appear at the top of the product sublanding page. A test will fail if this property is missing.
+
+    The `featured_track` property can be a simple boolean (i.e., `featured_track: true`) or it can be a string that includes versioning statements (e.g., `featured_track: '{% if currentVersion == "free-pro-team@latest" %}true{% else %}false{% endif %}'`). If you use versioning, you'll have multiple `featured_track`s per YML file, but make sure that only one will render in each currently supported version. A test will fail if there are more or less than one featured link for each version.
+
+Versioning for learning tracks is processed at page render time. The code lives in [`lib/learning-tracks.js`](lib/learning-tracks.js), which is called by `page.render()`. The processed learning tracks are then rendered by `layouts/product-sublanding.html`.
+
+The schema for validating the learning track YAML lives in [`tests/helpers/schemas/learning-tracks-schema.js`](tests/helpers/schemas/learning-tracks-schema.js) and is exercised by [`tests/content/lint-files.js`](tests/content/lint-files.js).

data/learning-tracks/actions.yml

@@ -7,6 +7,7 @@ getting_started:
     - /actions/learn-github-actions/essential-features-of-github-actions
     - /actions/learn-github-actions/managing-complex-workflows
     - /actions/learn-github-actions/security-hardening-for-github-actions
+  featured_track: true
 continuous_integration:
   title: 'Build and test code'
   description: 'You can create custom continuous integration (CI) workflows right in your repository.'

layouts/product-sublanding.html

@@ -22,8 +22,8 @@ <h1 class="my-3 font-mktg">{% data ui.product_sublanding.guides %}</h1>
           </header>
 
           <!-- Featured track -->
-          {% assign featuredTrack = page.learningTracks[0] %}
-          {% if featuredTrack %}
+          {% if page.featuredTrack %}
+          {% assign featuredTrack = page.featuredTrack %}
           <div class="mb-6 position-relative overflow-hidden mr-n3 ml-n3 px-3">
             <ul class="list-style-none d-flex flex-nowrap overflow-x-scroll px-2 feature-track">
               <li class="px-2 d-flex flex-shrink-0">
@@ -58,14 +58,14 @@ <h3 class="font-mktg h3-mktg my-4 color-text-primary">{{ guide.title }}</h3>
           {% endif %}
 
           {% assign learningTracks = page.learningTracks %}
-          {% if learningTracks %}
+          {% if learningTracks and learningTracks.size > 0 %}
           <div class="border-top py-6">
             <h2 class="mb-3 font-mktg">{% data ui.product_sublanding.learning_paths %}</h2>
             <div class="lead-mktg color-text-secondary f4 description-text">{% data ui.product_sublanding.learning_paths_desc %}</div>
 
             <!-- Learning tracks -->
             <div class="d-flex flex-wrap flex-items-start my-5 gutter">
-              {% for track in page.learningTracks offset:1 %}
+              {% for track in learningTracks %}
                 <div class="my-3 px-4 col-12 col-md-6 learning-track">
                   <div class="Box js-show-more-container d-flex flex-column">
                     <div class="Box-header bg-gradient--blue-pink p-4 d-flex flex-1 flex-items-start flex-wrap">

lib/page.js

@@ -11,6 +11,7 @@ const pathUtils = require('./path-utils')
 const Permalink = require('./permalink')
 const languages = require('./languages')
 const renderContent = require('./render-content')
+const processLearningTracks = require('./process-learning-tracks')
 const { renderReact } = require('./react/engine')
 const { productMap } = require('./all-products')
 const slash = require('slash')
@@ -207,23 +208,10 @@ class Page {
       this.permissions = await renderContent(this.rawPermissions, context)
     }
 
+    // Learning tracks may contain Liquid and need to have versioning processed.
     if (this.learningTracks) {
-      const learningTracks = []
-      for await (const rawTrackName of this.rawLearningTracks) {
-        // Track names in frontmatter may include Liquid conditionals
-        const renderedTrackName = await renderContent(rawTrackName, context, { textOnly: true, encodeEntities: true })
-        if (!renderedTrackName) continue
-
-        const track = context.site.data['learning-tracks'][context.currentProduct][renderedTrackName]
-        if (!track) continue
-        learningTracks.push({
-          trackName: renderedTrackName,
-          title: await renderContent(track.title, context, { textOnly: true, encodeEntities: true }),
-          description: await renderContent(track.description, context, { textOnly: true, encodeEntities: true }),
-          guides: await getLinkData(track.guides, context)
-        })
-      }
-
+      const { featuredTrack, learningTracks } = await processLearningTracks(this.rawLearningTracks, context)
+      this.featuredTrack = featuredTrack
       this.learningTracks = learningTracks
     }
 

lib/process-learning-tracks.js

@@ -0,0 +1,51 @@
+const renderContent = require('./render-content')
+const getLinkData = require('./get-link-data')
+
+const renderOpts = { textOnly: true, encodeEntities: true }
+
+// This module returns an object that contains a single featured learning track
+// and an array of all the other learning tracks for the current version.
+module.exports = async function processLearningTracks (rawLearningTracks, context) {
+  const learningTracks = []
+
+  let featuredTrack
+
+  for await (const rawTrackName of rawLearningTracks) {
+    let isFeaturedTrack = false
+
+    // Track names in frontmatter may include Liquid conditionals.
+    const renderedTrackName = await renderContent(rawTrackName, context, renderOpts)
+    if (!renderedTrackName) continue
+
+    // Find the data for the current product and track name.
+    const track = context.site.data['learning-tracks'][context.currentProduct][renderedTrackName]
+    if (!track) continue
+
+    const learningTrack = {
+      trackName: renderedTrackName,
+      title: await renderContent(track.title, context, renderOpts),
+      description: await renderContent(track.description, context, renderOpts),
+      // getLinkData respects versioning and only returns guides available in the current version;
+      // if no guides are available, the learningTrack.guides property will be an empty array.
+      guides: await getLinkData(track.guides, context)
+    }
+
+    // Determine if this is the featured track.
+    if (track.featured_track) {
+      // Featured track properties may be booleans or string that include Liquid conditionals with versioning.
+      // We need to parse any strings to determine if the featured track is relevant for this version.
+      isFeaturedTrack = track.featured_track === true || (await renderContent(track.featured_track, context, renderOpts) === 'true')
+
+      if (isFeaturedTrack) {
+        featuredTrack = learningTrack
+      }
+    }
+
+    // Only add the track to the array of tracks if there are guides in this version and it's not the featured track.
+    if (learningTrack.guides.length && !isFeaturedTrack) {
+      learningTracks.push(learningTrack)
+    }
+  }
+
+  return { featuredTrack, learningTracks }
+}

middleware/context.js

@@ -51,6 +51,7 @@ module.exports = async function contextualize (req, res, next) {
   req.context.siteTree = siteTree
   req.context.pages = pageMap
 
+  // TODO we should create new data directories for these example files instead of using variable files
   if (productMap[req.context.currentProduct]) {
     req.context.productCodeExamples = req.context.site.data.variables[`${productMap[req.context.currentProduct].id}_code_examples`]
     req.context.productCommunityExamples = req.context.site.data.variables[`${productMap[req.context.currentProduct].id}_community_examples`]

tests/helpers/schemas/learning-tracks-schema.js

@@ -0,0 +1,29 @@
+module.exports = {
+  properties: {
+    type: 'object',
+    additionalProperties: false,
+    patternProperties: {
+      '^[a-zA-Z-_]+$': {
+        type: 'object',
+        properties: {
+          title: {
+            type: 'string',
+            required: true
+          },
+          description: {
+            type: 'string',
+            required: true
+          },
+          guides: {
+            type: 'array',
+            items: { type: 'string' },
+            required: true
+          },
+          featured_track: {
+            type: 'boolean'
+          }
+        }
+      }
+    }
+  }
+}

tests/linting/lint-files.js

@@ -11,15 +11,19 @@ const frontmatter = require('../../lib/frontmatter')
 const languages = require('../../lib/languages')
 const { tags } = require('../../lib/liquid-tags/extended-markdown')
 const ghesReleaseNotesSchema = require('../helpers/schemas/release-notes-schema')
+const learningTracksSchema = require('../helpers/schemas/learning-tracks-schema')
 const renderContent = require('../../lib/render-content')
 const { execSync } = require('child_process')
+const allVersions = Object.keys(require('../../lib/all-versions'))
+const enterpriseServerVersions = allVersions.filter(v => v.startsWith('enterprise-server@'))
 
 const rootDir = path.join(__dirname, '../..')
 const contentDir = path.join(rootDir, 'content')
 const reusablesDir = path.join(rootDir, 'data/reusables')
 const variablesDir = path.join(rootDir, 'data/variables')
 const glossariesDir = path.join(rootDir, 'data/glossaries')
 const ghesReleaseNotesDir = path.join(rootDir, 'data/release-notes')
+const learningTracks = path.join(rootDir, 'data/learning-tracks')
 
 const languageCodes = Object.keys(languages)
 
@@ -167,7 +171,7 @@ const yamlWalkOptions = {
 }
 
 // different lint rules apply to different content types
-let mdToLint, ymlToLint, releaseNotesToLint
+let mdToLint, ymlToLint, releaseNotesToLint, learningTracksToLint
 
 if (!process.env.TEST_TRANSLATION) {
   // compile lists of all the files we want to lint
@@ -196,8 +200,13 @@ if (!process.env.TEST_TRANSLATION) {
 
   // GHES release notes
   const ghesReleaseNotesYamlAbsPaths = walk(ghesReleaseNotesDir, yamlWalkOptions).sort()
-  const ghesReleaseNotesYamlRelPaths = ghesReleaseNotesYamlAbsPaths.map(p => path.relative(rootDir, p))
+  const ghesReleaseNotesYamlRelPaths = ghesReleaseNotesYamlAbsPaths.map(p => slash(path.relative(rootDir, p)))
   releaseNotesToLint = zip(ghesReleaseNotesYamlRelPaths, ghesReleaseNotesYamlAbsPaths)
+
+  // Learning tracks
+  const learningTracksYamlAbsPaths = walk(learningTracks, yamlWalkOptions).sort()
+  const learningTracksYamlRelPaths = learningTracksYamlAbsPaths.map(p => slash(path.relative(rootDir, p)))
+  learningTracksToLint = zip(learningTracksYamlRelPaths, learningTracksYamlAbsPaths)
 } else {
   // get all translated markdown or yaml files by comparing files changed to main branch
   const changedFilesRelPaths = execSync('git diff --name-only origin/main | egrep "^translations/.*/.+.(yml|md)$"', { maxBuffer: 1024 * 1024 * 100 }).toString().split('\n')
@@ -207,7 +216,7 @@ if (!process.env.TEST_TRANSLATION) {
 
   console.log(`Found ${changedFilesRelPaths.length} translated files.`)
 
-  const { mdRelPaths = [], ymlRelPaths = [], releaseNotesRelPaths = [] } = groupBy(changedFilesRelPaths, (path) => {
+  const { mdRelPaths = [], ymlRelPaths = [], releaseNotesRelPaths = [], learningTracksRelPaths = [] } = groupBy(changedFilesRelPaths, (path) => {
     // separate the changed files to different groups
     if (path.endsWith('README.md')) {
       return 'throwAway'
@@ -217,20 +226,23 @@ if (!process.env.TEST_TRANSLATION) {
       return 'ymlRelPaths'
     } else if (path.match(/\/data\/release-notes\//i)) {
       return 'releaseNotesRelPaths'
+    } else if (path.match(/\data\/learning-tracks/)) {
+      return 'learningTracksRelPaths'
     } else {
       // we aren't linting the rest
       return 'throwAway'
     }
   })
 
-  const [mdTuples, ymlTuples, releaseNotesTuples] = [mdRelPaths, ymlRelPaths, releaseNotesRelPaths].map(relPaths => {
+  const [mdTuples, ymlTuples, releaseNotesTuples, learningTracksTuples] = [mdRelPaths, ymlRelPaths, releaseNotesRelPaths, learningTracksRelPaths].map(relPaths => {
     const absPaths = relPaths.map(p => path.join(rootDir, p))
     return zip(relPaths, absPaths)
   })
 
   mdToLint = mdTuples
   ymlToLint = ymlTuples
   releaseNotesToLint = releaseNotesTuples
+  learningTracksToLint = learningTracksTuples
 }
 
 function formatLinkError (message, links) {
@@ -694,3 +706,60 @@ describe('lint release notes', () => {
     }
   )
 })
+
+describe('lint learning tracks', () => {
+  if (learningTracksToLint.length < 1) return
+  describe.each(learningTracksToLint)(
+    '%s',
+    (yamlRelPath, yamlAbsPath) => {
+      let dictionary
+
+      beforeAll(async () => {
+        const fileContents = await readFileAsync(yamlAbsPath, 'utf8')
+        dictionary = yaml.safeLoad(fileContents, { filename: yamlRelPath })
+      })
+
+      it('matches the schema', () => {
+        const { errors } = revalidator.validate(dictionary, learningTracksSchema)
+        const errorMessage = errors.map(error => `- [${error.property}]: ${error.actual}, ${error.message}`).join('\n')
+        expect(errors.length, errorMessage).toBe(0)
+      })
+
+      it('has one and only one featured track per version', async () => {
+        const featuredTracks = {}
+        const context = { enterpriseServerVersions }
+
+        await Promise.all(allVersions.map(async (version) => {
+          const featuredTracksPerVersion = (await Promise.all(Object.values(dictionary).map(async (entry) => {
+            if (!entry.featured_track) return
+            context.currentVersion = version
+            const isFeaturedLink = typeof entry.featured_track === 'boolean' || (await renderContent(entry.featured_track, context, { textOnly: true, encodeEntities: true }) === 'true')
+            return isFeaturedLink
+          })))
+            .filter(Boolean)
+
+          featuredTracks[version] = featuredTracksPerVersion.length
+        }))
+
+        Object.entries(featuredTracks).forEach(([version, numOfFeaturedTracks]) => {
+          const errorMessage = `Expected one featured learning track for ${version} in ${yamlAbsPath}`
+          expect(numOfFeaturedTracks, errorMessage).toBe(1)
+        })
+      })
+
+      it('contains valid liquid', () => {
+        const toLint = []
+        Object.values(dictionary).forEach(({ title, description }) => {
+          toLint.push(title)
+          toLint.push(description)
+        })
+
+        toLint.forEach(element => {
+          expect(() => renderContent.liquid.parse(element), `${element} contains invalid liquid`)
+            .not
+            .toThrow()
+        })
+      })
+    }
+  )
+})