docs(downloads): DLT-3052 DLT-3355 add downloads section and navbar hovercards

[Francis Rupert (francisrupert)]

🛠️ Type Of Change

• Documentation

📖 Jira Ticket

• https://dialpad.atlassian.net/browse/DLT-3052
• https://dialpad.atlassian.net/browse/DLT-3355

📖 Description

New /downloads/ section:

Note

The top nav bar may not be the final location, but fine for now.

• DownloadsCatalog.vue driven by _data/downloads.json
• 5 sections: Logo, Icon, Gradient, Product Storytelling, Graphic
• noSidebar frontmatter flag (Layout.vue) for full-width section pages
• selfManagedHeaderPaths in Page.vue so Downloads registers its own TOC entries
• generate-raw-markdown.mjs post-process emits /md/downloads/index.md

Navbar hovercards (Foundations / Design System / UI Kits):

• Hover reveals immediate children, each with a one-line description from the page's frontmatter
• Click on anchor or inner link dismisses via v-if unmount
• Two reset paths: route-change for inner-link navigation, mouseleave on the dismissed anchor button for same-page clicks (paired with @blur for keyboard parity)
• Icons sourced from site-nav.json (same data as the sidebar)
• Descriptions injected at theme init via _injectFrontmatterIntoSidebar (extends an existing keywords/status injector to also pick up description)

PageHeader:

• Download button uses <router-link> for internal /downloads/#anchor paths, opens external URLs in a new tab
• "Back to What's New" link on post detail pages, extensible via a BACK_LINKS table for future child-detail sections
• copiedTimeout cleared on unmount

isExternalUrl util in theme/utils/, shared by PageHeader and SidebarItem (replaces two inline /^https?:\/\//.test(...) copies).

💡 Context

Downloads paired with Google Drive replaces Brand Design's use of Bynder.

📝 Checklist

• No private Dialpad links or info in code or PR description.
• Reviewed the diff.
• Considered performance impact (hovercard mounts are cheap; v-if unmount avoids tippy state churn on dismissal).
• Validated keyboard navigation (@blur paired with @mouseleave on the dismissed nav button).

What this PR does NOT do

• Touch foundations content (separate PR, DLT-3349)
• Touch the homepage (separate PR, DLT-3350)
• Modify dialtone-vue components. DtHovercard's hide() short-circuits when content is focused (which a click does), so click-to-dismiss is solved in the consumer via v-if unmount rather than via a component change.

📷 Screenshots / GIFs

Downloads

Screen.Recording.2026-04-26.at.10.54.12.AM.mov

Top Nav Bar Hovercards

Screen.Recording.2026-04-26.at.10.56.21.AM.mov

[coderabbitai]

Adds a /downloads/ section with DownloadsCatalog (driven by _data/downloads.json and post-processed raw markdown), navbar hovercards populated from frontmatter descriptions, noSidebar opt-out, PageHeader download/back links, self-managed TOC for downloads, shared isExternalUrl util, and keyboard/blur/dismiss behavior improvements.

Overall Judgement

✅ Ready to merge — Implementation is focused, includes build/tooling and accessibility considerations, and passes privacy/keyboard checks.

Walkthrough

Adds a Downloads documentation page and Vue component, integrates it into navbar and theme behavior, injects per-page descriptions into sidebar items, adds an isExternalUrl helper, and extends build scripts to generate flattened raw markdown for the downloads section.

Changes

Cohort / File(s)	Summary
Downloads Feature Core apps/dialtone-documentation/docs/.vuepress/views/DownloadsCatalog.vue, apps/dialtone-documentation/docs/_data/downloads.json, apps/dialtone-documentation/docs/downloads/index.md	New DownloadsCatalog component and data file; new downloads page that renders catalog, per-item and bulk download links, and populates page headers for "On this Page".
Navigation & Page UI apps/dialtone-documentation/docs/.vuepress/theme/components/Navbar.vue, apps/dialtone-documentation/docs/.vuepress/theme/components/PageHeader.vue, apps/dialtone-documentation/docs/.vuepress/theme/components/Page.vue, apps/dialtone-documentation/docs/.vuepress/theme/layouts/Layout.vue	Navbar adds Downloads entry and hovercard behavior; PageHeader adds conditional back-link and download button, button styling/spacing and RAW_SECTIONS update; Page watcher skips extra routes; Layout respects $frontmatter.noSidebar.
Theme Index & Client Registration apps/dialtone-documentation/docs/.vuepress/theme/index.js, apps/dialtone-documentation/docs/.vuepress/client.js	Sidebar injection now fills missing item description from page frontmatter via a lookup map; client registers DownloadsCatalog globally.
Utilities apps/dialtone-documentation/docs/.vuepress/theme/utils/isExternalUrl.js	Adds isExternalUrl(url) helper to detect http/https external links.
Build & Tooling apps/dialtone-documentation/scripts/generate-raw-markdown.mjs, apps/dialtone-documentation/scripts/lib/generate-llms.mjs	Raw-markdown generator gained downloads section, refactored frontmatter parsing, and post-processes to emit flattened downloads markdown; SECTION_META updated to include downloads for LLM index generation.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Router
    participant DownloadsCatalog
    participant DataFile as downloads.json
    participant ThemeHeaders as HeadersStore
    participant Sidebar

    User->>Router: navigate to /downloads
    Router->>DownloadsCatalog: mount component
    DownloadsCatalog->>DataFile: load sections & items
    DownloadsCatalog->>ThemeHeaders: inject computed headers
    ThemeHeaders->>Sidebar: populate "On this Page"
    DownloadsCatalog->>User: render catalog with download links/buttons

Loading

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/dialpad-design-nav-infra

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wiz-inc-55b470eb7e]

