feat(docs): show the GitHub video in a video container above the Introduction to Git page

A video route sharing id 5 with the markdown route is composed into the same
page, and the markdown route's hierarchyPage puts the video first. The docs
smoke now requires route ids to be unique within each route type.

Author: Vidigal-code

README.md

@@ -520,12 +520,22 @@ in with a configured provider. Route `id=11` has no `authorization`, so the **Vi
 its video container are always visible. Videos are played only by the video container; markdown pages
 do not embed them.
 
+A video route that shares its `id` with a markdown route is shown on the same page. The *Introduction
+to Git* page (`id=5`) uses this to show the test video in a video container **above** its markdown:
+the version config has a `routes-video` entry with `"id": 5` (no menu entry of its own) and the
+markdown route sets a page order that puts the video first:
+
+```json
+{ "id": 5, "hierarchyPage": { "video": 0, "md": 1, "source-viewer": 2, "html": 3, "audio": 4 } }
+```
+
 Test video (GitHub channel, *A brief introduction to Git for beginners*):
 
 [![A brief introduction to Git for beginners | GitHub](https://img.youtube.com/vi/r8jQ9hVA2qs/hqdefault.jpg)](https://www.youtube.com/watch?v=r8jQ9hVA2qs)
 
 - Watch on YouTube: https://www.youtube.com/watch?v=r8jQ9hVA2qs
 - Video route: https://vidigal-code.github.io/git-page-docs/Vidigal-code/git-page-docs/v/0.0.7/?lang=en&menu=en&id=11
+- Introduction to Git page (video above the markdown): https://vidigal-code.github.io/git-page-docs/Vidigal-code/git-page-docs/v/0.0.7/?lang=en&menu=en&id=5
 - Fullscreen: https://vidigal-code.github.io/git-page-docs/Vidigal-code/git-page-docs/v/0.0.7/?videofull=en&slug=r8jQ9hVA2qs
 
 Route definition in `gitpagedocs/docs/versions/0.0.7/config.json`:

cli/builders/route-builders.mjs

@@ -24,6 +24,7 @@ export function buildMdRoute(versionId, routeId, pathByLang, titles, description
     RouteguideBrandContainerTop = false,
     audio,
     authorization,
+    hierarchyPage,
   } = options;
   const out = {
     id: routeId,
@@ -54,6 +55,7 @@ export function buildMdRoute(versionId, routeId, pathByLang, titles, description
   if (container !== undefined) out.container = container;
   if (audio !== undefined) out.audio = audio;
   if (authorization !== undefined) out.authorization = authorization;
+  if (hierarchyPage !== undefined) out.hierarchyPage = hierarchyPage;
   return out;
 }
 

cli/builders/version-config-builder.mjs

@@ -20,6 +20,7 @@ import {
   AUDIO_META_ID12,
   SOURCE_VIEWER_META,
   DEFAULT_HIERARCHY,
+  VIDEO_FIRST_HIERARCHY,
 } from "../data/route-metas.mjs";
 import { buildAudioRoute, buildMdRoute, buildSourceViewerRoute, buildVideoRoute } from "./route-builders.mjs";
 import { resolveSourceViewerPath } from "./project-links.mjs";
@@ -39,6 +40,10 @@ const VIDEO_ROUTE_AUTHORIZATION = {
 const PUBLIC_VIDEO_ROUTE_ID = 11;
 /** Video routes follow the six markdown pages and the source viewer (ids 8-11). */
 const VIDEO_ROUTE_ID_OFFSET = 7;
+/** Markdown page that also shows the public video, in a video container above its text. */
+const VIDEO_PAGE_ROUTE_ID = 5;
+/** VIDEO_IDS / VIDEO_METAS entry of the public video (GitHub's introduction to Git). */
+const PUBLIC_VIDEO_INDEX = PUBLIC_VIDEO_ROUTE_ID - VIDEO_ROUTE_ID_OFFSET;
 
 const ROUTE_METAS = {
   1: ROUTE_META_ID1,
@@ -62,6 +67,7 @@ function buildVersionMdRoutes(versionId, includeDemoAuthorization) {
     };
     const routeOptions = {
       ...(id === 2 ? { audio: PAGE2_AUDIO } : {}),
+      ...(id === VIDEO_PAGE_ROUTE_ID ? { hierarchyPage: VIDEO_FIRST_HIERARCHY } : {}),
       ...(includeDemoAuthorization && id === 3
         ? { authorization: { requiredRoles: [MAINTAINER_ROLE] } }
         : {}),
@@ -80,8 +86,20 @@ function buildVersionMdRoutes(versionId, includeDemoAuthorization) {
   });
 }
 
+/** Video container shown on the markdown page VIDEO_PAGE_ROUTE_ID (no menu entry of its own). */
+function buildPageVideoRoute(versionId) {
+  return buildVideoRoute(
+    versionId,
+    VIDEO_PAGE_ROUTE_ID,
+    "youtube",
+    VIDEO_IDS[PUBLIC_VIDEO_INDEX - 1],
+    VIDEO_METAS[PUBLIC_VIDEO_INDEX].title,
+    VIDEO_METAS[PUBLIC_VIDEO_INDEX].description,
+  );
+}
+
 function buildVersionVideoRoutes(versionId, includeDemoAuthorization) {
-  return [1, 2, 3, 4].map((id) => {
+  const menuVideoRoutes = [1, 2, 3, 4].map((id) => {
     const routeId = id + VIDEO_ROUTE_ID_OFFSET;
     const isGuarded = includeDemoAuthorization && routeId !== PUBLIC_VIDEO_ROUTE_ID;
     return buildVideoRoute(
@@ -94,6 +112,7 @@ function buildVersionVideoRoutes(versionId, includeDemoAuthorization) {
       isGuarded ? { authorization: VIDEO_ROUTE_AUTHORIZATION } : {},
     );
   });
+  return [buildPageVideoRoute(versionId), ...menuVideoRoutes];
 }
 
 function buildVersionAudioRoutes(versionId) {

cli/data/route-metas.mjs

@@ -1,6 +1,8 @@
 /** Route and video metadata for doc versions */
 
 export const DEFAULT_HIERARCHY = { md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 };
+/** Page order that puts the video container above the markdown. */
+export const VIDEO_FIRST_HIERARCHY = { video: 0, md: 1, "source-viewer": 2, html: 3, audio: 4 };
 
 export const ROUTE_META_ID1 = {
   titles: { pt: "Primeiros passos", en: "Getting Started", es: "Primeros pasos" },

cli/tests/core/builders.test.ts

@@ -288,14 +288,27 @@ describe("buildVersionConfig", () => {
     const config = buildVersionConfig(versionId);
 
     const video = config["routes-video"];
-    expect(video.map((route) => route.id)).toEqual([8, 9, 10, 11]);
-    expect(video[0].video).toEqual({
+    expect(video.map((route) => route.id)).toEqual([5, 8, 9, 10, 11]);
+    const videoRoute = (id: number) => {
+      const found = video.find((route) => route.id === id);
+      if (!found) throw new Error(`missing video route ${id}`);
+      return found;
+    };
+    expect(videoRoute(8).video).toEqual({
       videoType: { pt: "youtube", en: "youtube", es: "youtube" },
       pathVideo: { pt: VIDEO_IDS[0], en: VIDEO_IDS[0], es: VIDEO_IDS[0] },
     });
-    expect(video[0].authorization).toEqual({ requireExternalAuth: true, allowedProviders: EXTERNAL_PROVIDERS });
+    expect(videoRoute(8).authorization).toEqual({ requireExternalAuth: true, allowedProviders: EXTERNAL_PROVIDERS });
     expect(video.filter((route) => route.authorization).map((route) => route.id)).toEqual([8, 9, 10]);
-    expect(video[3].authorization).toBeUndefined();
+    expect(videoRoute(11).authorization).toBeUndefined();
+
+    // Page 5 (Introduction to Git) shows the public video in a video container above its markdown.
+    expect(videoRoute(5).video?.pathVideo.en).toBe(VIDEO_IDS[3]);
+    expect(videoRoute(5).authorization).toBeUndefined();
+    const introductionMd = config["routes-md"].find((route) => route.id === 5);
+    const pageOrder = introductionMd?.hierarchyPage as Record<string, number> | undefined;
+    expect(pageOrder?.video).toBeLessThan(pageOrder?.md ?? 0);
+    expect(config["menus-header-video"].map((item) => item.id)).toEqual([8, 9, 10, 11]);
 
     const [audio] = config["routes-audio"];
     expect(audio.id).toBe(AUDIO_META_ID12.id);

gitpagedocs/docs/versions/0.0.7/config.json

@@ -181,7 +181,14 @@
       "RouteguideBrand": true,
       "RouteGuideSpeciFicbrand": [],
       "RouteguideBrandPosition": "center",
-      "RouteguideBrandContainerTop": false
+      "RouteguideBrandContainerTop": false,
+      "hierarchyPage": {
+        "video": 0,
+        "md": 1,
+        "source-viewer": 2,
+        "html": 3,
+        "audio": 4
+      }
     },
     {
       "id": 6,
@@ -244,6 +251,32 @@
   ],
   "routes-html": [],
   "routes-video": [
+    {
+      "id": 5,
+      "title": {
+        "pt": "A brief introduction to Git for beginners | GitHub",
+        "en": "A brief introduction to Git for beginners | GitHub",
+        "es": "A brief introduction to Git for beginners | GitHub"
+      },
+      "description": {
+        "pt": "Introdução ao Git para iniciantes.",
+        "en": "A brief introduction to Git for beginners.",
+        "es": "Una breve introducción a Git para principiantes."
+      },
+      "fullscreenEnabled": true,
+      "video": {
+        "videoType": {
+          "pt": "youtube",
+          "en": "youtube",
+          "es": "youtube"
+        },
+        "pathVideo": {
+          "pt": "r8jQ9hVA2qs",
+          "en": "r8jQ9hVA2qs",
+          "es": "r8jQ9hVA2qs"
+        }
+      }
+    },
     {
       "id": 8,
       "title": {

tools/gitpagedocs/docs/versions/0.0.7/config.json

@@ -181,7 +181,14 @@
       "RouteguideBrand": true,
       "RouteGuideSpeciFicbrand": [],
       "RouteguideBrandPosition": "center",
-      "RouteguideBrandContainerTop": false
+      "RouteguideBrandContainerTop": false,
+      "hierarchyPage": {
+        "video": 0,
+        "md": 1,
+        "source-viewer": 2,
+        "html": 3,
+        "audio": 4
+      }
     },
     {
       "id": 6,
@@ -244,6 +251,32 @@
   ],
   "routes-html": [],
   "routes-video": [
+    {
+      "id": 5,
+      "title": {
+        "pt": "A brief introduction to Git for beginners | GitHub",
+        "en": "A brief introduction to Git for beginners | GitHub",
+        "es": "A brief introduction to Git for beginners | GitHub"
+      },
+      "description": {
+        "pt": "Introdução ao Git para iniciantes.",
+        "en": "A brief introduction to Git for beginners.",
+        "es": "Una breve introducción a Git para principiantes."
+      },
+      "fullscreenEnabled": true,
+      "video": {
+        "videoType": {
+          "pt": "youtube",
+          "en": "youtube",
+          "es": "youtube"
+        },
+        "pathVideo": {
+          "pt": "r8jQ9hVA2qs",
+          "en": "r8jQ9hVA2qs",
+          "es": "r8jQ9hVA2qs"
+        }
+      }
+    },
     {
       "id": 8,
       "title": {

tools/smoke/baseline.snapshot.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-09-28T20:57:42.003Z",
+  "generatedAt": "2026-09-28T21:13:39.022Z",
   "targets": [
     "gitpagedocs/config.json",
     "gitpagedocs/langs/en.json",
@@ -12,6 +12,6 @@
     "gitpagedocs/langs/en.json": "5efaddcd0429f5f2e632850a13d923d2da2a8720292bb00d642f81357772eee1",
     "gitpagedocs/langs/pt.json": "f29cfa74721179058914edffc078beb9a5bd30a6f811aa9ef11ff9eb89212f85",
     "gitpagedocs/langs/es.json": "bfd6093ba9112be0568817b40ef2d1bc73f0c96f3c8cdb3461af421df946a0cd",
-    "gitpagedocs/docs/versions/0.0.7/config.json": "3b2f776c2f496cc73b033dbde359c4bed06fec530b7f1baadb020bf18a4f8abb"
+    "gitpagedocs/docs/versions/0.0.7/config.json": "0b9475a60b36e3a73b7c79d0043c1032941cb0fa306e071511db9c4cc3180b21"
   }
 }

tools/smoke/docs-selftest.ts

@@ -29,13 +29,19 @@ function asArray(value: unknown): Array<Record<string, unknown>> {
   return Array.isArray(value) ? value as Array<Record<string, unknown>> : [];
 }
 
+/**
+ * Route ids across every route type. An id is unique within its type; routes of
+ * different types may share one, and the viewer composes them into one page.
+ */
 function routeIds(config: Record<string, unknown>, routeKeys: string[]): Set<number> {
   const ids = new Set<number>();
   for (const key of routeKeys) {
+    const idsOfType = new Set<number>();
     for (const route of asArray(config[key])) {
       const id = Number(route.id);
       check(`generated config route id is valid for ${key}`, Number.isFinite(id), String(route.id));
-      check(`generated config route id ${id} is unique`, !ids.has(id), key);
+      check(`generated config route id ${id} is unique`, !idsOfType.has(id), key);
+      idsOfType.add(id);
       ids.add(id);
     }
   }