Merge pull request #17310 from github/remove-fpt-helper

Add helper function that removes free-pro-team from URLs

Author: sarahs

content/README.md

@@ -24,6 +24,7 @@ See the [contributing docs](/CONTRIBUTING.md) for general information about work
   - [Escaping single quotes](#escaping-single-quotes)
 - [Autogenerated mini TOCs](#autogenerated-mini-tocs)
 - [Versioning](#versioning)
+  - [Free-pro-team vs. GitHub.com versioning](#free-pro-team-vs.-github.com-versioning)
 - [Filenames](#filenames)
 - [Whitespace control](#whitespace-control)
 - [Links and image paths](#links-and-image-paths)
@@ -213,6 +214,12 @@ A content file can have **two** types of versioning:
 * Liquid statements in content (**optional**)
     * Conditionally render content depending on the current version being viewed. See [contributing/liquid-helpers](../contributing/liquid-helpers.md) for more info. Note Liquid conditionals can also appear in `data` and `include` files.
 
+### Free-pro-team vs. GitHub.com versioning
+
+As of early 2021, the `free-pro-team@latest` version is **only** supported in content files (in both frontmatter and Liquid versioning) and throughout the docs site backend. It is **not** user facing. A helper function called `lib/remove-fpt-from-path.js` removes the version from URLs. Users now select `GitHub.com` in the Article Versions dropdown instead of `Free, Pro, Team`.
+
+The convenience function allows us to continue supporting a consistent versioning structure under-the-hood while not displaying plan information to users that may be potentially confusing.
+
 ## Filenames
 
 When adding a new article, make sure the filename is a [kebab-cased](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) version of the title you use in the article's [`title`](#title) frontmatter. This can get tricky when a title has punctuation (such as "GitHub's Billing Plans"). A test will flag any discrepancies between title and filename. To override this requirement for a given article, you can add [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename) frontmatter.
@@ -224,7 +231,7 @@ When using Liquid conditionals in lists or tables, you can use [whitespace contr
 Just add a hyphen on either the left, right, or both sides to indicate that there should be no newline on that side. For example, this statement removes a newline on the left side:
 
 ```
-{%- if page.version == 'dotcom' %}
+{%- if currentVersion == 'free-pro-team@latest' %}
 ```
 
 These characters are especially important in [index pages](#index-pages) comprised of list items.
@@ -238,9 +245,9 @@ For example, if you include the following link in a content file:
 ```
 /github/writing-on-github/creating-a-saved-reply
 ```
-When viewed on GitHub.com docs, the link gets rendered with the language code and version:
+When viewed on GitHub.com docs, the link gets rendered with the language code:
 ```
-/en/free-pro-team@latest/github/writing-on-github/creating-a-saved-reply
+/en/github/writing-on-github/creating-a-saved-reply
 ```
 and when viewed on GitHub Enterprise Server docs, the version is included as well:
 ```

contributing/development.md

@@ -48,7 +48,7 @@ For more detailed instructions, please see this [VS Code recipe](https://github.
 
 While running the local server, you can visit [localhost:4000/dev-toc](http://localhost:4000/dev-toc) to view a top-level TOC of all the content in the site. This page is not available on https://docs.github.com. It was created for internal GitHub writers' use.
 
-At the `/dev-toc` path, you'll see a list of available versions. Click a version, and a list of products will appear. Note that the TOC content is versioned. If you are viewing `free-pro-team@latest` and you click the `Enterprise Admin` product, it will be empty, because there isn't any Admin content available on that version.
+At the `/dev-toc` path, you'll see a list of available versions. Click a version, and a list of products will appear. Note that the TOC content is versioned. If you are viewing the `GitHub.com` version and you click the `Enterprise Admin` product, it will be empty, because there isn't any Admin content available on that version.
 
 ## Site structure
 

contributing/permalinks.md

@@ -4,18 +4,16 @@ Because the site is dynamic, it does not build HTML files for each different ver
 
 For example, an article that is available in currently supported versions will have permalink URLs like the following:
 
-* `/en/free-pro-team@latest/github/getting-started-with-github/set-up-git`
+* `/en/github/getting-started-with-github/set-up-git`
 * `/en/enterprise-server@2.22/github/getting-started-with-github/set-up-git`
 * `/en/enterprise-server@2.21/github/getting-started-with-github/set-up-git`
 * `/en/enterprise-server@2.20/github/getting-started-with-github/set-up-git`
 * `/en/enterprise-server@2.19/github/getting-started-with-github/set-up-git`
 
 An article that is not available in Enterprise will have just one permalink:
 
-* `/en/free-pro-team@latest/github/getting-started-with-github/set-up-git`
+* `/en/github/getting-started-with-github/set-up-git`
 
 **If you are a content contributor:** You don't need to worry about supported versions when adding a link to a document. Following the examples above, if you want to reference an article you can just use its relative location:
 
-* `/github/getting-started-with-github/set-up-git`
-
-*(Please note that using a hard-coded link or supported version will result in an error when your submitted PR is automatically tested)*
+* `/github/getting-started-with-github/set-up-git`

lib/all-products.js

@@ -7,6 +7,7 @@ const yaml = require('js-yaml')
 const contentDir = path.join(process.cwd(), 'content')
 const frontmatter = require('@github-docs/frontmatter')
 const getApplicableVersions = require('./get-applicable-versions')
+const removeFPTFromPath = require('./remove-fpt-from-path')
 
 // the product order is determined by data/products.yml
 const productsFile = path.join(process.cwd(), 'data/products.yml')
@@ -46,7 +47,7 @@ sortedProductIds.forEach(productId => {
   const toc = slash(path.join(dir, 'index.md'))
   const { data } = frontmatter(fs.readFileSync(toc, 'utf8'))
   const applicableVersions = getApplicableVersions(data.versions, toc)
-  const href = slash(path.join('/', applicableVersions[0], productId))
+  const href = removeFPTFromPath(slash(path.join('/', applicableVersions[0], productId)))
 
   internalProducts[productId] = {
     id: productId,

lib/all-versions.js

@@ -7,9 +7,10 @@ const versionDelimiter = '@'
 const latestNonNumberedRelease = 'latest'
 
 const plans = [
-  {
+  { // free-pro-team is **not** a user-facing version and is stripped from URLs.
+    // See lib/remove-fpt-from-path.js for details.
     plan: 'free-pro-team',
-    planTitle: 'Free, Pro, and Team',
+    planTitle: 'GitHub.com',
     releases: [latestNonNumberedRelease],
     latestRelease: latestNonNumberedRelease,
     nonEnterpriseDefault: true, // permanent way to refer to this plan if the name changes

lib/get-link-data.js

@@ -1,6 +1,7 @@
 const path = require('path')
 const findPage = require('./find-page')
 const nonEnterpriseDefaultVersion = require('./non-enterprise-default-version')
+const removeFPTFromPath = require('./remove-fpt-from-path')
 
 // rawLinks is an array of paths: [ '/foo' ]
 // we need to convert it to an array of localized objects: [ { href: '/en/foo', title: 'Foo', intro: 'Description here' } ]
@@ -12,7 +13,7 @@ module.exports = async (rawLinks, context, additionalProperties = []) => {
   for (const link of rawLinks) {
     const linkPath = link.href || link
     const version = context.currentVersion === 'homepage' ? nonEnterpriseDefaultVersion : context.currentVersion
-    const href = path.join('/', context.currentLanguage, version, linkPath)
+    const href = removeFPTFromPath(path.join('/', context.currentLanguage, version, linkPath))
 
     const linkedPage = findPage(href, context.pages, context.redirects)
     if (!linkedPage) continue

lib/path-utils.js

@@ -76,9 +76,13 @@ function getProductStringFromPath (href) {
 
   if (href === '/') return 'homepage'
 
-  return allProducts[href.split('/')[2]]
-    ? href.split('/')[2]
-    : href.split('/')[1]
+  const pathParts = href.split('/')
+
+  if (pathParts.includes('early-access')) return 'early-access'
+
+  return allProducts[pathParts[2]]
+    ? pathParts[2]
+    : pathParts[1]
 }
 
 // Return the corresponding object for the product segment in a path

lib/permalink.js

@@ -3,6 +3,8 @@ const path = require('path')
 const patterns = require('./patterns')
 const getApplicableVersions = require('./get-applicable-versions')
 const allVersions = require('./all-versions')
+const nonEnterpriseDefaultVersion = require('./non-enterprise-default-version')
+const removeFPTFromPath = require('./remove-fpt-from-path')
 
 class Permalink {
   constructor (languageCode, pageVersion, relativePath, title) {
@@ -13,7 +15,7 @@ class Permalink {
 
     const permalinkSuffix = this.constructor.relativePathToSuffix(relativePath)
 
-    this.href = path.join('/', languageCode, pageVersion, permalinkSuffix)
+    this.href = removeFPTFromPath(path.join('/', languageCode, pageVersion, permalinkSuffix))
       .replace(patterns.trailingSlash, '$1')
 
     this.pageVersionTitle = allVersions[pageVersion].versionTitle
@@ -26,9 +28,12 @@ class Permalink {
     assert(languageCode, 'languageCode is required')
 
     const applicableVersions = getApplicableVersions(frontmatterVersions, path.join(languageCode, relativePath))
-    const permalinks = applicableVersions.map(pageVersion => {
-      return new Permalink(languageCode, pageVersion, relativePath, title)
-    })
+    const permalinks = applicableVersions
+      // skip the Dotcom homepage here because a special homepage permalink is added below
+      .filter(pageVersion => !(pageVersion === nonEnterpriseDefaultVersion && relativePath === 'index.md'))
+      .map(pageVersion => {
+        return new Permalink(languageCode, pageVersion, relativePath, title)
+      })
 
     // special permalink for homepage
     if (relativePath === 'index.md') {

lib/redirects/get-old-paths-from-permalink.js

@@ -1,5 +1,5 @@
-const { latest, lastReleaseWithLegacyFormat } = require('../enterprise-server-releases')
-const { getPathWithoutLanguage, getPathWithLanguage } = require('../path-utils')
+const { latest, deprecated, lastReleaseWithLegacyFormat } = require('../enterprise-server-releases')
+const { getPathWithoutLanguage, getPathWithLanguage, getVersionStringFromPath } = require('../path-utils')
 const patterns = require('../patterns')
 const versionSatisfiesRange = require('../version-satisfies-range')
 const currentlySupportedVersions = Object.keys(require('../all-versions'))
@@ -11,6 +11,15 @@ const nonEnterpriseDefaultVersion = require('../non-enterprise-default-version')
 module.exports = function getOldPathsFromPath (currentPath, languageCode, currentVersion) {
   const oldPaths = new Set()
 
+  const versionFromPath = getVersionStringFromPath(currentPath)
+
+  // This only applies to Dotcom paths, so no need to determine whether the version is deprecated
+  // create old path /free-pro-team@latest/github from new path /github (or from a frontmatter `redirect_from` path like /articles)
+  if (versionFromPath === 'homepage' || !(currentlySupportedVersions.includes(versionFromPath) || deprecated.includes(versionFromPath)) || (versionFromPath === nonEnterpriseDefaultVersion && !currentPath.includes(nonEnterpriseDefaultVersion))) {
+    oldPaths.add(currentPath
+      .replace(`/${languageCode}`, `/${languageCode}/${nonEnterpriseDefaultVersion}`))
+  }
+
   // ------ BEGIN LEGACY VERSION FORMAT REPLACEMENTS ------//
   // These remain relevant to handle legacy-formatted frontmatter redirects
   // and archived versions paths.
@@ -57,14 +66,6 @@ module.exports = function getOldPathsFromPath (currentPath, languageCode, curren
   // ------ BEGIN MODERN VERSION FORMAT REPLACEMENTS ------//
   if (currentlySupportedVersions.includes(currentVersion) || versionSatisfiesRange(currentVersion, `>${lastReleaseWithLegacyFormat}`)) {
     (new Set(oldPaths)).forEach(oldPath => {
-      // create old path /github from new path /free-pro-team@latest/github
-      oldPaths.add(oldPath
-        .replace(`/${nonEnterpriseDefaultVersion}`, ''))
-
-      // create old path /free-pro-team/github from new path /free-pro-team@latest/github
-      oldPaths.add(oldPath
-        .replace('@latest', ''))
-
       // create old path /enterprise/<version> from new path /enterprise-server@<version>
       oldPaths.add(oldPath
         .replace(/\/enterprise-server@(\d)/, '/enterprise/$1'))

lib/redirects/permalinks.js

@@ -4,6 +4,7 @@ const supportedVersions = new Set(Object.keys(require('../all-versions')))
 const getOldPathsFromPermalink = require('./get-old-paths-from-permalink')
 const { getVersionStringFromPath } = require('../path-utils')
 const { getNewVersionedPath } = require('../old-versions-utils')
+const removeFPTFromPath = require('../remove-fpt-from-path')
 
 module.exports = function generateRedirectsForPermalinks (permalinks, redirectFrontmatter) {
   // account for Array or String frontmatter entries
@@ -37,7 +38,7 @@ module.exports = function generateRedirectsForPermalinks (permalinks, redirectFr
       // get the old path for the current permalink version
       let versionedFrontmatterOldPath = path.join('/', permalink.languageCode, getNewVersionedPath(frontmatterOldPath))
       const versionFromPath = getVersionStringFromPath(versionedFrontmatterOldPath)
-      versionedFrontmatterOldPath = versionedFrontmatterOldPath.replace(versionFromPath, permalink.pageVersion)
+      versionedFrontmatterOldPath = removeFPTFromPath(versionedFrontmatterOldPath.replace(versionFromPath, permalink.pageVersion))
 
       // add it to the redirects object
       redirects[versionedFrontmatterOldPath] = permalink.href

lib/remove-fpt-from-path.js

@@ -0,0 +1,9 @@
+const slash = require('slash')
+const nonEnterpriseDefaultVersion = require('./non-enterprise-default-version')
+
+// This is a convenience function to remove free-pro-team@latest from all
+// **user-facing** aspects of the site (particularly URLs) while continuing to support
+// free-pro-team@latest as a version both in the codebase and in content/data files.
+module.exports = function removeFPTFromPath (path) {
+  return slash(path.replace(`/${nonEnterpriseDefaultVersion}`, ''))
+}

lib/rewrite-local-links.js

@@ -9,6 +9,7 @@ const nonEnterpriseDefaultVersion = require('./non-enterprise-default-version')
 const allVersions = require('./all-versions')
 const supportedVersions = Object.keys(allVersions)
 const supportedPlans = Object.values(allVersions).map(v => v.plan)
+const removeFPTFromPath = require('./remove-fpt-from-path')
 
 // Content authors write links like `/some/article/path`, but they need to be
 // rewritten on the fly to match the current language and page version
@@ -79,7 +80,7 @@ function getNewHref (link, languageCode, version) {
     // ------ END ONE-OFF OVERRIDES ------//
 
     // update the version in the link
-    newHref = newHref.replace(versionFromHref, version)
+    newHref = removeFPTFromPath(newHref.replace(versionFromHref, version))
   }
 
   newHref = newHref.replace(patterns.trailingSlash, '$1')

lib/site-tree.js

@@ -6,6 +6,7 @@ const allVersions = Object.keys(require('./all-versions'))
 const { getPathWithoutVersion } = require('./path-utils')
 const getApplicableVersions = require('./get-applicable-versions')
 const findPage = require('./find-page')
+const removeFPTFromPath = require('./remove-fpt-from-path')
 
 // This module builds a localized tree of every page on the site
 // It includes single-source pages that have different variants
@@ -46,7 +47,7 @@ module.exports = async function buildSiteTree (pageMap, site, redirects) {
         if (!getApplicableVersions(page.versions).includes(version)) return
 
         // item.hrefs have a default version via lib/all-products, so update to the current version
-        const versionedProductHref = path.join('/', languageCode, version, getPathWithoutVersion(item.href))
+        const versionedProductHref = removeFPTFromPath(path.join('/', languageCode, version, getPathWithoutVersion(item.href)))
 
         product.categories = buildCategoriesTree(page.tocItems, versionedProductHref, pageMap, redirects, version)
 

middleware/breadcrumbs.js

@@ -1,5 +1,7 @@
 const path = require('path')
 const { getPathWithoutLanguage } = require('../lib/path-utils')
+const nonEnterpriseDefaultVersion = require('../lib/non-enterprise-default-version')
+const removeFPTFromPath = require('../lib/remove-fpt-from-path')
 
 module.exports = async (req, res, next) => {
   if (!req.context.page) return next()
@@ -24,19 +26,22 @@ module.exports = async (req, res, next) => {
   }
 
   req.context.breadcrumbs.product = {
-    href: path.posix.join('/', req.context.currentLanguage, req.context.currentVersion, productPath),
+    href: removeFPTFromPath(path.posix.join('/', req.context.currentLanguage, req.context.currentVersion, productPath)),
     title: product.title
   }
 
-  // drop the version segment so pathParts now starts with /product
-  pathParts.shift()
+  // if this is not FPT, drop the version segment so pathParts now starts with /product
+  // if this is FPT, there is no version segment so pathParts already starts with /product
+  if (req.context.currentVersion !== nonEnterpriseDefaultVersion) {
+    pathParts.shift()
+  }
 
   if (!pathParts[1]) return next()
 
   // get category path
   // e.g., `getting-started-with-github` in /free-pro-team@latest/github/getting-started-with-github
   // or /enterprise-server@2.21/github/getting-started-with-github
-  const categoryPath = path.posix.join('/', req.context.currentLanguage, req.context.currentVersion, productPath, pathParts[1])
+  const categoryPath = removeFPTFromPath(path.posix.join('/', req.context.currentLanguage, req.context.currentVersion, productPath, pathParts[1]))
 
   const category = product.categories[categoryPath]
 

middleware/contextualizers/early-access-links.js

@@ -7,17 +7,14 @@ module.exports = function earlyAccessContext (req, res, next) {
 
   // Get a list of all hidden pages per version
   const earlyAccessPageLinks = uniq(Object.values(req.context.pages)
-    .filter(page => page.hidden)
-    // Do not include early access landing page
-    .filter(page => page.relativePath !== 'early-access/index.md')
-    // Create Markdown links
-    .map(page => {
-      return page.permalinks.map(permalink => `- [${permalink.title}](${permalink.href})`)
-    })
+    .filter(page => page.hidden && page.relativePath.startsWith('early-access') && page.relativePath !== 'early-access/index.md')
+    .map(page => page.permalinks)
     .flat())
     // Get links for the current version
-    .filter(link => link.includes(req.context.currentVersion))
+    .filter(permalink => req.context.currentVersion === permalink.pageVersion)
     .sort()
+    // Create Markdown links
+    .map(permalink => `- [${permalink.title}](${permalink.href})`)
 
   // Add to the rendering context
   // This is only used in the separate EA repo on local development

middleware/contextualizers/rest.js

@@ -1,17 +1,18 @@
 const path = require('path')
 const rest = require('../../lib/rest')
+const removeFPTFromPath = require('../../lib/remove-fpt-from-path')
 
 module.exports = async function (req, res, next) {
   req.context.rest = rest
 
   // link to include in `Works with GitHub Apps` notes
   // e.g. /ja/rest/reference/apps or /en/enterprise/2.20/user/rest/reference/apps
-  req.context.restGitHubAppsLink = path.join(
+  req.context.restGitHubAppsLink = removeFPTFromPath(path.join(
     '/',
     req.context.currentLanguage,
     req.context.currentVersion,
     '/developers/apps'
-  )
+  ))
 
   // ignore requests to non-REST reference paths
   if (!req.path.includes('rest/reference')) return next()