dora-team · davidstanke · Dec 19, 2025 · Dec 19, 2025
diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md
@@ -62,6 +62,7 @@ You should focus on these areas in your code review:
      appearance.
    * Magic Numbers: Using unexplained numerical values directly in the code, making it harder to
      understand the purpose and adjust the values later.
+   * "Magic" Front Matter: Avoid creating custom front matter variables to control layout logic (like `top_header` or `hide_title`) when standard Hugo variables (like defined hierarchy or `.Title`) can achieve the same result. Standardizing on core logic makes templates easier to understand and maintain.
 
 4. Security: Identify potential vulnerabilities in data handling or input validation. Examples here
    include things like storing passwords or credentials, vulnerabilities in the way APIs are designed

diff --git a/firebase.json b/firebase.json
@@ -553,6 +553,16 @@
           "source": "/ai/capabilities-model",
           "destination": "/ai/capabilities-model/report/",
           "type": 302
+        },
+        {
+          "source": "/ai/gen-ai-report/",
+          "destination": "/ai/gen-ai-report/report/",
+          "type": 302
+        },
+        {
+          "source": "/ai/gen-ai-report",
+          "destination": "/ai/gen-ai-report/report/",
+          "type": 302
         }
       ]
     }

diff --git a/hugo/content/ai/_index.md b/hugo/content/ai/_index.md
@@ -1,6 +1,5 @@
 ---
 title: "Artificial Intelligence"
-top_header: "Artificial Intelligence"
 date: 2025-11-26
 draft: false
 ---

diff --git a/hugo/content/ai/capabilities-model/_index.md b/hugo/content/ai/capabilities-model/_index.md
@@ -0,0 +1,7 @@
+---
+title: "DORA AI Capabilities Model"
+type: "ai"
+draft: false
+---
+
+<!-- this page is only used for the title of pages in this section there is a redirect to /ai/capabilities-model/report/ in the firebase config -->
diff --git a/hugo/content/ai/capabilities-model/errata.md b/hugo/content/ai/capabilities-model/errata.md
@@ -1,19 +1,16 @@
 ---
 title: "DORA AI Capabilities Model report errata"
-top_header: "DORA AI Capabilities Model"
 date: 2025-12-08
 updated: 2025-12-08
 draft: false
 research_collection: "DORA AI Capabilities Model"
 research_collection_title: "DORA AI Capabilities Model"
 type: "ai"
+layout: "report"
 tab_order: "20"
 tab_title: "Errata"
-hide_title: true
 ---
 
-### DORA AI Capabilities Model report errata
-
 This page lists errors and corrections to the DORA AI Capabilities Model report. To track revisions, report PDFs are stamped with a version number. The initial version of the report is `v. 2025.1`.
 
 -----

diff --git a/hugo/content/ai/capabilities-model/questions.md b/hugo/content/ai/capabilities-model/questions.md
@@ -1,5 +1,5 @@
 ---
-title: "DORA AI Capabilities Model questions"
+title: "Survey Questions"
 date: 2025-11-25
 updated: 2025-11-25
 draft: false

diff --git a/hugo/content/ai/capabilities-model/report/index.md b/hugo/content/ai/capabilities-model/report/index.md
@@ -1,20 +1,17 @@
 ---
-title: "DORA AI Capabilities Model report"
-top_header: "DORA AI Capabilities Model"
+title: "Download the DORA AI Capabilities Model report"
 date: 2025-11-25
 updated: 2025-11-25
 draft: false
 type: "ai"
+layout: "report"
 tab_order: "1"
 tab_title: "AI Capabilities Model report"
 research_collection: "DORA AI Capabilities Model"
 research_collection_title: "DORA AI Capabilities Model"
-hide_title: true
 hideSiteBanner: true
 ---
 
-## Download the DORA AI Capabilities Model report
-
 <grid class="border_none mt-1">
 <item>
 

diff --git a/hugo/content/ai/gen-ai-report/_index.md b/hugo/content/ai/gen-ai-report/_index.md
@@ -1,39 +1,7 @@
 ---
 title: "Impact of Generative AI in Software Development"
-top_header: "Artificial Intelligence"
-date: 2025-03-06
+type: "ai"
 draft: false
-type: ai
-research_collection: "Impact of Generative AI in Software Development"
-tab_order: "2"
-tab_title: "Impact of Gen AI report"
-layout: single
 ---
-## Impact of Generative AI in Software Development
 
