Support arbitrary keys in new featuredLinks frontmatter (github#16239)

* Add featuredLinks to frontmatter * Parse them in featured-links.js * Remove old raw setup * Use them * Missed a couple * Update translation files * Fix frontmatter schema * Loop over the right object * Also update translations' usage * Update docs and tests * Better README comment Co-authored-by: Sarah Schneider <[email protected]> * Return next() Co-authored-by: Sarah Schneider <[email protected]>
shahrokh90 · Oct 27, 2020 · 174d853 · 174d853
1 parent 4704063
commit 174d853
Show file tree

Hide file tree

Showing 39 changed files with 412 additions and 375 deletions.
diff --git a/content/README.md b/content/README.md
@@ -16,7 +16,7 @@ See the [contributing docs](/CONTRIBUTING.md) for general information about work
   - [`product`](#product)
   - [`layout`](#layout)
   - [`mapTopic`](#maptopic)
-  - [`gettingStartedLinks` and `popularLinks`](#gettingstartedlinks-and-popularlinks)
+  - [`featuredLinks`](#featuredlinks)
   - [`showMiniToc`](#showminitoc)
   - [`miniTocMaxHeadingLevel`](#minitocmaxheadinglevel)
   - [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename)
@@ -132,12 +132,22 @@ For a layout named `layouts/article.html`, the value would be `article`.
 - Type: `Boolean`. Default is `false`.
 - Optional.
 
-### `gettingStartedLinks` and `popularLinks`
+### `featuredLinks`
 
-- Purpose: Renders the linked articles' titles and intros under `Getting started` and `Popular articles` headings, respectively. See site homepage for an example.
-- Type: `Array`.
+- Purpose: Renders the linked articles' titles and intros on product landing pages and the homepage.
+- Type: `Object`.
 - Optional.
 
+Example:
+
+```yaml
+featuredLinks:
+  gettingStarted:
+    - /path/to/page
+  guides:
+    - /guides/example
+```
+
 ### `showMiniToc`
 
 - Purpose: Indicates whether an article should show a mini TOC above the rest of the content. See [Autogenerated mini TOCs](#autogenerated-mini-tocs) for more info.

diff --git a/content/actions/index.md b/content/actions/index.md
@@ -5,15 +5,16 @@ intro: 'Automate, customize, and execute your software development workflows rig
 introLinks:
   quickstart: /actions/quickstart
   learn: /actions/learn-github-actions
-gettingStartedLinks:
-  - /actions/managing-workflow-runs
-  - /actions/hosting-your-own-runners
-guideLinks:
-  - /actions/guides/setting-up-continuous-integration-using-workflow-templates
-  - /actions/guides/about-packaging-with-github-actions
-popularLinks:
-  - /actions/reference/workflow-syntax-for-github-actions
-  - /actions/reference/events-that-trigger-workflows
+featuredLinks:
+  gettingStarted:
+    - /actions/managing-workflow-runs
+    - /actions/hosting-your-own-runners
+  guide:
+    - /actions/guides/setting-up-continuous-integration-using-workflow-templates
+    - /actions/guides/about-packaging-with-github-actions
+  popular:
+    - /actions/reference/workflow-syntax-for-github-actions
+    - /actions/reference/events-that-trigger-workflows
 redirect_from:
   - /articles/automating-your-workflow-with-github-actions/
   - /articles/customizing-your-project-with-github-actions/
@@ -42,7 +43,7 @@ versions:
       <h3 class="f5 text-normal text-mono underline-dashed color-gray-5">{% data ui.toc.guides %}</h3>
     </div>
     <ul class="list-style-none">
-      {% for link in guideLinks %}
+      {% for link in featuredLinks.guide %}
         <li>{% include featured-link %}</li>
       {% endfor %}
     </ul>
@@ -53,7 +54,7 @@ versions:
       <h3 class="f5 text-normal text-mono underline-dashed color-gray-5">{% data ui.toc.popular_articles %}</h3>
     </div>
     <ul class="list-style-none">
-      {% for link in popularLinks %}
+      {% for link in featuredLinks.popular %}
         <li>{% include featured-link %}</li>
       {% endfor %}
     </ul>
@@ -64,7 +65,7 @@ versions:
       <h3 class="f5 text-normal text-mono underline-dashed color-gray-5">Manage workflows</h3>
     </div>
     <ul class="list-style-none">
-      {% for link in gettingStartedLinks %}
+      {% for link in featuredLinks.gettingStarted %}
         <li>{% include featured-link %}</li>
       {% endfor %}
     </ul>

diff --git a/content/index.md b/content/index.md
@@ -1,16 +1,17 @@
 ---
 title: '{% data variables.product.product_name %}{% if currentVersion == "free-pro-team@latest" %}.com{% endif %} Help Documentation'
-gettingStartedLinks:
-  - /github/getting-started-with-github/set-up-git
-  - /github/authenticating-to-github/connecting-to-github-with-ssh
-  - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github
-  - /github/writing-on-github/basic-writing-and-formatting-syntax
-popularLinks:
-  - /github/collaborating-with-issues-and-pull-requests/about-pull-requests
-  - /github/authenticating-to-github
-  - /github/importing-your-projects-to-github/adding-an-existing-project-to-github-using-the-command-line
-  - /github/using-git/managing-remote-repositories
-  - /github/working-with-github-pages
+featuredLinks:
+  gettingStarted:
+    - /github/getting-started-with-github/set-up-git
+    - /github/authenticating-to-github/connecting-to-github-with-ssh
+    - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github
+    - /github/writing-on-github/basic-writing-and-formatting-syntax
+  popular:
+    - /github/collaborating-with-issues-and-pull-requests/about-pull-requests
+    - /github/authenticating-to-github
+    - /github/importing-your-projects-to-github/adding-an-existing-project-to-github-using-the-command-line
+    - /github/using-git/managing-remote-repositories
+    - /github/working-with-github-pages
 versions: '*'
 ---
 
diff --git a/content/insights/index.md b/content/insights/index.md
@@ -2,14 +2,15 @@
 title: GitHub Insights Documentation
 shortTitle: GitHub Insights
 intro: 'Understand and improve your software delivery process through data with {% data variables.product.prodname_insights %}. You can view customized reports based on data from {% data variables.product.prodname_enterprise %}.'
-gettingStartedLinks:
-  - /insights/installing-and-configuring-github-insights/about-github-insights
-  - /insights/installing-and-configuring-github-insights/system-overview-for-github-insights
-  - /insights/installing-and-configuring-github-insights/installing-github-insights
-  - /insights/exploring-your-usage-of-github-enterprise/viewing-key-metrics-and-reports
-popularLinks:
-  - /insights/installing-and-configuring-github-insights/about-data-in-github-insights
-  - /insights/exploring-your-usage-of-github-enterprise/metrics-available-with-github-insights
+featuredLinks:
+  gettingStarted:
+    - /insights/installing-and-configuring-github-insights/about-github-insights
+    - /insights/installing-and-configuring-github-insights/system-overview-for-github-insights
+    - /insights/installing-and-configuring-github-insights/installing-github-insights
+    - /insights/exploring-your-usage-of-github-enterprise/viewing-key-metrics-and-reports
+  popular:
+    - /insights/installing-and-configuring-github-insights/about-data-in-github-insights
+    - /insights/exploring-your-usage-of-github-enterprise/metrics-available-with-github-insights
 redirect_from:
   - /github/installing-and-configuring-github-insights
 versions:

diff --git a/content/packages/index.md b/content/packages/index.md
@@ -2,18 +2,19 @@
 title: GitHub Packages Documentation
 shortTitle: GitHub Packages
 intro: 'Learn to safely publish and consume packages, store your packages alongside your code, and share your packages privately with your team or publicly with the open source community. You can also automate your packages with {% data variables.product.prodname_actions %}.'
-gettingStartedLinks:
-  - /packages/publishing-and-managing-packages/about-github-packages
-  - /packages/getting-started-with-github-container-registry/about-github-container-registry
-  - /packages/getting-started-with-github-container-registry
-  - /packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images
-  - /packages/publishing-and-managing-packages/publishing-a-package
-  - /packages/publishing-and-managing-packages/installing-a-package
-popularLinks:
-  - /packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages
-  - /packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages
-  - /packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images
-  - /packages/using-github-packages-with-your-projects-ecosystem/using-github-packages-with-github-actions
+featuredLinks:
+  gettingStarted:
+    - /packages/publishing-and-managing-packages/about-github-packages
+    - /packages/getting-started-with-github-container-registry/about-github-container-registry
+    - /packages/getting-started-with-github-container-registry
+    - /packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images
+    - /packages/publishing-and-managing-packages/publishing-a-package
+    - /packages/publishing-and-managing-packages/installing-a-package
+  popular:
+    - /packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages
+    - /packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages
+    - /packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images
+    - /packages/using-github-packages-with-your-projects-ecosystem/using-github-packages-with-github-actions
 redirect_from:
   - /github/managing-packages-with-github-packages
   - /categories/managing-packages-with-github-package-registry

diff --git a/includes/article.html b/includes/article.html
@@ -63,7 +63,7 @@ <h3 id="in-this-article" class="f5 mb-2"><a class="link-gray-dark" href="#in-thi
       </div>
     </div>
     <div id="article-contents" class="article-grid-body">
-      {% if gettingStartedLinks and popularLinks %}
+      {% if featuredLinks.gettingStarted and featuredLinks.popular %}
       {% include featured-links %}
       {% endif %}
       {{ renderedPage }}

diff --git a/includes/featured-links.html b/includes/featured-links.html
@@ -7,7 +7,7 @@
         <h3 class="f5 text-normal text-mono underline-dashed color-gray-5">{% data ui.toc.getting_started %}</h3>
       </div>
 
-      {% for link in gettingStartedLinks %}
+      {% for link in featuredLinks.gettingStarted %}
         {% include featured-link %}
       {% endfor %}
     </div>
@@ -18,7 +18,7 @@ <h3 class="f5 text-normal text-mono underline-dashed color-gray-5">{% data ui.to
         <h3 class="f5 text-normal text-mono underline-dashed color-gray-5">{% data ui.toc.popular_articles %}</h3>
       </div>
 
-      {% for link in popularLinks %}
+      {% for link in featuredLinks.popular %}
         {% include featured-link %}
       {% endfor %}
     </div>

diff --git a/lib/frontmatter.js b/lib/frontmatter.js
@@ -52,15 +52,6 @@ const schema = {
     redirect_from: {
       type: ['array', 'string']
     },
-    gettingStartedLinks: {
-      type: 'array'
-    },
-    popularLinks: {
-      type: 'array'
-    },
-    guideLinks: {
-      type: 'array'
-    },
     allowTitleToDifferFromFilename: {
       type: 'boolean'
     },
@@ -70,6 +61,16 @@ const schema = {
         quickstart: { type: 'string' },
         learn: { type: 'string' }
       }
+    },
+    featuredLinks: {
+      type: 'object',
+      additionalProperties: false,
+      patternProperties: {
+        '^[a-zA-Z-_]+$': {
+          type: 'array',
+          items: { type: 'string' }
+        }
+      }
     }
   }
 }

diff --git a/lib/page.js b/lib/page.js
@@ -59,15 +59,6 @@ class Page {
     this.rawProduct = this.product
     this.rawPermissions = this.permissions
 
-    // Store raw data so we can access/modify it later in middleware
-    this.rawGettingStartedLinks = this.gettingStartedLinks
-    this.rawPopularLinks = this.popularLinks
-    this.rawGuideLinks = this.guideLinks
-    // Do not need to keep the original props
-    delete this.gettingStartedLinks
-    delete this.popularLinks
-    delete this.guideLinks
-
     // a page should only be available in versions that its parent product is available in
     const versionsParentProductIsNotAvailableIn = getApplicableVersions(this.versions, this.fullPath)
       // only the homepage will not have this.parentProduct

diff --git a/middleware/featured-links.js b/middleware/featured-links.js
@@ -8,9 +8,12 @@ module.exports = async (req, res, next) => {
 
   if (!(req.context.page.relativePath.endsWith('index.md') || req.context.page.layout === 'product-landing')) return next()
 
-  req.context.gettingStartedLinks = await getLinkData(req.context.page.rawGettingStartedLinks, req.context)
-  req.context.popularLinks = await getLinkData(req.context.page.rawPopularLinks, req.context)
-  req.context.guideLinks = await getLinkData(req.context.page.rawGuideLinks, req.context)
+  if (!req.context.page.featuredLinks) return next()
+
+  req.context.featuredLinks = {}
+  for (const key in req.context.page.featuredLinks) {
+    req.context.featuredLinks[key] = await getLinkData(req.context.page.featuredLinks[key], req.context)
+  }
 
   return next()
 }

diff --git a/tests/content/featured-links.js b/tests/content/featured-links.js
@@ -3,7 +3,7 @@ const enterpriseServerReleases = require('../../lib/enterprise-server-releases')
 const japaneseCharacters = require('japanese-characters')
 const nonEnterpriseDefaultVersion = require('../../lib/non-enterprise-default-version')
 
-describe('gettingStartedLinks and popularLinks', () => {
+describe('featuredLinks', () => {
   jest.setTimeout(3 * 60 * 1000)
 
   describe('rendering', () => {
@@ -55,7 +55,7 @@ describe('gettingStartedLinks and popularLinks', () => {
 
   describe('context.page object', () => {
     test('returns modified array of links', async () => {
-      const gettingStartedLinks = await getJSON('/en?json=gettingStartedLinks')
+      const gettingStartedLinks = await getJSON('/en?json=featuredLinks.gettingStarted')
       const expectedFirstLink = {
         href: `/en/${nonEnterpriseDefaultVersion}/github/getting-started-with-github/set-up-git`,
         title: 'Set up Git'
@@ -66,7 +66,7 @@ describe('gettingStartedLinks and popularLinks', () => {
     })
 
     test('returns raw array of links on the page object', async () => {
-      const rawGettingStartedLinks = await getJSON('/en?json=page.rawGettingStartedLinks')
+      const rawGettingStartedLinks = await getJSON('/en?json=page.featuredLinks.gettingStarted')
       expect(rawGettingStartedLinks[0]).toEqual('/github/getting-started-with-github/set-up-git')
     })
   })

diff --git a/translations/de-DE/content/actions/index.md b/translations/de-DE/content/actions/index.md
@@ -2,15 +2,16 @@
 title: Dokumentation zu GitHub Actions
 shortTitle: GitHub Actions
 intro: 'Mit {% data variables.product.prodname_actions %} kannst Du Deine Softwareentwicklungs-Workflows direkt in Ihrem Repository automatisieren, anpassen und ausführen. Du kannst Actions entdecken, erstellen und weitergeben, um beliebige Aufträge (einschließlich CI/CD) auszuführen. Du kannst auch Actions in einem vollständig angepassten Workflow kombinieren.'
-gettingStartedLinks:
-  - /actions/quickstart
-  - /actions/learn-github-actions
-guideLinks:
-  - /actions/managing-workflow-runs
-  - /actions/hosting-your-own-runners
-popularLinks:
-  - /actions/reference/workflow-syntax-for-github-actions
-  - /actions/reference/events-that-trigger-workflows
+featuredLinks:
+  gettingStarted:
+    - /actions/quickstart
+    - /actions/learn-github-actions
+  guide:
+    - /actions/managing-workflow-runs
+    - /actions/hosting-your-own-runners
+  popular:
+    - /actions/reference/workflow-syntax-for-github-actions
+    - /actions/reference/events-that-trigger-workflows
 redirect_from:
   - /articles/automating-your-workflow-with-github-actions/
   - /articles/customizing-your-project-with-github-actions/
@@ -39,7 +40,7 @@ versions:
       <h3 class="f5 text-normal text-mono underline-dashed color-gray-5">{% data ui.toc.getting_started %}</h3>
     </div>
     <ul class="list-style-none">
-      {% for link in gettingStartedLinks %}
+      {% for link in featuredLinks.gettingStarted %}
         <li>{% include featured-link %}</li>
       {% endfor %}
     </ul>
@@ -50,7 +51,7 @@ versions:
       <h3 class="f5 text-normal text-mono underline-dashed color-gray-5">{% data ui.toc.popular_articles %}</h3>
     </div>
     <ul class="list-style-none">
-      {% for link in popularLinks %}
+      {% for link in featuredLinks.popular %}
         <li>{% include featured-link %}</li>
       {% endfor %}
     </ul>
@@ -61,7 +62,7 @@ versions:
       <h3 class="f5 text-normal text-mono underline-dashed color-gray-5">Manage workflows</h3>
     </div>
     <ul class="list-style-none">
-      {% for link in guideLinks %}
+      {% for link in featuredLinks.guide %}
         <li>{% include featured-link %}</li>
       {% endfor %}
     </ul>

diff --git a/translations/de-DE/content/index.md b/translations/de-DE/content/index.md
@@ -1,16 +1,17 @@
 ---
 title: '{% data variables.product.product_name %}{% if currentVersion == "free-pro-team@latest" %}.com{% endif %} Help Documentation'
-gettingStartedLinks:
-  - /github/getting-started-with-github/set-up-git
-  - /github/authenticating-to-github/connecting-to-github-with-ssh
-  - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github
-  - /github/writing-on-github/basic-writing-and-formatting-syntax
-popularLinks:
-  - /github/collaborating-with-issues-and-pull-requests/about-pull-requests
-  - /github/authenticating-to-github
-  - /github/importing-your-projects-to-github/adding-an-existing-project-to-github-using-the-command-line
-  - /github/using-git/managing-remote-repositories
-  - /github/working-with-github-pages
+featuredLinks:
+  gettingStarted:
+    - /github/getting-started-with-github/set-up-git
+    - /github/authenticating-to-github/connecting-to-github-with-ssh
+    - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github
+    - /github/writing-on-github/basic-writing-and-formatting-syntax
+  popular:
+    - /github/collaborating-with-issues-and-pull-requests/about-pull-requests
+    - /github/authenticating-to-github
+    - /github/importing-your-projects-to-github/adding-an-existing-project-to-github-using-the-command-line
+    - /github/using-git/managing-remote-repositories
+    - /github/working-with-github-pages
 versions: '*'
 ---
 
diff --git a/translations/de-DE/content/insights/index.md b/translations/de-DE/content/insights/index.md
@@ -2,14 +2,15 @@
 title: GitHub Insights Documentation
 shortTitle: GitHub Insights
 intro: 'Understand and improve your software delivery process through data with {% data variables.product.prodname_insights %}. You can view customized reports based on data from {% data variables.product.prodname_enterprise %}.'
-gettingStartedLinks:
-  - /insights/installing-and-configuring-github-insights/about-github-insights
-  - /insights/installing-and-configuring-github-insights/system-overview-for-github-insights
-  - /insights/installing-and-configuring-github-insights/installing-github-insights
-  - /insights/exploring-your-usage-of-github-enterprise/viewing-key-metrics-and-reports
-popularLinks:
-  - /insights/installing-and-configuring-github-insights/about-data-in-github-insights
-  - /insights/exploring-your-usage-of-github-enterprise/metrics-available-with-github-insights
+featuredLinks:
+  gettingStarted:
+    - /insights/installing-and-configuring-github-insights/about-github-insights
+    - /insights/installing-and-configuring-github-insights/system-overview-for-github-insights
+    - /insights/installing-and-configuring-github-insights/installing-github-insights
+    - /insights/exploring-your-usage-of-github-enterprise/viewing-key-metrics-and-reports
+  popular:
+    - /insights/installing-and-configuring-github-insights/about-data-in-github-insights
+    - /insights/exploring-your-usage-of-github-enterprise/metrics-available-with-github-insights
 redirect_from:
   - /github/installing-and-configuring-github-insights
 versions: