show journey nav and support journey article branching text frontmatter (#58848)

Author: rsese

content/README.md

@@ -259,7 +259,9 @@ includeGuides:
   - `id` (required): Unique identifier for the journey. The id only needs to be unique for journeys within a single journey landing page.
   - `title` (required): Display title for the journey (supports Liquid variables)
   - `description` (optional): Description of the journey (supports Liquid variables)
-  - `guides` (required): Array of article paths that make up this journey
+  - `guides` (required): Array of guide objects that make up this journey. Each guide object has:
+    - `href` (required): Path to the article
+    - `alternativeNextStep` (optional): Custom text to guide users to alternative paths in the journey. Supports Liquid variables and `[AUTOTITLE]`.
 - Only applicable when used with `layout: journey-landing`.
 - Optional.
 
@@ -271,15 +273,16 @@ journeyTracks:
     title: 'Getting started with {% data variables.product.prodname_actions %}'
     description: 'Learn the basics of GitHub Actions.'
     guides:
-      - '/actions/quickstart'
-      - '/actions/learn-github-actions'
-      - '/actions/using-workflows'
+      - href: '/actions/quickstart'
+      - href: '/actions/learn-github-actions'
+        alternativeNextStep: 'Want to skip ahead? See [AUTOTITLE](/actions/using-workflows).'
+      - href: '/actions/using-workflows'
   - id: 'advanced'
     title: 'Advanced {% data variables.product.prodname_actions %}'
     description: 'Dive deeper into advanced features.'
     guides:
-      - '/actions/using-workflows/workflow-syntax-for-github-actions'
-      - '/actions/deployment/deploying-with-github-actions'
+      - href: '/actions/using-workflows/workflow-syntax-for-github-actions'
+      - href: '/actions/deployment/deploying-with-github-actions'
 ```
 
 ### `type`

content/contributing/writing-for-github-docs/using-yaml-frontmatter.md

@@ -257,7 +257,9 @@ includeGuides:
   * `id` (required): Unique identifier for the journey. The id only needs to be unique for journeys within a single journey landing page.
   * `title` (required): Display title for the journey (supports Liquid variables)
   * `description` (optional): Description of the journey (supports Liquid variables)
-  * `guides` (required): Array of article paths that make up this journey
+  * `guides` (required): Array of guide objects that make up this journey. Each guide object has:
+    * `href` (required): Path to the article
+    * `alternativeNextStep` (optional): Custom text to guide users to alternative paths in the journey. Supports Liquid variables and `[AUTOTITLE]`.
 * Only applicable when used with `layout: journey-landing`.
 * Optional.
 
@@ -269,15 +271,16 @@ journeyTracks:
     title: 'Getting started with {% data variables.product.prodname_actions %}'
     description: 'Learn the basics of GitHub Actions.'
     guides:
-      - '/actions/quickstart'
-      - '/actions/learn-github-actions'
-      - '/actions/using-workflows'
+      - href: '/actions/quickstart'
+      - href: '/actions/learn-github-actions'
+        alternativeNextStep: 'Want to skip ahead? See [AUTOTITLE](/actions/using-workflows).'
+      - href: '/actions/using-workflows'
   - id: 'advanced'
     title: 'Advanced {% data variables.product.prodname_actions %}'
     description: 'Dive deeper into advanced features.'
     guides:
-      - '/actions/using-workflows/workflow-syntax-for-github-actions'
-      - '/actions/deployment/deploying-with-github-actions'
+      - href: '/actions/using-workflows/workflow-syntax-for-github-actions'
+      - href: '/actions/deployment/deploying-with-github-actions'
 ```
 
 ### `type`

content/enterprise-onboarding/index.md

@@ -16,56 +16,56 @@ journeyTracks:
     title: 'Getting started with your enterprise'
     description: 'Master the fundamentals of {% data variables.product.prodname_ghe_cloud %} and get started with a trial.'
     guides:
-      - '/enterprise-onboarding/getting-started-with-your-enterprise/choose-an-enterprise-type'
-      - '/enterprise-onboarding/getting-started-with-your-enterprise/setting-up-a-trial-of-github-enterprise'
-      - '/enterprise-onboarding/getting-started-with-your-enterprise/adding-users-to-your-enterprise'
-      - '/enterprise-onboarding/getting-started-with-your-enterprise/about-enterprise-billing'
-      - '/enterprise-onboarding/getting-started-with-your-enterprise/about-migrating-to-github-enterprise-cloud'
+      - href: '/enterprise-onboarding/getting-started-with-your-enterprise/choose-an-enterprise-type'
+      - href: '/enterprise-onboarding/getting-started-with-your-enterprise/setting-up-a-trial-of-github-enterprise'
+      - href: '/enterprise-onboarding/getting-started-with-your-enterprise/adding-users-to-your-enterprise'
+      - href: '/enterprise-onboarding/getting-started-with-your-enterprise/about-enterprise-billing'
+      - href: '/enterprise-onboarding/getting-started-with-your-enterprise/about-migrating-to-github-enterprise-cloud'
   - id: 'setting_up_organizations_and_teams'
     title: 'Setting up organizations and teams in your enterprise'
     description: 'Organize work effectively and ensure people have the access they need to resources and administrative settings.'
     guides:
-      - '/enterprise-onboarding/setting-up-organizations-and-teams/best-practices'
-      - '/enterprise-onboarding/setting-up-organizations-and-teams/setting-up-an-organization'
-      - '/enterprise-onboarding/setting-up-organizations-and-teams/about-roles-in-an-enterprise'
-      - '/enterprise-onboarding/setting-up-organizations-and-teams/identify-role-requirements'
-      - '/enterprise-onboarding/setting-up-organizations-and-teams/creating-custom-roles'
-      - '/enterprise-onboarding/setting-up-organizations-and-teams/about-teams-in-an-enterprise'
-      - '/enterprise-onboarding/setting-up-organizations-and-teams/creating-teams'
-      - '/enterprise-onboarding/setting-up-organizations-and-teams/assigning-roles-to-teams-and-users'
-      - '/enterprise-onboarding/setting-up-organizations-and-teams/use-innersource'
+      - href: '/enterprise-onboarding/setting-up-organizations-and-teams/best-practices'
+      - href: '/enterprise-onboarding/setting-up-organizations-and-teams/setting-up-an-organization'
+      - href: '/enterprise-onboarding/setting-up-organizations-and-teams/about-roles-in-an-enterprise'
+      - href: '/enterprise-onboarding/setting-up-organizations-and-teams/identify-role-requirements'
+      - href: '/enterprise-onboarding/setting-up-organizations-and-teams/creating-custom-roles'
+      - href: '/enterprise-onboarding/setting-up-organizations-and-teams/about-teams-in-an-enterprise'
+      - href: '/enterprise-onboarding/setting-up-organizations-and-teams/creating-teams'
+      - href: '/enterprise-onboarding/setting-up-organizations-and-teams/assigning-roles-to-teams-and-users'
+      - href: '/enterprise-onboarding/setting-up-organizations-and-teams/use-innersource'
   - id: 'support_for_your_enterprise'
     title: 'Creating a support model for your enterprise'
     description: 'Find out how to get help and choose who will be able to contact Support.'
     guides:
-      - '/enterprise-onboarding/support-for-your-enterprise/understanding-support'
-      - '/enterprise-onboarding/support-for-your-enterprise/using-the-support-portal'
-      - '/enterprise-onboarding/support-for-your-enterprise/managing-support-entitlements'
+      - href: '/enterprise-onboarding/support-for-your-enterprise/understanding-support'
+      - href: '/enterprise-onboarding/support-for-your-enterprise/using-the-support-portal'
+      - href: '/enterprise-onboarding/support-for-your-enterprise/managing-support-entitlements'
   - id: 'govern_people_and_repositories'
     title: 'Governing people and repositories'
     description: 'Implement policies, custom properties, and rulesets to govern users and repositories across your enterprise.'
     guides:
-      - '/enterprise-onboarding/govern-people-and-repositories/about-enterprise-policies'
-      - '/enterprise-onboarding/govern-people-and-repositories/create-custom-properties'
-      - '/enterprise-onboarding/govern-people-and-repositories/create-repository-policies'
-      - '/enterprise-onboarding/govern-people-and-repositories/protect-branches'
-      - '/enterprise-onboarding/govern-people-and-repositories/using-the-audit-log-for-your-enterprise'
-      - '/enterprise-onboarding/govern-people-and-repositories/about-enterprise-security'
+      - href: '/enterprise-onboarding/govern-people-and-repositories/about-enterprise-policies'
+      - href: '/enterprise-onboarding/govern-people-and-repositories/create-custom-properties'
+      - href: '/enterprise-onboarding/govern-people-and-repositories/create-repository-policies'
+      - href: '/enterprise-onboarding/govern-people-and-repositories/protect-branches'
+      - href: '/enterprise-onboarding/govern-people-and-repositories/using-the-audit-log-for-your-enterprise'
+      - href: '/enterprise-onboarding/govern-people-and-repositories/about-enterprise-security'
   - id: 'github_apps'
     title: 'Automating processes with GitHub Apps'
     description: 'Create and install apps to automate processes securely in your enterprise and organizations.'
     guides:
-      - '/enterprise-onboarding/github-apps/create-enterprise-apps'
-      - '/enterprise-onboarding/github-apps/install-enterprise-apps'
+      - href: '/enterprise-onboarding/github-apps/create-enterprise-apps'
+      - href: '/enterprise-onboarding/github-apps/install-enterprise-apps'
   - id: 'github_actions_for_your_enterprise'
     title: 'Setting up CI/CD with GitHub Actions'
     description: 'Explore {% data variables.product.prodname_actions %}, plan your rollout, and get started.'
     guides:
-      - '/enterprise-onboarding/github-actions-for-your-enterprise/about-github-actions-for-enterprises'
-      - '/enterprise-onboarding/github-actions-for-your-enterprise/actions-components'
-      - '/enterprise-onboarding/github-actions-for-your-enterprise/planning-a-rollout-of-github-actions'
-      - '/enterprise-onboarding/github-actions-for-your-enterprise/migrating-your-enterprise-to-github-actions'
-      - '/enterprise-onboarding/github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-cloud'
+      - href: '/enterprise-onboarding/github-actions-for-your-enterprise/about-github-actions-for-enterprises'
+      - href: '/enterprise-onboarding/github-actions-for-your-enterprise/actions-components'
+      - href: '/enterprise-onboarding/github-actions-for-your-enterprise/planning-a-rollout-of-github-actions'
+      - href: '/enterprise-onboarding/github-actions-for-your-enterprise/migrating-your-enterprise-to-github-actions'
+      - href: '/enterprise-onboarding/github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-cloud'
 versions:
   ghec: '*'
 topics:

content/get-started/start-your-journey/index.md

@@ -28,12 +28,12 @@ journeyTracks:
     title: 'Get started'
     description: 'Master the fundamentals of {% data variables.product.github %} and Git.'
     guides:
-      - '/get-started/start-your-journey/about-github-and-git'
-      - '/get-started/start-your-journey/creating-an-account-on-github'
-      - '/get-started/start-your-journey/hello-world'
-      - '/get-started/start-your-journey/setting-up-your-profile'
-      - '/get-started/start-your-journey/finding-inspiration-on-github'
-      - '/get-started/start-your-journey/downloading-files-from-github'
-      - '/get-started/start-your-journey/uploading-a-project-to-github'
-      - '/get-started/start-your-journey/git-and-github-learning-resources'
+      - href: '/get-started/start-your-journey/about-github-and-git'
+      - href: '/get-started/start-your-journey/creating-an-account-on-github'
+      - href: '/get-started/start-your-journey/hello-world'
+      - href: '/get-started/start-your-journey/setting-up-your-profile'
+      - href: '/get-started/start-your-journey/finding-inspiration-on-github'
+      - href: '/get-started/start-your-journey/downloading-files-from-github'
+      - href: '/get-started/start-your-journey/uploading-a-project-to-github'
+      - href: '/get-started/start-your-journey/git-and-github-learning-resources'
 ---

src/content-linter/lib/linting-rules/journey-tracks-guide-path-exists.ts

@@ -71,14 +71,19 @@ export const journeyTracksGuidePathExists = {
       const trackObj = track as Record<string, unknown>
       if (trackObj.guides && Array.isArray(trackObj.guides)) {
         for (let guideIndex = 0; guideIndex < trackObj.guides.length; guideIndex++) {
-          const guide: string = trackObj.guides[guideIndex]
-          if (typeof guide === 'string') {
-            if (!isValidGuidePath(guide, params.name)) {
+          const guideObj = trackObj.guides[guideIndex]
+
+          // Validate guide is an object with expected properties
+          if (!guideObj || typeof guideObj !== 'object') continue
+
+          // Validate href property
+          if ('href' in guideObj && typeof guideObj.href === 'string') {
+            if (!isValidGuidePath(guideObj.href, params.name)) {
               addError(
                 onError,
                 journeyTracksLineNumber,
-                `Journey track guide path does not exist: ${guide} (track ${trackIndex + 1}, guide ${guideIndex + 1})`,
-                guide,
+                `Journey track guide path does not exist: ${guideObj.href} (track ${trackIndex + 1}, guide ${guideIndex + 1})`,
+                guideObj.href,
               )
             }
           }

src/content-linter/lib/linting-rules/journey-tracks-liquid.ts

@@ -75,16 +75,38 @@ export const journeyTracksLiquid = {
 
       if (track.guides && Array.isArray(track.guides)) {
         for (let guideIndex = 0; guideIndex < track.guides.length; guideIndex++) {
-          const guide: string = track.guides[guideIndex]
-          if (typeof guide === 'string') {
+          const guideObj = track.guides[guideIndex]
+
+          // Validate guide is an object with expected properties
+          if (!guideObj || typeof guideObj !== 'object') continue
+
+          // Validate href property
+          if ('href' in guideObj && typeof guideObj.href === 'string') {
+            try {
+              liquid.parse(guideObj.href)
+            } catch (error: any) {
+              addError(
+                onError,
+                trackLineNumber,
+                `Invalid Liquid syntax in journey track guide href (track ${trackIndex + 1}, guide ${guideIndex + 1}): ${error.message}`,
+                guideObj.href,
+              )
+            }
+          }
+
+          // Validate alternativeNextStep property if present
+          if (
+            'alternativeNextStep' in guideObj &&
+            typeof guideObj.alternativeNextStep === 'string'
+          ) {
             try {
-              liquid.parse(guide)
+              liquid.parse(guideObj.alternativeNextStep)
             } catch (error: any) {
               addError(
                 onError,
                 trackLineNumber,
-                `Invalid Liquid syntax in journey track guide (track ${trackIndex + 1}, guide ${guideIndex + 1}): ${error.message}`,
-                guide,
+                `Invalid Liquid syntax in journey track guide alternativeNextStep (track ${trackIndex + 1}, guide ${guideIndex + 1}): ${error.message}`,
+                guideObj.alternativeNextStep,
               )
             }
           }

src/content-linter/tests/fixtures/journey-tracks/duplicate-ids.md

@@ -11,15 +11,15 @@ journeyTracks:
   - id: duplicate-id
     title: "First Track"
     guides:
-      - /article-one
+      - href: /article-one
   - id: unique-id
     title: "Unique Track"
     guides:
-      - /article-two
+      - href: /article-two
   - id: duplicate-id
     title: "Second Track with Same ID"
     guides:
-      - /subdir/article-three
+      - href: /subdir/article-three
 ---
 
 # Journey with Duplicate IDs

src/content-linter/tests/fixtures/journey-tracks/invalid-paths.md

@@ -11,9 +11,9 @@ journeyTracks:
   - id: track-1
     title: "Track with Invalid Guides"
     guides:
-      - /article-one
-      - /nonexistent/guide
-      - /another/invalid/path
+      - href: /article-one
+      - href: /nonexistent/guide
+      - href: /another/invalid/path
 ---
 
 # Journey with Invalid Paths

src/content-linter/tests/fixtures/journey-tracks/non-journey-layout.md

@@ -11,7 +11,7 @@ journeyTracks:
   - id: track-1
     title: "Should be ignored"
     guides:
-      - /nonexistent/path
+      - href: /nonexistent/path
 ---
 
 # Non-Journey Page

src/content-linter/tests/fixtures/journey-tracks/valid-journey.md

@@ -11,12 +11,12 @@ journeyTracks:
   - id: track-1
     title: "Getting Started Track"
     guides:
-      - /article-one
-      - /article-two
+      - href: /article-one
+      - href: /article-two
   - id: track-2
     title: "Advanced Track"
     guides:
-      - /subdir/article-three
+      - href: /subdir/article-three
 ---
 
 # Valid Journey Landing