-<grid class="border_none" style="margin-top:1rem;">
-<item>
-
-<a href="dora-impact-of-generative-ai-in-software-development.pdf" target="_blank"><img src="dora-impact-of-generative-ai-in-software-development-report.png" alt="Impact of Generative AI in Software Development" style="max-width:24em;"></a>
-
-</item>
-
-<item>
-<p>
-Generative AI is rapidly reshaping the software development landscape, presenting both exciting opportunities and complex challenges.
-</p>
-
-<p>
-This report offers research-backed guidance for leaders and practitioners to effectively navigate this transformation, providing actionable insights to maximize AI's benefits while mitigating potential risks.
-</p>
-
-<p>
-Based on extensive data and developer interviews, the report moves beyond the hype to offer a nuanced perspective on AI's impact on individuals, teams, and organizations.
-</p>
-
-<p>
-
-<a href="dora-impact-of-generative-ai-in-software-development.pdf" target="_blank"><button class="secondary">Download the report</button></a>
-
-</p>
-</grid>
+<!-- this page is only used for the title of pages in this section there is a redirect to /ai/gen-ai-report/report/ in the firebase config -->
diff --git a/hugo/content/ai/gen-ai-report/errata.md b/hugo/content/ai/gen-ai-report/errata.md
@@ -1,13 +1,13 @@
 ---
-title: "DORA Research Errata"
-top_header: "Artificial Intelligence"
+title: "Impact of Generative AI in Software Development report errata"
 date: 2025-03-06
 updated: 2025-03-06
 research_collection: "Impact of Generative AI in Software Development"
 draft: false
 tab_order: "100"
 tab_title: "Errata"
 type: "ai"
+layout: "report"
 ---
 
 This page lists errors and corrections to the Impact of Generative AI in Software Development. To track revisions, report PDFs are stamped with a version number. The current version of the report is [`v.2025.2`](/ai/gen-ai-report).

diff --git a/hugo/content/ai/gen-ai-report/questions.md b/hugo/content/ai/gen-ai-report/questions.md
@@ -1,5 +1,5 @@
 ---
-title: "DORA Research Questions"
+title: "Survey Questions"
 date: 2025-03-10
 updated: 2025-03-10
 research_collection: "Impact of Generative AI in Software Development"

diff --git a/hugo/content/ai/gen-ai-report/report/index.md b/hugo/content/ai/gen-ai-report/report/index.md
@@ -0,0 +1,36 @@
+---
+title: "Download the Impact of Generative AI in Software Development"
+date: 2025-10-17
+updated: 2025-10-17
+draft: false
+layout: "report"
+type: "ai"
+tab_order: "1"
+tab_title: "Impact of Gen AI Report"
+research_collection: "Impact of Generative AI in Software Development"
+research_collection_title: "Impact of Generative AI in Software Development"
+hideSiteBanner: true
+---
+
+<grid class="border_none mt-1">
+<item>
+
+<a href="/ai/gen-ai-report/dora-impact-of-generative-ai-in-software-development.pdf" target="_blank"><img src="/ai/gen-ai-report/dora-impact-of-generative-ai-in-software-development-report.png" alt="Impact of Generative AI in Software Development" class="report-image"></a>
+
+</item>
+<item>
+<p>
+  Generative AI is rapidly reshaping the software development landscape, presenting both exciting opportunities and complex challenges.
+</p>
+<p>
+  This report offers research-backed guidance for leaders and practitioners to effectively navigate this transformation, providing actionable insights to maximize AI's benefits while mitigating potential risks.
+</p>
+<p>
+  Based on extensive data and developer interviews, the report moves beyond the hype to offer a nuanced perspective on AI's impact on individuals, teams, and organizations.
+</p>
+<div style="text-align: right;">
+<a href="/ai/gen-ai-report/dora-impact-of-generative-ai-in-software-development.pdf" target="_blank" class="button secondary">Download the report</a>
+</div>
+
+</item>
+</grid>
diff --git a/hugo/content/ai/research-insights/_index.md b/hugo/content/ai/research-insights/_index.md
@@ -1,6 +1,5 @@
 ---
-title: "AI Research Insights"
-top_header: "AI: Research insights"
+title: "AI research insights"
 updated: 2025-12-17
 date: 2025-12-07
 research_collection: "AI research insights"

diff --git a/hugo/content/ai/research-insights/adopt-gen-ai/_index.md b/hugo/content/ai/research-insights/adopt-gen-ai/_index.md
@@ -1,12 +1,11 @@
 ---
 title: "Helping developers adopt generative AI: Four practical strategies for organizations"
-top_header: "AI: Research insights"
 date: 2025-01-31
 updated: 2025-03-19
 research_collection: "AI research insights"
 research_collection_title: "Adopt Gen AI"
 draft: false
-tab_order: "4"
+tab_order: "5"
 tab_title: "Adopt Gen AI"
 authors:
     1: {name: "Daniella Villalba", url: "/research/team/#daniella-villalba-phd"}

diff --git a/hugo/content/ai/research-insights/ai-as-a-tutor/index.md b/hugo/content/ai/research-insights/ai-as-a-tutor/index.md
@@ -1,12 +1,11 @@
 ---
 title: "AI as a tutor"
-top_header: "AI: Research insights"
 date: 2025-12-12
 updated: 2025-12-17
 research_collection: "AI research insights"
 research_collection_title: "AI as a tutor"
 draft: false
-tab_order: "7"
+tab_order: "1"
 tab_title: "AI as a tutor"
 authors:
     1: {name: "Andrew Harlan", url: "https://www.linkedin.com/in/andrew-harlan-phd/"}

diff --git a/hugo/content/ai/research-insights/builder-mindset/index.md b/hugo/content/ai/research-insights/builder-mindset/index.md
@@ -1,12 +1,11 @@
 ---
 title:  "Understanding builder intent in the AI era"
-top_header: "AI: Research insights"
 date:  2025-10-17
 updated: 2025-10-17
 research_collection: "AI research insights"
 research_collection_title: "Builder mindset"
 draft: false
-tab_order: "1"
+tab_order: "2"
 tab_title: "Builder mindset"
 authors:
     1: {name: 'Abey Stenman', url: 'https://www.linkedin.com/in/abeytid/'}

diff --git a/hugo/content/ai/research-insights/concerns-beyond-accuracy-of-ai-output/index.md b/hugo/content/ai/research-insights/concerns-beyond-accuracy-of-ai-output/index.md
@@ -1,12 +1,11 @@
 ---
 title:  "Concerns beyond the accuracy of AI output"
-top_header: "AI: Research insights"
 date: 2025-06-30
 updated: 2025-07-31
 research_collection: "AI research insights"
 research_collection_title: "Concerns beyond accuracy"
 draft: false
-tab_order: "3"
+tab_order: "4"
 tab_title: "Concerns beyond accuracy"
 authors:
     1: {name: "Dr. Kevin M. Storer", url: "/research/team/#dr-kevin-m-storer"}

diff --git a/hugo/content/ai/research-insights/measurement-frameworks/index.md b/hugo/content/ai/research-insights/measurement-frameworks/index.md
@@ -1,12 +1,11 @@
 ---
 title: "Choosing measurement frameworks to fit your organizational goals"
-top_header: "AI: Research insights"
 date: 2025-08-06
 updated: 2025-08-26
 research_collection: "AI research insights"
 research_collection_title: "Measurement frameworks"
 draft: false
-tab_order: "2"
+tab_order: "3"
 tab_title: "Measurement frameworks"
 authors:
     1: {name: "Dr. Sarah D'Angelo", url: "https://www.linkedin.com/in/sarahrdangelo/"}

diff --git a/hugo/content/ai/research-insights/trust-in-ai/index.md b/hugo/content/ai/research-insights/trust-in-ai/index.md
@@ -1,12 +1,11 @@
 ---
 title: "Fostering Trust in AI"
-top_header: "AI: Research insights"
 date: 2024-09-13
 updated: 2025-03-19
 research_collection: "AI research insights"
 research_collection_title: "Trust in AI"
 draft: false
-tab_order: "6"
+tab_order: "7"
 tab_title: "Trust in AI"
 authors:
     1: {name: "Dr. Kevin M. Storer", url: "/research/team/#dr-kevin-m-storer"}

diff --git a/hugo/content/ai/research-insights/value-of-development-work/index.md b/hugo/content/ai/research-insights/value-of-development-work/index.md
@@ -1,14 +1,13 @@
 ---
 title: "How gen AI affects the value of development work"
-top_header: "AI: Research insights"
 date: 2024-12-10
 updated: 2025-03-05T00:00:00Z
 research_collection: "AI research insights"
 research_collection_title: "Value of development work"
 draft: false
 authors:
     1: {name: "Dr. Kevin M. Storer", url: "/research/team/#dr-kevin-m-storer"}
-tab_order: "5"
+tab_order: "6"
 tab_title: "Value of development work"
 headline: "How gen AI affects the value of development work"
 type: "ai"

