Rename 'map topics' to 'subcategories' (#56202)

heiskr · web-flow · commit a7a57b22c2f5 · 2025-06-25T15:29:49.000Z
diff --git a/src/content-linter/lib/helpers/schema-utils.js b/src/content-linter/lib/helpers/schema-utils.js
@@ -33,7 +33,7 @@ export function formatAjvErrors(errors = []) {
     // The two most common errors are required and additionalProperties.
     // This catches any other with a generic detail that uses the AJV wording.
     error.detail = `Frontmatter ${errorObj.message}.`
-    error.context = Object.values(errorObj.params.join(''))
+    error.context = Object.values(errorObj.params).join('')
     error.errorProperty = error.context
     error.searchProperty = error.errorProperty
     return error
diff --git a/src/content-linter/lib/linting-rules/early-access-references.js b/src/content-linter/lib/linting-rules/early-access-references.js
@@ -62,7 +62,9 @@ export const frontmatterEarlyAccessReferences = {
 
     // The landing page must link to early-access content so the
     // children property doesn't need to be checked in that case.
-    if (filepath === 'content/index.md') delete fm.children
+    // Also exclude fixture index files.
+    if (filepath === 'content/index.md' || filepath.includes('fixtures/content/index.md'))
+      delete fm.children
 
     // Convert updated frontmatter back to a string
     // to search for 'early-access'.'
diff --git a/src/content-linter/tests/category-pages.ts b/src/content-linter/tests/category-pages.ts
@@ -139,8 +139,8 @@ describe.skip('category pages', () => {
                 const articleContents = await fs.promises.readFile(articlePath, 'utf8')
                 const data = getFrontmatterData(articleContents)
 
-                // Do not include map topics in list of published articles
-                if (data.mapTopic || data.hidden) return null
+                // Do not include subcategories in list of published articles
+                if (data.subcategory || data.hidden) return null
 
                 // ".../content/github/{category}/{article}.md" => "/{article}"
                 return `/${path.relative(categoryDir, articlePath).replace(/\.md$/, '')}`
@@ -161,8 +161,8 @@ describe.skip('category pages', () => {
                 const articleContents = await fs.promises.readFile(articlePath, 'utf8')
                 const data = getFrontmatterData(articleContents)
 
-                // Do not include map topics nor hidden pages in list of available articles
-                if (data.mapTopic || data.hidden) return null
+                // Do not include subcategories nor hidden pages in list of available articles
+                if (data.subcategory || data.hidden) return null
 
                 // ".../content/github/{category}/{article}.md" => "/{article}"
                 return `/${path.relative(categoryDir, articlePath).replace(/\.md$/, '')}`
@@ -195,7 +195,7 @@ describe.skip('category pages', () => {
           expect(unexpectedArticles.length, errorMessage).toBe(0)
         })
 
-        test('contains only articles and map topics with versions that are also available in the parent category', () => {
+        test('contains only articles and subcategories with versions that are also available in the parent category', () => {
           Object.entries(articleVersions).forEach(([articleName, articleVersions]) => {
             const unexpectedVersions = difference(articleVersions, categoryVersions)
             const errorMessage = `${articleName} has versions that are not available in parent category`
diff --git a/src/content-render/scripts/reconcile-category-dirs-with-ids.js b/src/content-render/scripts/reconcile-category-dirs-with-ids.js
@@ -23,13 +23,13 @@ const slugger = new GithubSlugger()
 
 const contentDir = path.join(ROOT, 'content')
 
-const INCLUDE_MAP_TOPICS = Boolean(JSON.parse(process.env.INCLUDE_MAP_TOPICS || 'false'))
+const INCLUDE_SUBCATEGORIES = Boolean(JSON.parse(process.env.INCLUDE_SUBCATEGORIES || 'false'))
 
 main()
 
 async function main() {
   const englishCategoryIndices = getEnglishCategoryIndices().filter((name) => {
-    return INCLUDE_MAP_TOPICS || name.split(path.sep).length < 5
+    return INCLUDE_SUBCATEGORIES || name.split(path.sep).length < 5
   })
 
   const shouldRename = []
diff --git a/src/content-render/tests/render-changed-and-deleted-files.js b/src/content-render/tests/render-changed-and-deleted-files.js
@@ -127,7 +127,7 @@ describe('deleted-content', () => {
         ? `The deleted file ${file} did not set up a redirect when deleted.`
         : ''
     // Certain articles that are deleted and moved under a directory with the same article name
-    // should just route to the map topic page instead of redirecting (docs content team confirmed).
+    // should just route to the subcategory page instead of redirecting (docs content team confirmed).
     // So, in this scenario, we'd get a 200 status code.
     expect(res.statusCode === 301 || res.statusCode === 200, error).toBe(true)
   })
diff --git a/src/dev-toc/layout.html b/src/dev-toc/layout.html
@@ -39,11 +39,11 @@ <h2 class="mt-3 mb-3"><abbr>TOC</abbr> for {{ allVersions[currentVersion].versio
   <li style="margin: 3px 0 0 30px;">
     <a title="{{ categoryPage.page.documentType }}" href="{{ docsRoot }}{{ categoryPage.href }}">{{ categoryPage.renderedFullTitle }}</a>
       <ul>
-        {% for maptopicPage in categoryPage.childPages %}
+        {% for subcategoryPage in categoryPage.childPages %}
             <li style="margin: 3px 0 0 30px;">
-              <a title="{{ maptopicPage.page.documentType }}" href="{{ docsRoot }}{{ maptopicPage.href }}">{{ maptopicPage.renderedFullTitle }}</a>
+              <a title="{{ subcategoryPage.page.documentType }}" href="{{ docsRoot }}{{ subcategoryPage.href }}">{{ subcategoryPage.renderedFullTitle }}</a>
               <ul>
-                {% for articlePage in maptopicPage.childPages %}
+                {% for articlePage in subcategoryPage.childPages %}
                 <li style="margin: 3px 0 0 30px;">
                   <a title="{{ articlePage.page.documentType }}" href="{{ docsRoot }}{{ articlePage.href }}">{{ articlePage.renderedFullTitle }}</a>
                 </li>
diff --git a/src/events/lib/get-document-type.ts b/src/events/lib/get-document-type.ts
@@ -1,7 +1,7 @@
 /**
  * Document types used by the system
  */
-type DocumentType = 'homepage' | 'product' | 'category' | 'mapTopic' | 'article' | 'early-access'
+type DocumentType = 'homepage' | 'product' | 'category' | 'subcategory' | 'article' | 'early-access'
 
 /**
  * This function derives the document type from the *relative path* segment length,
@@ -20,17 +20,17 @@ export default function getDocumentType(relativePath: string): DocumentType {
   // Early Access has an extra tree segment, so it has a different number of segments.
   const isEarlyAccess = relativePath.startsWith('early-access')
 
-  const publicDocs: DocumentType[] = ['homepage', 'product', 'category', 'mapTopic']
+  const publicDocs: DocumentType[] = ['homepage', 'product', 'category', 'subcategory']
 
   const earlyAccessDocs: DocumentType[] = [
     'homepage',
     'early-access',
     'product',
     'category',
-    'mapTopic',
+    'subcategory',
   ]
 
-  // Anything beyond the largest depth is assumed to be a mapTopic
+  // Anything beyond the largest depth is assumed to be a subcategory
   return isEarlyAccess
     ? earlyAccessDocs[Math.min(segmentLength, earlyAccessDocs.length) - 1]
     : publicDocs[Math.min(segmentLength, publicDocs.length) - 1]
diff --git a/src/events/lib/schema.ts b/src/events/lib/schema.ts
@@ -89,7 +89,7 @@ const context = {
     page_document_type: {
       type: 'string',
       description: 'The generic page document type based on URL path.',
-      enum: ['homepage', 'early-access', 'product', 'category', 'mapTopic', 'article'], // get-document-type.js
+      enum: ['homepage', 'early-access', 'product', 'category', 'subcategory', 'article'], // get-document-type.js
     },
     page_type: {
       type: 'string',
diff --git a/src/fixtures/fixtures/article-with-mislocalized-frontmatter.md b/src/fixtures/fixtures/article-with-mislocalized-frontmatter.md
@@ -1,7 +1,7 @@
 ---
 title: GitHub 上でプロジェクトを探索する
 intro: ''
-mapTopic: verdadero
+subcategory: true
 versions:
   free-pro-team: '*'
   enterprise-server: '*'
diff --git a/src/fixtures/fixtures/content/actions/category/index.md b/src/fixtures/fixtures/content/actions/category/index.md
@@ -8,5 +8,5 @@ versions:
   ghes: '*'
   ghec: '*'
 children:
-  - /map-topic
+  - /subcategory
 ---
diff --git a/src/fixtures/fixtures/content/actions/category/subcategory/article.md b/src/fixtures/fixtures/content/actions/category/subcategory/article.md
diff --git a/src/fixtures/fixtures/content/actions/category/subcategory/index.md b/src/fixtures/fixtures/content/actions/category/subcategory/index.md
@@ -1,6 +1,6 @@
 ---
-title: Map Topic page about Actions
-shortTitle: Map & Topic
+title: Subcategory page about Actions
+shortTitle: Subcategory
 intro: "Here's the intro for {% data variables.product.prodname_actions %}."
 versions:
   fpt: '*'
diff --git a/src/fixtures/fixtures/content/index.md b/src/fixtures/fixtures/content/index.md
@@ -10,7 +10,7 @@ featuredLinks:
     - /get-started/foo/bar
     - /pages
     - '{% ifversion ghec %}/get-started/versioning/only-ghec{% endif %}'
-    - /actions/category/map-topic
+    - /actions/category/subcategory
 redirect_from:
   - /olden-days
 versions:
diff --git a/src/fixtures/tests/breadcrumbs.ts b/src/fixtures/tests/breadcrumbs.ts
@@ -26,7 +26,7 @@ describe('breadcrumbs', () => {
     expect(links.text()).toBe('Bar')
   })
 
-  test('article pages have breadcrumbs in article with product, category, maptopic, and article and last breadcrumb is not viewable', async () => {
+  test('article pages have breadcrumbs in article with product, category, subcategory, and article and last breadcrumb is not viewable', async () => {
     const $ = await getDOM('/get-started/start-your-journey/hello-world')
     const links = $('[data-testid=breadcrumbs-in-article] a')
     expect(links.length).toBe(3)
diff --git a/src/fixtures/tests/categories-and-subcategory.js b/src/fixtures/tests/categories-and-subcategory.js
@@ -2,8 +2,8 @@ import { describe, expect, test } from 'vitest'
 
 import { getDOM, head } from '#src/tests/helpers/e2etest.js'
 
-describe('map topics', () => {
-  test('get-started/start-your-journey map-topic', async () => {
+describe('subcategories', () => {
+  test('get-started/start-your-journey subcategory', async () => {
     const $ = await getDOM('/get-started/start-your-journey')
     const lead = $('[data-search=lead]').text()
     expect(lead).toMatch('Get started using HubGit to manage Git repositories')
@@ -20,8 +20,8 @@ describe('map topics', () => {
     expect(responses.every((r) => r.statusCode === 200)).toBeTruthy()
   })
 
-  test('actions/category/map-topic map-topic has its articles intro', async () => {
-    const $ = await getDOM('/actions/category/map-topic')
+  test('actions/category/subcategory subcategory has its articles intro', async () => {
+    const $ = await getDOM('/actions/category/subcategory')
     const lead = $('[data-search=lead]').text()
     expect(lead).toMatch("Here's the intro for HubGit Actions.")
 
@@ -41,7 +41,7 @@ describe('map topics', () => {
 })
 
 describe('categories', () => {
-  test('actions/category map-topic', async () => {
+  test('actions/category subcategory', async () => {
     const $ = await getDOM('/actions/category')
     const lead = $('[data-search=lead]').text()
     expect(lead).toMatch('Learn how to migrate your existing CI/CD')
diff --git a/src/fixtures/tests/internal-links.js b/src/fixtures/tests/internal-links.js
@@ -129,7 +129,7 @@ describe('link-rewriting', () => {
   })
 })
 
-describe('map-topic links', () => {
+describe('subcategory links', () => {
   test('no free-pro-team prefix', async () => {
     const $ = await getDOM('/rest/actions')
     const links = $('[data-testid="table-of-contents"] a[href]')
diff --git a/src/fixtures/tests/page-titles.js b/src/fixtures/tests/page-titles.js
@@ -21,7 +21,7 @@ describe('page titles', () => {
     )
   })
 
-  test('fpt map topic page', async () => {
+  test('fpt subcategory page', async () => {
     const $ = await getDOM('/en/get-started/start-your-journey')
     expect($('title').text()).toBe('Start your journey - GitHub Docs')
   })
diff --git a/src/fixtures/tests/playwright-a11y.spec.ts b/src/fixtures/tests/playwright-a11y.spec.ts
@@ -9,7 +9,7 @@ const pages: { [key: string]: string } = {
   homepage: '/',
   learningPath:
     '/code-security/getting-started/quickstart?learn=foo_bar&learnProduct=code-security',
-  mapAndTopic: '/actions/category/map-topic',
+  mapAndTopic: '/actions/category/subcategory',
   procedural: '/get-started/images/images-in-lists',
   productLanding: '/code-security',
   restCategory: '/rest/actions/artifacts',
diff --git a/src/fixtures/tests/playwright-rendering.spec.ts b/src/fixtures/tests/playwright-rendering.spec.ts
@@ -302,18 +302,18 @@ test.describe('tool picker', () => {
   })
 })
 
-test('navigate with side bar into article inside a map-topic inside a category', async ({
+test('navigate with side bar into article inside a subcategory inside a category', async ({
   page,
 }) => {
   // Our TreeView sidebar only shows "2 levels". If you click and expand
-  // the category, you'll be able to see the map-topic and the article
+  // the category, you'll be able to see the subcategory and the article
   // within.
   await page.goto('/actions')
-  await page.getByTestId('sidebar').getByText('Category').click()
-  await page.getByText('Map & Topic').click()
+  await page.getByTestId('sidebar').getByText('Category', { exact: true }).click()
+  await page.getByTestId('sidebar').getByText('Subcategory').click()
   await page.getByText('<article>').click()
   await expect(page.getByRole('heading', { name: 'Article title' })).toBeVisible()
-  await expect(page).toHaveURL(/actions\/category\/map-topic\/article/)
+  await expect(page).toHaveURL(/actions\/category\/subcategory\/article/)
 })
 
 test.describe('hover cards', () => {
diff --git a/src/frame/components/context/MainContext.tsx b/src/frame/components/context/MainContext.tsx
@@ -90,7 +90,7 @@ export type MainContextT = {
   breadcrumbs: {
     product: BreadcrumbT
     category?: BreadcrumbT
-    maptopic?: BreadcrumbT
+    subcategory?: BreadcrumbT
     article?: BreadcrumbT
   }
   communityRedirect: {
diff --git a/src/frame/lib/frontmatter.js b/src/frame/lib/frontmatter.js
@@ -53,7 +53,7 @@ export const schema = {
       minimum: 2,
       maximum: 4,
     },
-    mapTopic: {
+    subcategory: {
       type: 'boolean',
     },
     // allow hidden articles under `early-access`
@@ -65,7 +65,7 @@ export const schema = {
       type: 'boolean',
     },
     // specify whether an Early Access product should have a table of contents
-    // (EA categories and map topics have them by default, but products don't)
+    // (EA categories and subcategories have them by default, but products don't)
     earlyAccessToc: {
       type: 'boolean',
     },
diff --git a/src/frame/lib/get-toc-items.js b/src/frame/lib/get-toc-items.js
@@ -6,7 +6,7 @@ const productTOCs = Object.values(productMap)
 const linkString = /{% [^}]*?link.*? \/(.*?) ?%}/m
 const linksArray = new RegExp(linkString.source, 'gm')
 
-// return an array of objects like { type: 'category|maptopic|article', href: 'path' }
+// return an array of objects like { type: 'category|subcategory|article', href: 'path' }
 export default function getTocItems(page) {
   // only process product and category tocs
   if (!page.relativePath.endsWith('index.md')) return
@@ -27,11 +27,11 @@ export default function getTocItems(page) {
     const tocItem = {}
 
     // a product's toc items are always categories
-    // whereas a category's toc items can be either maptopics or articles
+    // whereas a category's toc items can be either subcategories or articles
     tocItem.type = productTOCs.includes(page.relativePath)
       ? 'category'
       : item.includes('topic_')
-        ? 'maptopic'
+        ? 'subcategory'
         : 'article'
 
     tocItem.href = item.match(linkString)[1]
diff --git a/src/frame/middleware/context/current-product-tree.ts b/src/frame/middleware/context/current-product-tree.ts
@@ -43,7 +43,7 @@ export default async function currentProductTree(
 
   // First make a slim tree of just the 'href', 'title', 'shortTitle'
   // 'documentType' and 'childPages' (which is recursive).
-  // This gets used for map topic and category pages.
+  // This gets used for subcategory and category pages.
   req.context.currentProductTreeTitles = await getCurrentProductTreeTitles(
     req.context.currentProductTree,
     req.context,
diff --git a/src/frame/middleware/context/generic-toc.ts b/src/frame/middleware/context/generic-toc.ts
@@ -4,7 +4,7 @@ import type { ExtendedRequest, Context, Tree, ToC } from '@/types'
 import findPageInSiteTree from '@/frame/lib/find-page-in-site-tree.js'
 
 // This module adds either flatTocItems or nestedTocItems to the context object for
-// product, category, and map topic TOCs that don't have other layouts specified.
+// product, category, and subcategory TOCs that don't have other layouts specified.
 // They are rendered by includes/generic-toc-flat.html or includes/generic-toc-nested.html.
 export default async function genericToc(req: ExtendedRequest, res: Response, next: NextFunction) {
   if (!req.context) throw new Error('request not contextualized')
@@ -14,7 +14,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
     req.context.currentLayoutName !== 'category-landing'
   )
     return next()
-  // This middleware can only run on product, category, and map topics.
+  // This middleware can only run on product, category, and subcategories.
   if (
     req.context.page.documentType === 'homepage' ||
     req.context.page.documentType === 'article' ||
@@ -29,7 +29,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
   const tocTypes: Record<string, string> = {
     product: 'flat',
     category: 'nested',
-    mapTopic: 'flat',
+    subcategory: 'flat',
   }
 
   // Frontmatter can optionally be set on an Early Access product to show hidden child items.
@@ -47,32 +47,32 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
     req.pagePath,
   )
 
-  let fauxMapTopic = false
+  let fauxSubcategory = false
   if (req.context.page.documentType === 'category' && req.context.page.autogenerated !== 'rest') {
     // But does *have* children?
     const hasGrandchildren = (treePage.childPages || []).some((child) => child.children)
-    fauxMapTopic = !hasGrandchildren
+    fauxSubcategory = !hasGrandchildren
   }
 
   // Find the current TOC type based on the current document type.
   const currentTocType = earlyAccessToc
     ? 'nested'
-    : fauxMapTopic
+    : fauxSubcategory
       ? 'flat'
       : tocTypes[req.context.page.documentType]
 
   // By default, only include hidden child items on a TOC page if it's an Early Access category or
-  // map topic page, not a product or 'articles' fake category page (e.g., /early-access/github/articles).
+  // subcategory page, not a product or 'articles' fake category page (e.g., /early-access/github/articles).
   // This is because we don't want entire EA product TOCs to be publicly browseable, but anything at the category
   // or below level is fair game because that content is scoped to specific features.
-  const isCategoryOrMapTopic =
-    req.context.page.documentType === 'category' || req.context.page.documentType === 'mapTopic'
+  const isCategoryOrSubcategory =
+    req.context.page.documentType === 'category' || req.context.page.documentType === 'subcategory'
   if (!req.context.currentPath) throw new Error('currentPath not in context')
   const isEarlyAccess = req.context.currentPath.includes('/early-access/')
   const isArticlesCategory = req.context.currentPath.endsWith('/articles')
 
   const includeHidden =
-    earlyAccessToc || (isCategoryOrMapTopic && isEarlyAccess && !isArticlesCategory)
+    earlyAccessToc || (isCategoryOrSubcategory && isEarlyAccess && !isArticlesCategory)
 
   // Conditionally run getTocItems() recursively.
   let isRecursive
@@ -90,7 +90,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
     })
   }
 
-  // Get an array of child map topics and their child articles and add it to the context object.
+  // Get an array of child subcategories and their child articles and add it to the context object.
   if (currentTocType === 'nested' || isOneOffProductToc) {
     isRecursive = !isOneOffProductToc
     renderIntros = false
diff --git a/src/frame/tests/page.js b/src/frame/tests/page.js
@@ -63,7 +63,7 @@ describe('Page class', () => {
       expect(articleWithFM.showMiniToc).toBe(false)
     })
 
-    // products, categories, and map topics have index.md pages
+    // products, categories, and subcategories have index.md pages
     test('is undefined by default on index.md pages', () => {
       expect(tocPage.showMiniToc).toBeUndefined()
     })
diff --git a/src/frame/tests/server.js b/src/frame/tests/server.js
diff --git a/src/search/lib/get-elasticsearch-results/general-search.ts b/src/search/lib/get-elasticsearch-results/general-search.ts
diff --git a/src/search/scripts/scrape/lib/parse-page-sections-into-records.ts b/src/search/scripts/scrape/lib/parse-page-sections-into-records.ts
diff --git a/src/search/tests/fixtures/page-without-body.html b/src/search/tests/fixtures/page-without-body.html
diff --git a/src/search/tests/fixtures/page-without-sections.html b/src/search/tests/fixtures/page-without-sections.html
diff --git a/src/search/tests/parse-page-sections-into-records.ts b/src/search/tests/parse-page-sections-into-records.ts
diff --git a/src/types.ts b/src/types.ts