Wiz Scan Summary

Scanner	Findings
Vulnerabilities	-
Sensitive Data	-
Secrets	-
IaC Misconfigurations	-
SAST Findings	2
Software Management Findings	-
Total	2

View scan details in Wiz

To detect these findings earlier in the dev lifecycle, try using Wiz Code VS Code Extension.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2cdf77d12f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "Codex (@codex) review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".

[coderabbitai]

Actionable comments posted: 7

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/dialtone-documentation/docs/_data/downloads.json`:
- Around line 100-105: The JSON contains a placeholder label in the downloads
data: replace the "label": "Label" inside the "items" array entry with a
descriptive text that matches the "svg": "download-graphic" asset (e.g.,
"Download graphic" or a more specific description like "PDF download graphic");
update the "label" value in that object so it accurately describes the graphic
for consumers of the downloads data.
- Around line 74-79: Replace the placeholder label value in the downloads.json
items array: find the object with "svg": "download-gradient" and change the
"label" property from "Label" to a meaningful, user-facing string that describes
the download (e.g., the file type or action such as "Download PDF" or "Get App")
so the UI displays a clear label.
- Around line 1-108: The JSON currently contains hardcoded user-facing strings
(e.g., sections.*.title, sections.*.relatedLabel, sections.*.downloadAllLabel,
and sections.*.items[*].label) which must be replaced with FTL localization
keys; update each string to a stable key (e.g., downloads.logo.title,
downloads.icon.items.gradient.label) and put the actual text in the FTL
translations file, then modify the docs rendering/template to resolve those keys
at runtime so the JSON only contains the localization keys and not English text;
ensure all instances (logo, icon, gradient, product-storytelling, graphic
sections and their items, relatedLabel/downloadAllLabel fields) are converted
and add corresponding entries to the .ftl file for each key.

In `@apps/dialtone-documentation/docs/.vuepress/theme/components/PageHeader.vue`:
- Around line 88-146: The primary "Copy MD" action currently calls
onCopyAsMarkdown() even when rawMarkdownUrl is null; update the dt-split-button
so the primary action is disabled/guarded when rawMarkdownUrl is falsy and
ensure onCopyAsMarkdown early-returns or shows a fallback (e.g., disabled state
or tooltip) when rawMarkdownUrl is missing; specifically, modify the
dt-split-button props/handler around the Copy MD primary action and add a
null-check inside the onCopyAsMarkdown method (and/or set a
:disabled="!rawMarkdownUrl" on dt-split-button) so clicking the main CTA does
nothing or informs the user when rawMarkdownUrl is not available.

In `@apps/dialtone-documentation/docs/.vuepress/views/DownloadsCatalog.vue`:
- Around line 45-68: The download button is currently nested inside the dt-stack
gated by v-if="item.label", so items with a downloadUrl but no label lose their
CTA; update the template to render the dt-button independently of item.label —
keep the dt-text block wrapped in v-if="item.label" (or render it conditionally
inside dt-stack) and move the dt-button (v-if="item.downloadUrl") outside or
alongside dt-stack so the Download button (dt-button) is displayed whenever
item.downloadUrl exists regardless of item.label; adjust the template around
dt-stack, dt-text and dt-button in DownloadsCatalog.vue accordingly.

In `@apps/dialtone-documentation/docs/downloads/index.md`:
- Around line 1-7: The new Downloads page
(apps/dialtone-documentation/docs/downloads/index.md with frontmatter title
"Downloads" and path /downloads/) was not added to the site's navigation data;
add an entry for "/downloads/" to the _data/site-nav.json array/object used for
site navigation (preserving the existing structure and keys such as title, path,
order or parent if present) so the page is registered even though it has
noSidebar: true; ensure the JSON entry uses the same title "Downloads" and
correct path "/downloads/" and follow existing ordering/grouping conventions in
_data/site-nav.json.

In `@apps/dialtone-documentation/scripts/generate-raw-markdown.mjs`:
- Around line 504-518: postProcessDownloads currently uses title from
parseFrontmatter directly which yields "# undefined" if title is missing; update
postProcessDownloads to provide a sensible fallback (e.g., 'Untitled' or an
empty string) when title is falsy before building the first line, e.g., compute
a safeTitle = title || 'Untitled' (or derive from sourcePath) and use safeTitle
when pushing `# ${safeTitle}`; reference parseFrontmatter and the
postProcessDownloads function to locate the change.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: aab2faa3-f0db-4b02-b214-3686c418f447

