jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-20 10:28:40 -05:00
Code Issues Projects Releases Wiki Activity

add some clarifying comments

Browse Source
This commit is contained in:
Sarah Schneider
2020-12-17 10:50:52 -05:00
parent 5da9d74e33
commit 75deecd386
1 changed files with 27 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
lib/path-utils.js
View File

@@ -7,41 +7,46 @@ const allVersions = require('./all-versions')
const supportedVersions = new Set(Object.keys(allVersions))
const { getNewVersionedPath } = require('./old-versions-utils')
// construct appropriate versioned path for any given HREF
// This function constructs an appropriate versioned path for any given HREF.
// NOTE: this gets called by findPage and various other functions, and
// has to return a proper versioned link given a wide variety of incoming
// modern or legacy-formatted links, so it is somewhat overloaded. At some point
// this could probably be broken up into separate functions to handle different incoming
// paths. But it is currently optimized to handle lots of edge cases.
function getVersionedPathWithoutLanguage (href, version) {
// start clean without language code or trailing slash
// Start clean without language code or trailing slash
href = getPathWithoutLanguage(href.replace(patterns.trailingSlash, '$1'))
// if this is an old versioned path that includes a deprecated version, do not change!
// If this is an old versioned path that includes a deprecated version, do not change!
// example: /enterprise/11.10.340/admin/articles/upgrading-to-the-latest-release
const oldEnterpriseVersionNumber = href.match(patterns.getEnterpriseVersionNumber)
if (oldEnterpriseVersionNumber && deprecated.includes(oldEnterpriseVersionNumber[1])) {
return href
}
// try to derive the current version from the path
// Try to derive the current version from the path
// example: enterprise-server@2.22 or free-pro-team@latest
let versionFromPath = getVersionStringFromPath(href)
// if a real version was found, add it to the path so we can go through the rest of the checks
// If a supported version was found, add it to the path so we can go through the rest of the checks
if (supportedVersions.has(versionFromPath)) {
href = href.replace(href.split('/')[1], versionFromPath)
}
// if the version found is NOT a currently supported version...
// If a currently supported version was NOT found...
let productObjectFromPath
if (!supportedVersions.has(versionFromPath)) {
// first check if the first segment is instead a current product;
// First check if the segment is instead a current product;
// example: /admin/foo or /desktop/foo
productObjectFromPath = allProducts[versionFromPath]
// if so, add the first supported version for that product to the href
// If so, add the first supported version for that product to the href
// (this is just to get a path with all the expected segments; the version will be updated later if needed)
if (productObjectFromPath) {
href = path.join('/', productObjectFromPath.versions[0], href)
versionFromPath = productObjectFromPath.versions[0]
} else {
// otherwise, this may be an old path that should be converted to new path;
// Otherwise, this may be an old path that should be converted to new path;
// OLD: /enterprise/2.22/admin/installation OR /enterprise/admin/installation
// NEW: /enterprise-server@2.22/admin/installation
href = getNewVersionedPath(href)
@@ -49,34 +54,34 @@ function getVersionedPathWithoutLanguage (href, version) {
}
}
// if not previously found, derive the product object from the path (e.g., github or admin)
// If not previously found, derive the product object from the path (e.g., github or admin)
if (!productObjectFromPath) {
productObjectFromPath = getProductObjectFromPath(href)
}
// if the product's versions don't include the specified version, nothing to change!
// If the product's versions don't include the specified version, nothing to change!
if (productObjectFromPath && !productObjectFromPath.versions.includes(version)) {
return slash(href)
}
// update the version
// Update the version and return the path
return slash(href.replace(versionFromPath, version))
}
// add language code
// Add language code to a versioned path
function getVersionedPathWithLanguage (href, version, languageCode) {
return getPathWithLanguage(getVersionedPathWithoutLanguage(href, version), languageCode)
}
// add the language to the given HREF
// /en/articles/foo -> /articles/foo
// Add the language to the given HREF
// /articles/foo -> /en/articles/foo
function getPathWithLanguage (href, languageCode) {
return slash(path.posix.join('/', languageCode, getPathWithoutLanguage(href)))
.replace(patterns.trailingSlash, '$1')
}
// remove the language from the given HREF
// /articles/foo -> /en/articles/foo
// Remove the language from the given HREF
// /en/articles/foo -> /articles/foo
function getPathWithoutLanguage (href) {
return slash(href.replace(patterns.hasLanguageCode, '/'))
}
@@ -90,30 +95,30 @@ function getPathWithoutVersion (href) {
function getVersionStringFromPath (href) {
href = getPathWithoutLanguage(href)
// return immediately if this is a link to the homepage
// Return immediately if this is a link to the homepage
if (href === '/') {
return 'homepage'
}
// check if the first segment is a supported version
// Check if the first segment is a supported version
const versionFromPath = href.split('/')[1]
if (supportedVersions.has(versionFromPath)) {
return versionFromPath
}
// if the version segment is the latest enterprise-server release, return the latest release
// If the version segment is the latest enterprise-server release, return the latest release
if (versionFromPath === 'enterprise-server@latest') {
return `enterprise-server@${latest}`
}
// if it's just a plan with no @release (e.g., `enterprise-server`), return the latest release
// If it's just a plan with no @release (e.g., `enterprise-server`), return the latest release
const planObject = Object.values(allVersions).find(v => v.plan === versionFromPath)
if (planObject) {
return allVersions[planObject.latestVersion].version
}
// otherwise, return the first segment as-is, which may not be a proper version
// Otherwise, return the first segment as-is, which may not be a real supported version,
// but additional checks are done on this segment in getVersionedPathWithoutLanguage
return versionFromPath
}