diff --git a/hugo/themes/dora-2025/layouts/ai/overview.html b/hugo/themes/dora-2025/layouts/ai/overview.html
@@ -1,8 +1,6 @@
 {{ define "main" }} {{- partial "link_styles" "scss/ai.scss" -}}
 
-{{ if .Params.top_header }}
-<h1>{{ .Params.top_header }}</h1>
-{{ end }}
+<h1>{{ .Title }}</h1>
 {{ if .Params.research_collection }}
 {{- partial "research_archives_tabs" . -}}
 {{ end }}

diff --git a/hugo/themes/dora-2025/layouts/ai/report.html b/hugo/themes/dora-2025/layouts/ai/report.html
@@ -0,0 +1,36 @@
+{{ define "main" }} {{- partial "link_styles" "scss/ai.scss" -}}
+
+{{ if ne .Parent.Title "Artificial Intelligence" }}
+<h1>{{ .Parent.Title }}</h1>
+{{ end }}
+
+{{ if .Params.research_collection }}
+{{- partial "research_archives_tabs" . -}}
+{{ end }}
+
+<h2>{{ .Title }}</h2>
+
+{{/*
+Define the groups of people to display.
+To add a new group:
+1. Add a new dict to this slice.
+2. "key": matches the param name in the content front matter (e.g. "contributors").
+3. "label": the text to display before the names (e.g. "with contributions from").
+*/}}
+{{ $contributors := slice
+(dict "key" "authors" "label" "by")
+(dict "key" "guides" "label" "guidance from")
+}}
+{{ range $contributors }}
+{{ partial "author_list" (dict "list" (index $.Params .key) "label" .label) }}
+{{ end }}
+
+<article class="ai-content">
+  {{ .Content }}
+  {{ if .Params.updated }}
+  <div class="updated">
+    Last updated: {{ .Params.updated | time.Format ":date_long" }}
+  </div>
+  {{ end }}
+</article>
+{{ end }}
diff --git a/hugo/themes/dora-2025/layouts/ai/single.html b/hugo/themes/dora-2025/layouts/ai/single.html
@@ -1,14 +1,14 @@
 {{ define "main" }} {{- partial "link_styles" "scss/ai.scss" -}}
 
-{{ if .Params.top_header }}
-<h1>{{ .Params.top_header }}</h1>
+{{ if ne .Parent.Title "Artificial Intelligence" }}
+<h1>{{ .Parent.Title }}</h1>
 {{ end }}
+
 {{ if .Params.research_collection }}
 {{- partial "research_archives_tabs" . -}}
 {{ end }}
-{{ if and (ne .Params.top_header .Title) (not .Params.hide_title) }}
+
 <h1>{{ .Title }}</h1>
-{{ end }}
 
 {{/*
 Define the groups of people to display.

diff --git a/test/playwright/tests/ai/ai-capabilities-model-report.spec.ts b/test/playwright/tests/ai/ai-capabilities-model-report.spec.ts
@@ -7,12 +7,12 @@ test.describe("AI Capabilities Model report page", () => {
 
   test("has the correct title.", async ({ page }) => {
     await expect(page).toHaveTitle(
-      "DORA | DORA AI Capabilities Model report",
+      "DORA | Download the DORA AI Capabilities Model report",
     );
   });
 
   test("has the correct header.", async ({ page }) => {
-    const header = page.getByRole("heading", { name: "DORA AI Capabilities Model", exact: true });
+    const header = page.getByRole("heading", { name: "DORA AI Capabilities Model", exact: true, level: 1 });
     await expect(header).toBeVisible();
   });
 
@@ -22,7 +22,7 @@ test.describe("AI Capabilities Model report page", () => {
   });
 
   test("has the correct download header.", async ({ page }) => {
-    const downloadHeader = page.getByRole("heading", { name: "Download the DORA AI Capabilities Model report", exact: true });
+    const downloadHeader = page.getByRole("heading", { name: "Download the DORA AI Capabilities Model report", exact: true, level: 2 });
     await expect(downloadHeader).toBeVisible();
   });
 

diff --git a/test/playwright/tests/ai/aicm-questions.spec.ts b/test/playwright/tests/ai/aicm-questions.spec.ts
@@ -6,7 +6,7 @@ test.describe('AICM questions page', () => {
   });
 
   test('has the correct title', async ({ page }) => {
-    await expect(page).toHaveTitle(/DORA AI Capabilities Model questions/);
+    await expect(page).toHaveTitle(/Survey Questions/);
   });
 
   test('has the "AI adoption" section with subheadings', async ({ page }) => {