📥 Commits

Reviewing files that changed from the base of the PR and between 961965a and 2cdf77d.

⛔ Files ignored due to path filters (11)

• apps/dialtone-documentation/docs/.vuepress/public/assets/images/download-gradient.svg is excluded by !**/*.svg
• apps/dialtone-documentation/docs/.vuepress/public/assets/images/download-graphic.svg is excluded by !**/*.svg
• apps/dialtone-documentation/docs/.vuepress/public/assets/images/download-logo--dark-icon.svg is excluded by !**/*.svg
• apps/dialtone-documentation/docs/.vuepress/public/assets/images/download-logo--gradient-icon.svg is excluded by !**/*.svg
• apps/dialtone-documentation/docs/.vuepress/public/assets/images/download-logo--meetings-dark.svg is excluded by !**/*.svg
• apps/dialtone-documentation/docs/.vuepress/public/assets/images/download-logo--meetings-light.svg is excluded by !**/*.svg
• apps/dialtone-documentation/docs/.vuepress/public/assets/images/download-logo--primary-2-dark.svg is excluded by !**/*.svg
• apps/dialtone-documentation/docs/.vuepress/public/assets/images/download-logo--primary-2-light.svg is excluded by !**/*.svg
• apps/dialtone-documentation/docs/.vuepress/public/assets/images/download-logo--secondary-1-color-dark.svg is excluded by !**/*.svg
• apps/dialtone-documentation/docs/.vuepress/public/assets/images/download-logo--secondary-1-color-light.svg is excluded by !**/*.svg
• apps/dialtone-documentation/docs/.vuepress/public/assets/images/download-product-storytelling.svg is excluded by !**/*.svg

📒 Files selected for processing (11)

• apps/dialtone-documentation/docs/.vuepress/client.js
• apps/dialtone-documentation/docs/.vuepress/theme/components/Navbar.vue
• apps/dialtone-documentation/docs/.vuepress/theme/components/Page.vue
• apps/dialtone-documentation/docs/.vuepress/theme/components/PageHeader.vue
• apps/dialtone-documentation/docs/.vuepress/theme/index.js
• apps/dialtone-documentation/docs/.vuepress/theme/layouts/Layout.vue
• apps/dialtone-documentation/docs/.vuepress/theme/utils/isExternalUrl.js
• apps/dialtone-documentation/docs/.vuepress/views/DownloadsCatalog.vue
• apps/dialtone-documentation/docs/_data/downloads.json
• apps/dialtone-documentation/docs/downloads/index.md
• apps/dialtone-documentation/scripts/generate-raw-markdown.mjs

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/dialtone-documentation/docs/.vuepress/views/DownloadsCatalog.vue`:
- Around line 23-35: The section-level download button currently always renders
(dt-button) and shows a disabled CTA when section.downloadAllUrl is null; change
the template to render the dt-button only when section.downloadAllUrl is truthy
(use v-if on the dt-button or its wrapper) so the CTA is omitted entirely when
no URL is provided—keep using section.downloadAllLabel for the label and
preserve the startIcon slot and other props unchanged.

In `@apps/dialtone-documentation/scripts/generate-raw-markdown.mjs`:
- Around line 664-675: The downloads post-processing swallow (catch) hides
failures so an unexpanded /md/downloads/index.md persists; change the block that
checks section.name === 'downloads' to let postProcessDownloads errors fail the
run by either removing the try/catch or rethrowing the caught error (or calling
process.exit(1)) after logging; specifically update the code around the call to
postProcessDownloads (and the DOWNLOADS_JSON/readFileSync usage) so that any
thrown err is not only logged but causes a non-zero exit or is rethrown to fail
the export.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 80f997af-618c-4c5b-94f9-990ed1f7f34e

📥 Commits

Reviewing files that changed from the base of the PR and between 2cdf77d and ef174fc.

📒 Files selected for processing (5)

• apps/dialtone-documentation/docs/.vuepress/theme/components/PageHeader.vue
• apps/dialtone-documentation/docs/.vuepress/views/DownloadsCatalog.vue
• apps/dialtone-documentation/docs/_data/downloads.json
• apps/dialtone-documentation/scripts/generate-raw-markdown.mjs
• apps/dialtone-documentation/scripts/lib/generate-llms.mjs

[coderabbitai]

♻️ Duplicate comments (1)

apps/dialtone-documentation/scripts/generate-raw-markdown.mjs (1)

664-676: ⚠️ Potential issue | 🟠 Major

Set a non-zero exit code when downloads post-process fails.

This catch block logs and increments errorCount, but the process can still exit successfully, allowing stale/unexpanded downloads markdown to flow into later indexing steps. Mark the run as failed at this point.

Suggested minimal fix

     if (section.name === 'downloads') {
       try {
         const downloadsData = JSON.parse(readFileSync(DOWNLOADS_JSON, 'utf-8'));
         postProcessDownloads(
           resolve(sourceDir, 'index.md'),
           resolve(outputBase, 'index.md'),
           downloadsData,
         );
       } catch (err) {
         console.error(`[generate-raw-markdown] downloads post-process: ${err.message}`);
         errorCount++;
+        process.exitCode = 1;
       }
     }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@apps/dialtone-documentation/scripts/generate-raw-markdown.mjs` around lines
664 - 676, The catch block for the downloads post-process (where section.name
=== 'downloads' and you call postProcessDownloads with DOWNLOADS_JSON) only logs
and increments errorCount; modify the catch to mark the run as failed by setting
a non-zero exit status (e.g., set process.exitCode = 1 or call process.exit(1))
after incrementing errorCount so failures of postProcessDownloads are reflected
in the process exit code and prevent stale output from proceeding.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@apps/dialtone-documentation/scripts/generate-raw-markdown.mjs`:
- Around line 664-676: The catch block for the downloads post-process (where
section.name === 'downloads' and you call postProcessDownloads with
DOWNLOADS_JSON) only logs and increments errorCount; modify the catch to mark
the run as failed by setting a non-zero exit status (e.g., set process.exitCode
= 1 or call process.exit(1)) after incrementing errorCount so failures of
postProcessDownloads are reflected in the process exit code and prevent stale
output from proceeding.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 63429202-0f98-4204-8571-345bea7e0f31

📥 Commits

Reviewing files that changed from the base of the PR and between ef174fc and 4b18667.

📒 Files selected for processing (1)

• apps/dialtone-documentation/scripts/generate-raw-markdown.mjs

[Brad Paugh (braddialpad)]

well this is annoying isn't it... Probably an improvement we can make to hovercard, but outside the scope of this PR of course.

[github-actions]

✔️ Deploy previews ready!
😎 Dialtone documentation preview: https://dialtone.dialpad.com/deploy-previews/pr-1229/