diff --git a/.github/skills/previewing-docs-site/SKILL.md b/.github/skills/previewing-docs-site/SKILL.md new file mode 100644 index 000000000..4d2d68d4f --- /dev/null +++ b/.github/skills/previewing-docs-site/SKILL.md @@ -0,0 +1,61 @@ +--- +name: previewing-docs-site +description: Builds and serves the documentation site (docs/, GitHub Pages with Just the Docs) locally so changes can be reviewed before they ship. Use when asked to preview, render, check or review the docs site, the user manual, release notes or the landing page, or to verify styling, images, light and dark mode, or the sidebar. +--- + +# Previewing the Docs Site + +The site is built by GitHub Pages from `docs/` with the Just the Docs remote theme. There are no hosted +PR previews, so review changes with a local build. Background and site structure: +`docs/ai-and-plans/features/docs-site/README.md`. + +## Quick start (Windows) + +```powershell +.github/skills/previewing-docs-site/scripts/preview.ps1 # port 4000 +.github/skills/previewing-docs-site/scripts/preview.ps1 -Port 4001 # second checkout +``` + +Open **http://127.0.0.1:4000/vscode-documentdb/** (note the base URL) once the log says +`Server running`. The first build downloads the theme and takes about 2 minutes; later edits +rebuild automatically. + +The script keeps everything outside the repository (Gemfile copy, `Gemfile.lock`, `_site`) in +`%TEMP%\vscode-documentdb-docs-preview`, installs gems on first use, and fixes the `--source` +path casing (see Pitfalls). + +When an agent runs it, start it as a detached background process and poll the URL until it +returns 200 before opening pages. + +## Prerequisites + +- Ruby with the DevKit: `winget install RubyInstallerTeam.RubyWithDevKit.3.3` + (the script also looks in `C:\Ruby33-x64\bin`) +- Network access for the first build (gems and the remote theme) + +## macOS and Linux + +```bash +mkdir -p /tmp/docs-preview && cp .github/skills/previewing-docs-site/scripts/Gemfile /tmp/docs-preview/ +cd /tmp/docs-preview && bundle install +bundle exec jekyll serve --source "$OLDPWD/docs" --destination ./_site --livereload +``` + +## What to check + +- **Light and dark mode.** The site follows the OS color scheme. In a browser, toggle the OS + setting, or with Playwright use `page.emulateMedia({ colorScheme: 'dark' })`. +- **Theme-aware images.** Every `` should swap to its `_dark` source in dark mode. +- **Sidebar and "On this page".** New pages appear only after a restart (see Pitfalls). +- **Excluded content.** Only `index.md`, `user-manual/` and `release-notes/` are published; other + `docs/` content must be listed under `exclude` in `_config.yml`. + +## Pitfalls + +| Symptom | Cause and fix | +| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| Custom styles missing, no error | `--source` casing differs from the disk (e.g. `C:\local` vs `C:\Local`), so `docs/_sass` is dropped. Use the script. | +| New page or `_config.yml` change not visible | The sidebar is cached (`jekyll-include-cache`) and config is read once. Stop the server and start it again. | +| `/` returns 404 | The site lives under `/vscode-documentdb/`. | +| Port already in use | Another preview is running. Use `-Port 4001`, or stop the old `ruby.exe` by its process ID. | +| Build works locally but not on GitHub | Pages builds `gh-pages` itself (legacy build), so only plugins listed on pages.github.com/versions work. Keep the Gemfile on `github-pages`. | diff --git a/.github/skills/previewing-docs-site/scripts/Gemfile b/.github/skills/previewing-docs-site/scripts/Gemfile new file mode 100644 index 000000000..04d05912a --- /dev/null +++ b/.github/skills/previewing-docs-site/scripts/Gemfile @@ -0,0 +1,9 @@ +source 'https://rubygems.org' + +# Same gem set GitHub Pages uses to build the site (see https://pages.github.com/versions/). +gem 'github-pages', group: :jekyll_plugins +# Loaded by the Pages plugins; bundled with Ruby on Windows but not visible to Bundler on Linux and macOS. +gem 'rake' +gem 'webrick' +gem 'tzinfo-data' +gem 'wdm', '>= 0.1.0', platforms: [:windows] diff --git a/.github/skills/previewing-docs-site/scripts/preview.ps1 b/.github/skills/previewing-docs-site/scripts/preview.ps1 new file mode 100644 index 000000000..7a156d987 --- /dev/null +++ b/.github/skills/previewing-docs-site/scripts/preview.ps1 @@ -0,0 +1,55 @@ +<# +.SYNOPSIS + Build and serve the docs site (docs/) locally, the way GitHub Pages builds it. + +.DESCRIPTION + Copies the Gemfile to a work folder outside the repository, installs the gems once, and runs + `jekyll serve` with live reload. Nothing is written inside the repository. + Open http://127.0.0.1:/vscode-documentdb/ when "Server running" appears. + +.EXAMPLE + .github/skills/previewing-docs-site/scripts/preview.ps1 +.EXAMPLE + .github/skills/previewing-docs-site/scripts/preview.ps1 -Port 4001 -WorkDir C:\temp\docs-preview +#> +param( + [int]$Port = 4000, + [string]$WorkDir = (Join-Path ([IO.Path]::GetTempPath()) 'vscode-documentdb-docs-preview') +) +$ErrorActionPreference = 'Stop' + +# Jekyll in safe mode silently drops docs/_sass when --source casing differs from the disk, +# so rebuild the path with the exact casing of every segment. +function Get-ExactPath([string]$Path) { + $full = [IO.Path]::GetFullPath($Path).TrimEnd('\') + $parts = $full.Split('\') + $exact = $parts[0].ToUpper() + foreach ($part in $parts[1..($parts.Count - 1)]) { + $match = Get-ChildItem -LiteralPath "$exact\" -Force | Where-Object { $_.Name -ieq $part } | Select-Object -First 1 + $exact = "$exact\$($match.Name)" + } + $exact +} + +$docs = Get-ExactPath (Join-Path $PSScriptRoot '..\..\..\..\docs') +if (-not (Test-Path (Join-Path $docs '_config.yml'))) { throw "docs/_config.yml not found at $docs" } + +$ruby = 'C:\Ruby33-x64\bin' +if (-not (Get-Command bundle -ErrorAction SilentlyContinue) -and (Test-Path $ruby)) { $env:Path = "$ruby;$env:Path" } +if (-not (Get-Command bundle -ErrorAction SilentlyContinue)) { + throw 'Ruby with Bundler not found. Install it with: winget install RubyInstallerTeam.RubyWithDevKit.3.3' +} + +New-Item -ItemType Directory -Force -Path $WorkDir | Out-Null +Copy-Item (Join-Path $PSScriptRoot 'Gemfile') $WorkDir -Force +$env:BUNDLE_GEMFILE = Join-Path $WorkDir 'Gemfile' +Push-Location $WorkDir +try { + bundle check *> $null + if ($LASTEXITCODE -ne 0) { bundle install } + Write-Host "Serving $docs at http://127.0.0.1:$Port/vscode-documentdb/ (first build takes about 2 minutes)" + bundle exec jekyll serve --source $docs --destination (Join-Path $WorkDir '_site') --livereload --port $Port +} +finally { + Pop-Location +} diff --git a/.github/skills/writing-release-notes/EXAMPLES-MAJOR-RELEASE.md b/.github/skills/writing-release-notes/EXAMPLES-MAJOR-RELEASE.md index c8684b224..538625fc6 100644 --- a/.github/skills/writing-release-notes/EXAMPLES-MAJOR-RELEASE.md +++ b/.github/skills/writing-release-notes/EXAMPLES-MAJOR-RELEASE.md @@ -7,8 +7,10 @@ This is a complete example of a major/minor release notes file (X.Y.0). ## Template ```markdown -> **Release Notes** — [Back to Release Notes](../index.md#release-notes) - +--- +title: 'vX.Y' +parent: 'Release Notes' +nav_order: NNNN --- # DocumentDB for VS Code Extension vX.Y @@ -63,8 +65,10 @@ See the full changelog entry for this release: ## Real Example (v0.6.0) ```markdown -> **Release Notes** — [Back to Release Notes](../index.md#release-notes) - +--- +title: 'v0.6' +parent: 'Release Notes' +nav_order: 60 --- # DocumentDB for VS Code Extension v0.6 diff --git a/.github/skills/writing-release-notes/RELEASE-NOTES-FORMAT.md b/.github/skills/writing-release-notes/RELEASE-NOTES-FORMAT.md index 12334c24b..7dfc49e18 100644 --- a/.github/skills/writing-release-notes/RELEASE-NOTES-FORMAT.md +++ b/.github/skills/writing-release-notes/RELEASE-NOTES-FORMAT.md @@ -15,12 +15,21 @@ Examples: ### Header (Required for all release notes files) -```markdown -> **Release Notes** — [Back to Release Notes](../index.md#release-notes) +Front matter that places the page in the documentation site's sidebar. The breadcrumbs replace the +old "Back to Release Notes" line. +```markdown +--- +title: 'vX.Y' +parent: 'Release Notes' +nav_order: NNNN --- ``` +`nav_order` is `major * 1000 + minor * 10`, for example `1010` for 1.1 and `110` for 0.11. The +Release Notes section lists pages in descending `nav_order`, so the newest release appears first. +Patch releases append to the existing file and do not change the front matter. + ### Main Release Section (X.Y.0) ```markdown diff --git a/.github/skills/writing-release-notes/SKILL.md b/.github/skills/writing-release-notes/SKILL.md index 1a1aa0388..095ba5b67 100644 --- a/.github/skills/writing-release-notes/SKILL.md +++ b/.github/skills/writing-release-notes/SKILL.md @@ -141,7 +141,7 @@ Before completing: - [ ] All issue/PR links are correct and clickable - [ ] Version numbers match across all files - [ ] Categories are appropriate (Features, Fixes, Improvements) -- [ ] Release notes use proper header format +- [ ] Release notes start with the front matter header (`title`, `parent: 'Release Notes'`, `nav_order`) - [ ] Patch releases append to existing file with `---` separator - [ ] `docs/index.md` Release Notes section updated with link to new version - [ ] Screenshot question was answered diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 883e3e25a..3e9db30d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -419,7 +419,7 @@ mutation($repo: ID!, $cat: ID!, $title: String!, $body: String!) { createDiscussion(input: {repositoryId: $repo, categoryId: $cat, title: $title, body: $body}) { discussion { url } } -}' -f repo= -f cat= -f title="vX.Y.Z" -f body="$(cat docs/release-notes/X.Y.md)" \ +}' -f repo= -f cat= -f title="vX.Y.Z" -f body="$(sed '1,/^---$/d' docs/release-notes/X.Y.md)" \ --jq '.data.createDiscussion.discussion.url' ``` diff --git a/docs/_config.yml b/docs/_config.yml index 932d54331..a8a8de9ad 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,2 +1,76 @@ +# Documentation site, rendered by GitHub Pages with the Just the Docs theme. +# Interim solution until the user manual moves to learn.microsoft.com. +# How it works and how to preview it: ai-and-plans/features/docs-site/README.md +remote_theme: just-the-docs/just-the-docs@v0.12.0 + title: DocumentDB for VS Code description: Learn more about the DocumentDB for VS Code Extension +baseurl: '/vscode-documentdb' +url: 'https://microsoft.github.io' + +plugins: + - jekyll-remote-theme + - jekyll-include-cache + - jekyll-seo-tag + - jekyll-sitemap + - jekyll-redirect-from + - jemoji + +# Light by default; head_custom.html switches to dark when the OS prefers it. +color_scheme: light + +search_enabled: true +search: + heading_level: 2 + previews: 2 + preview_words_before: 3 + preview_words_after: 3 + rel_url: true + +heading_anchors: true +back_to_top: true +back_to_top_text: 'Back to top' + +aux_links: + 'GitHub': + - 'https://github.com/microsoft/vscode-documentdb' + 'Marketplace': + - 'https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-documentdb' +aux_links_new_tab: true + +gh_edit_link: true +gh_edit_link_text: 'Edit this page on GitHub' +gh_edit_repository: 'https://github.com/microsoft/vscode-documentdb' +gh_edit_branch: 'main' +gh_edit_source: docs +gh_edit_view_mode: 'tree' + +callouts: + note: + title: Note + color: blue + tip: + title: Tip + color: green + warning: + title: Warning + color: yellow + important: + title: Important + color: purple + caution: + title: Caution + color: red + +# The public site publishes only index.md, user-manual/ and release-notes/. +# Everything else under docs/ is contributor material and stays out of the site. +exclude: + - Gemfile + - Gemfile.lock + - node_modules + - ai-and-plans/ + - blog-posts/ + - atlas-mongodb-discovery-flow.md + - index-advisor-data-flow.md + - localization.md + - query-generation-data-flow.md diff --git a/docs/_includes/head_custom.html b/docs/_includes/head_custom.html new file mode 100644 index 000000000..361febd0f --- /dev/null +++ b/docs/_includes/head_custom.html @@ -0,0 +1,3 @@ + + + diff --git a/docs/_includes/title.html b/docs/_includes/title.html new file mode 100644 index 000000000..b85051cac --- /dev/null +++ b/docs/_includes/title.html @@ -0,0 +1,9 @@ +{%- comment -%} + Overrides the theme's title.html: DocumentDB icon next to the site title. + The source swaps to the dark-background icon when the OS prefers dark. +{%- endcomment -%} + + + + +{{ site.title | replace: ' for VS Code', ' for VS Code' }} diff --git a/docs/_sass/custom/custom.scss b/docs/_sass/custom/custom.scss new file mode 100644 index 000000000..3ee520c61 --- /dev/null +++ b/docs/_sass/custom/custom.scss @@ -0,0 +1,154 @@ +// Semibold headings, closer to learn.microsoft.com than the theme's light weights. +h1, +.text-alpha { + font-weight: 600; +} + +h2, +h3, +.text-beta, +.text-gamma { + font-weight: 600; +} + +// The theme renders h4 as small uppercase labels, smaller than body text, so +// "Step 1: ..." style subheadings are easy to miss. Keep them at body size and bold. +.main-content h4 { + font-size: 1rem !important; + font-weight: 600; + text-transform: none; + letter-spacing: normal; +} + +.site-title { + font-weight: 600; +} + +// Sidebar title with the DocumentDB icon (see _includes/title.html). +.site-title { + display: flex; + align-items: center; + gap: 0.625rem; +} + +.site-icon { + display: flex; + flex: none; + + img { + width: 1.75rem; + height: auto; + } +} + +// The theme sets 1.5rem !important from 31.25rem up; keep the title on one line next to the icon. +@media (min-width: 31.25rem) { + .site-title { + font-size: 1.25rem !important; + } +} + +// "On this page" panel (assets/js/page-toc.js). +// From 78.5rem up, the main column widens by 12rem to hold a right-side column on every page, +// so pages with and without the panel share one layout. The theme's sidebar centering formula +// is repeated here with the wider content width. +$page-toc-width: 12rem; +$page-toc-gap: 2rem; +$page-toc-breakpoint: $nav-width + $content-width + $page-toc-width; + +.page-toc { + display: none; +} + +@media (min-width: $page-toc-breakpoint) { + .side-bar { + width: calc((100% - #{$nav-width + $content-width + $page-toc-width}) / 2 + #{$nav-width}); + + & + .main { + margin-left: calc((100% - #{$nav-width + $content-width + $page-toc-width}) / 2 + #{$nav-width}); + max-width: $content-width + $page-toc-width; + } + } + + .main-content-wrap { + display: grid; + grid-template-columns: minmax(0, 1fr) $page-toc-width; + column-gap: $page-toc-gap; + align-items: start; + + > :not(.page-toc) { + grid-column: 1; + } + } + + .page-toc { + display: block; + grid-column: 2; + grid-row: 1 / span 3; + position: sticky; + top: 1.5rem; + max-height: calc(100vh - 3rem); + overflow-y: auto; + padding-top: 0.25rem; + font-size: 0.8125rem; + line-height: 1.4; + + .page-toc-title { + margin: 0 0 0.5rem; + font-size: 0.8125rem; + font-weight: 600; + color: $body-heading-color; + } + + ul { + margin: 0; + padding: 0; + list-style: none; + border-left: 1px solid $border-color; + } + + li { + margin: 0; + padding: 0; + + &::before { + content: none; + } + } + + a { + display: block; + margin-left: -1px; + padding: 0.25rem 0 0.25rem 0.75rem; + border-left: 2px solid transparent; + color: $body-text-color; + text-decoration: none; + + &:hover { + color: $link-color; + } + + &.active { + border-left-color: $link-color; + color: $link-color; + font-weight: 600; + } + } + + .page-toc-h3 a { + padding-left: 1.5rem; + } + } +} + +// Code blocks: the theme keeps the 16px body line box around 12px code, which pulls +// box-drawing characters apart. Size the 
 like its code so ASCII diagrams connect.
+pre.highlight {
+    font-size: 0.75rem;
+    line-height: 1.25;
+
+    code {
+        font-size: 1em;
+        line-height: inherit;
+    }
+}
diff --git a/docs/_sass/custom/setup.scss b/docs/_sass/custom/setup.scss
new file mode 100644
index 000000000..4da212aed
--- /dev/null
+++ b/docs/_sass/custom/setup.scss
@@ -0,0 +1,12 @@
+// Microsoft-style typography and brand color.
+// Light scheme values use !default, so these win in light mode; the dark scheme keeps its own colors.
+$body-font-family:
+    'Segoe UI Variable Text',
+    'Segoe UI',
+    system-ui,
+    -apple-system,
+    'Helvetica Neue',
+    sans-serif;
+$mono-font-family: 'Cascadia Mono', consolas, menlo, monospace;
+$link-color: #0067b8;
+$btn-primary-color: #0067b8;
diff --git a/docs/ai-and-plans/README.md b/docs/ai-and-plans/README.md
index 5aeb6a389..c3b2c2acb 100644
--- a/docs/ai-and-plans/README.md
+++ b/docs/ai-and-plans/README.md
@@ -47,6 +47,7 @@ treat `status: historical` or `status: superseded` as current.
 | [e2e-testing](./features/e2e-testing/README.md)                           | The planned installed-workbench and webview end-to-end test iteration                                    | planned                             |
 | [data-grid](./features/data-grid/README.md)                               | The Collection View table and tree, including the planned SlickGrid replacement                          | planned                             |
 | [survey](./features/survey/README.md)                                     | Survey refresh: simpler eligibility, broader activity coverage, cohort telemetry, and invitation surface | draft #992; enabled                 |
+| [docs-site](./features/docs-site/README.md)                               | The GitHub Pages documentation site: Just the Docs theme, OS dark mode, local preview                    | draft #420                          |
 
 Everything else is a single file at this root, such as:
 
diff --git a/docs/ai-and-plans/features/docs-site/README.md b/docs/ai-and-plans/features/docs-site/README.md
new file mode 100644
index 000000000..c2a22a85d
--- /dev/null
+++ b/docs/ai-and-plans/features/docs-site/README.md
@@ -0,0 +1,221 @@
+---
+feature: docs-site
+kind: design
+status: active
+prs: [420]
+created: 2026-10-16
+verified: 2026-10-16
+code:
+    - docs/_config.yml
+    - docs/_includes/**
+    - docs/_sass/custom/**
+    - docs/user-manual.md
+    - docs/release-notes.md
+    - .github/workflows/deploy-documentation-production.yml
+    - .github/skills/previewing-docs-site/**
+---
+
+# Documentation site (GitHub Pages)
+
+> How `docs/` becomes https://microsoft.github.io/vscode-documentdb/, which theme renders it, and how
+> to preview a change locally before it ships.
+
+## Purpose
+
+The public documentation site: the landing page, the user manual and the release notes. This
+feature covers the build and the look of that site, not its content.
+
+It is an **interim** solution. The user manual is expected to move to learn.microsoft.com; until
+then this site should look good and cost little to maintain. Changes that would make the later move
+harder (rewriting content into a site-specific format) are deliberately avoided.
+
+## Code map
+
+| Path                                                                                 | Role                                                                           |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| `.github/workflows/deploy-documentation-production.yml`                              | On push to `main` touching `docs/**`, copies `docs/` to `gh-pages`             |
+| `docs/_config.yml`                                                                   | Theme pin, plugins, search, published scope                                    |
+| `docs/user-manual.md`, `docs/release-notes.md`                                       | Sidebar section pages; served at `/user-manual/` and `/release-notes/`         |
+| `docs/user-manual/{connecting-to-databases,data-management,querying,ai-features}.md` | Category pages grouping the user manual                                        |
+| Front matter of each published page                                                  | Sidebar title, parent and order                                                |
+| `docs/_includes/head_custom.html`                                                    | Loads the dark stylesheet when the OS prefers dark, and `page-toc.js`          |
+| `docs/assets/js/page-toc.js`                                                         | Builds the "On this page" panel from the article's h2/h3 headings              |
+| `docs/_includes/title.html`                                                          | Sidebar title: DocumentDB icon (light/dark via ``) and site name      |
+| `docs/favicon.ico`                                                                   | Same favicon as documentdb.io; the theme links it automatically                |
+| `docs/assets/images/documentdb-icon-{light,dark}.svg`                                | Copies of `resources/documentdb/documentdb_icon_*.svg` with a `viewBox` added  |
+| `docs/_sass/custom/setup.scss`                                                       | Theme variables: Segoe UI, Cascadia Mono, Microsoft blue for links and buttons |
+| `docs/_sass/custom/custom.scss`                                                      | CSS after the theme: semibold headings, sidebar title, "On this page" layout   |
+
+## Architecture
+
+```
+main (docs/**) --push--> deploy-documentation-production.yml --copy--> gh-pages branch
+                                                                            |
+                         GitHub Pages "legacy" Jekyll build  <--------------+
+                         (github-pages gem: Jekyll 3.10, safe mode)
+                         + remote_theme just-the-docs@v0.12.0
+                                                                            |
+                                              microsoft.github.io/vscode-documentdb
+```
+
+- **The theme is not in the repository.** `remote_theme` downloads Just the Docs at the pinned tag
+  on every build. The repository holds content plus a few override files.
+- **The GitHub workflow does not run Jekyll.** It only copies `docs/` to `gh-pages`. GitHub Pages
+  builds that branch itself (`build_type: legacy`), so only the plugins and versions on
+  [pages.github.com/versions](https://pages.github.com/versions/) are available.
+- **Only `index.md`, `user-manual/` and `release-notes/` are published.** Everything else in
+  `docs/` is listed under `exclude` in `_config.yml`. A new top-level file or folder in `docs/` is
+  published unless it is added to that list.
+- **No PR previews.** They were removed from `main` in `c8ad1900`. Preview locally; see
+  [Previewing locally](#previewing-locally).
+
+## How the sidebar is built
+
+Every published page starts with a front matter block; that is the only navigation data:
+
+```yaml
+---
+title: 'MongoDB Atlas' # sidebar label, breadcrumb and browser tab
+parent: 'Service Discovery' # title of the parent page
+nav_order: 5 # position among siblings
+has_toc: false # only on content pages with children, to skip the auto-generated child list
+---
+```
+
+The tree mirrors the landing page's table of contents:
+
+```
+User Manual                     user-manual.md (served at /user-manual/)
+├── Connecting to Databases     user-manual/connecting-to-databases.md
+│   ├── Service Discovery       ├── Azure, Kubernetes, MongoDB Atlas, each with sub-pages
+│   └── Local Instances         └── ...
+├── Data Management             user-manual/data-management.md
+├── Querying                    user-manual/querying.md
+└── AI Features                 user-manual/ai-features.md
+Release Notes                   release-notes.md (child_nav_order: desc, newest first)
+```
+
+Rules:
+
+- **Files never move.** External links point at `user-manual/`. The hierarchy lives only in
+  front matter, so a page can be re-parented without changing its URL. The four category pages
+  are new files.
+- **Titles must be unique.** Just the Docs links a child to its parent by title. Sidebar titles
+  can be shorter than the page's H1, but they also appear in the browser tab, so they must make
+  sense on their own ("Troubleshoot MongoDB Atlas Discovery", not "Troubleshooting").
+- **Release notes:** `nav_order` is `major * 1000 + minor * 10` (1.0 is `1000`, 0.11 is `110`).
+  The [writing-release-notes](../../../../.github/skills/writing-release-notes/SKILL.md) skill
+  includes the header.
+- Breadcrumbs replace the old "Back to User Manual" lines, which were removed.
+
+**Adding a user manual page:** create the file with the front matter above, choose the `parent`
+from the tree, and add a link to the landing page's table of contents as before. Restart a running
+local preview to see it in the sidebar.
+
+When the user manual moves to learn.microsoft.com, the front matter maps to a `TOC.yml` and is
+otherwise ignored.
+
+## "On this page" panel
+
+Just the Docs has no right-side table of contents; its only in-page option is a Kramdown `{:toc}`
+list inside the article. `assets/js/page-toc.js` adds a panel instead:
+
+- Built in the browser from the article's `h2` and `h3` headings that have an `id`; headings with
+  `.no_toc` are skipped. Pages with fewer than three such headings get no panel.
+- The first entry, **Introduction**, returns to the top of the page.
+- Sticky while scrolling. The highlighted entry is the last heading that has reached the top 40%
+  of the viewport, or Introduction before the first one.
+- Shown from a 78.5rem (1256px) viewport up. There the main column is widened by 12rem on every
+  page, so pages with and without a panel share one layout; `custom.scss` repeats the theme's
+  sidebar centering formula with the wider width. Below that width nothing changes.
+- No content edits. Several pages still carry a hand-written "Table of Contents" list; it can be
+  removed page by page now that the panel exists.
+
+## Dark mode
+
+Just the Docs has no built-in "follow the OS" mode
+([issue #234](https://github.com/just-the-docs/just-the-docs/issues/234) is open). The site uses
+the light scheme and `head_custom.html` adds the theme's own dark stylesheet with
+`media="(prefers-color-scheme: dark)"`. This switches live, needs no JavaScript and does not flash.
+There is no manual toggle.
+
+## Styling
+
+Kept small on purpose:
+
+- `_sass/custom/setup.scss` sets theme variables before the color schemes load. Light-scheme
+  variables are `!default`, so the brand blue applies in light mode; the dark scheme keeps its own
+  lighter link color for contrast.
+- `_sass/custom/custom.scss` adds CSS after the theme.
+
+See [Just the Docs customization](https://just-the-docs.com/docs/customization/) for the variables.
+
+## Previewing locally
+
+The `previewing-docs-site` skill (`.github/skills/previewing-docs-site/`) wraps these steps in
+`scripts/preview.ps1`, which also fixes the path casing issue below and keeps all build output
+outside the repository. The manual steps:
+
+1. Install Ruby with the DevKit (Windows: `winget install RubyInstallerTeam.RubyWithDevKit.3.3`).
+2. Keep a Gemfile **outside** `docs/`, so it is not published:
+
+   ```ruby
+   source 'https://rubygems.org'
+   gem 'github-pages', group: :jekyll_plugins
+   gem 'webrick'
+   gem 'tzinfo-data'
+   gem 'wdm', '>= 0.1.0', platforms: [:windows]
+   ```
+
+3. From the folder holding the Gemfile:
+
+   ```bash
+   bundle install
+   bundle exec jekyll serve --source /docs --destination ./_site --livereload
+   ```
+
+4. Open http://127.0.0.1:4000/vscode-documentdb/ (note the base URL).
+
+Notes:
+
+- **Windows: pass `--source` with the exact folder casing on disk** (for example `C:\Local\...`, not
+  `C:\local\...`). In safe mode, a casing mismatch silently drops `docs/_sass` from the Sass load
+  path, and the custom styles disappear without an error. GitHub's build is not affected.
+- Restart the server after changing `_config.yml` or adding a page: the sidebar is cached in memory
+  (`jekyll-include-cache`), so new pages do not appear in the sidebar on live reload.
+- The first build downloads the theme, so it needs network access. A full build takes about
+  2 minutes locally, because the nested sidebar is rendered into every page.
+
+## Timeline
+
+| Date       | Change                                                                                   | PR / commit |
+| ---------- | ---------------------------------------------------------------------------------------- | ----------- |
+| 2025-12-11 | Pages configuration and production/preview workflows added                               | `4eda823c`  |
+| 2025-12-11 | Experimental Minima theme, `docs/THEME_CUSTOMIZATION.md`                                 | #420        |
+| 2025-12-11 | Preview deployments removed from `main`                                                  | `c8ad1900`  |
+| 2026-10-16 | `main` merged into #420, preview workflow change dropped, guide moved here and refreshed | #420        |
+| 2026-10-16 | Site limited to `index.md`, `user-manual/` and `release-notes/`                          | #420        |
+| 2026-10-16 | Minima replaced by Just the Docs: sidebar, search, OS dark mode, Microsoft styling       | #420        |
+| 2026-10-16 | User manual grouped into categories; navigation moved into page front matter             | #420        |
+| 2026-10-16 | documentdb.io favicon; DocumentDB icon in the sidebar title, swapping with the OS theme  | #420        |
+| 2026-10-16 | "On this page" panel for article sections; landing page links on one line                | #420        |
+| 2026-10-16 | Dark variants for every image; copy-and-paste diagrams redrawn for both themes           | #420        |
+| 2026-10-16 | Code block line height and `h4` styling fixed                                            | #420        |
+| 2026-10-16 | `previewing-docs-site` skill for local previews                                          | #420        |
+
+Details: [01-minima-theme.md](./iterations/01-minima-theme.md),
+[02-just-the-docs.md](./iterations/02-just-the-docs.md).
+
+## Decisions
+
+No `decisions.md` yet. The choices are recorded in the iteration files.
+
+## Open gaps
+
+1. **Landing page duplicates the sidebar.** `index.md` still carries the full table of contents and
+   its own "DocumentDB for VS Code" heading. It must be kept in sync with the front matter by hand.
+2. **Excluded pages return 404 after deploy.** Production currently serves `blog-posts/`,
+   `localization` and the data-flow documents. Nothing in the repository, the extension or the
+   published pages links to them, but outside bookmarks will break.
+3. **Not verified on GitHub.** Everything was checked with a local `github-pages` 232 build, not on
+   the live Pages build.
diff --git a/docs/ai-and-plans/features/docs-site/iterations/01-minima-theme.md b/docs/ai-and-plans/features/docs-site/iterations/01-minima-theme.md
new file mode 100644
index 000000000..f86dc5ab8
--- /dev/null
+++ b/docs/ai-and-plans/features/docs-site/iterations/01-minima-theme.md
@@ -0,0 +1,72 @@
+---
+feature: docs-site
+kind: iteration
+status: historical
+prs: [420]
+created: 2025-12-11
+---
+
+# Iteration 01: Minima theme for the documentation site
+
+## Goal
+
+Replace the default GitHub Pages look (Primer) with Minima 3, add the customization hooks, and
+document how to change the theme.
+
+## What the PR contained (2025-12-11)
+
+- `docs/_config.yml`: `remote_theme: jekyll/minima@1e8a445`, `baseurl`, the whitelisted plugins,
+  `minima.skin: auto`, commented examples for navigation and social links.
+- `docs/assets/css/style.scss` and `docs/_sass/minima/custom-*.scss`: the Minima 3 override hooks.
+- `docs/_includes/custom-head.html` and `sub-footer.html`: commented examples only.
+- `docs/THEME_CUSTOMIZATION.md`: a customization guide at the top of `docs/`.
+- `.github/workflows/deploy-documentation-preview.yml`: a "Known limitations" note in the preview
+  comment (shared `_config.yml`, broken asset links under the production `baseurl`).
+
+The same day, `main` removed PR preview deployments entirely (`c8ad1900`), which left the PR
+conflicting.
+
+## 2026-10-16: refresh
+
+- **Merged `main` into the branch.** The only conflict was the preview workflow: modified here,
+  deleted on `main`. Resolved by **accepting the deletion**. The note it added described the
+  limitations of a workflow that no longer exists. Keeping the workflow was rejected: re-adding
+  previews was not the goal of this PR and `main` removed them deliberately.
+- **Moved the guide into this feature folder.** `docs/THEME_CUSTOMIZATION.md` was published as a
+  page and showed up as "Theme Customization Guide" in the site header. It is contributor
+  documentation, so it was moved into this feature folder (later folded into [README.md](../README.md) when Minima was replaced; see [iteration 02](./02-just-the-docs.md)). Keeping it at the `docs/` root was
+  rejected for that reason.
+- **Refreshed the guide against current GitHub Pages.** Findings:
+  - The legacy build is still `github-pages` v232 (Jekyll 3.10.0, Minima 2.5.1). Minima 3 still
+    needs `remote_theme`.
+  - The Actions publishing route is mature (`upload-pages-artifact` v5, `deploy-pages` v5), but
+    hosted PR previews (`deploy-pages` `preview: true`) are still alpha and not public.
+  - The navigation example used `minima.nav_pages`, which the pinned commit does not read; it
+    reads `header_pages`. Recorded as an open gap rather than changing the config in this step.
+  - Minima `master` is about 30 functional commits ahead of the pin.
+  - The "Testing locally" section put the Gemfile inside `docs/`, which would publish it. The new
+    guide keeps it outside. (A local-only config that skipped `ai-and-plans/` was used at first;
+    it became unnecessary once the site exclusions below landed in `_config.yml`.)
+- **Verified locally.** Built with `github-pages` 232 on Ruby 3.3 (Windows). With `ai-and-plans/`
+  excluded, the build finishes in about 8 seconds and the landing page renders with the Minima
+  `auto` skin. A full build including `ai-and-plans/` did not finish within about 8 minutes and
+  produced many Liquid syntax warnings.
+- **Limited the site to user-facing content.** Operator decision: publish only `index.md`,
+  `user-manual/` and `release-notes/`. Everything else in `docs/` goes under `exclude` in
+  `_config.yml`. Alternatives considered:
+  - _Also publish `blog-posts/`._ Rejected by the operator.
+  - _Publish `user-manual/` only._ Rejected: the landing page is the table of contents, the
+    extension's Help view links to the root, and the README links to release notes.
+  - _Copy only the allowed folders in the deploy workflow._ Not chosen: an `exclude` list in
+    `_config.yml` is visible to the local preview, so the preview matches production.
+
+  Verification: build in about 7 seconds with no warnings; 30 user-manual and 14 release-notes
+  pages; all 24 distinct `microsoft.github.io/vscode-documentdb` URLs in the README,
+  `package.json`, the release notes and the user manual return 200 locally; `blog-posts/`,
+  `ai-and-plans/` and `localization` return 404. No link needed updating.
+
+## Not verified
+
+- The production build on GitHub (legacy Pages) with this theme.
+- Visual review of user manual and release notes pages beyond spot checks.
+- Dark skin rendering.
diff --git a/docs/ai-and-plans/features/docs-site/iterations/02-just-the-docs.md b/docs/ai-and-plans/features/docs-site/iterations/02-just-the-docs.md
new file mode 100644
index 000000000..a51addcb5
--- /dev/null
+++ b/docs/ai-and-plans/features/docs-site/iterations/02-just-the-docs.md
@@ -0,0 +1,103 @@
+---
+feature: docs-site
+kind: iteration
+status: active
+prs: [420]
+created: 2026-10-16
+---
+
+# Iteration 02: Just the Docs theme
+
+## Goal
+
+A documentation-style site (sidebar, search) that follows the OS light/dark setting, as an interim
+solution until the user manual moves to learn.microsoft.com. Cheap to keep, no content rewrite.
+
+## Theme choice
+
+Operator decision: **Just the Docs**, replacing Minima from [iteration 01](./01-minima-theme.md).
+The Minima files were dropped.
+
+Alternatives considered:
+
+- _Chirpy_ (operator's visual preference). Rejected: built around a blog (posts, tags, archives),
+  and needs Jekyll 4.3 plus `jekyll-archives`, which the GitHub Pages legacy build does not support.
+  It would also require switching publishing to a GitHub Actions build.
+- _DocFX modern template_ (closest to learn.microsoft.com: left TOC, right "In this article",
+  auto/light/dark). Rejected for now: not Jekyll, needs a .NET build in Actions, a Pages source
+  change and `toc.yml` files. Not worth it for an interim site.
+- _A Jekyll theme replicating learn.microsoft.com._ None found. Learn's look comes from its internal
+  publishing pipeline (`MicrosoftDocs/nosql-docs-pr` has `"template": []` in `docfx.json`).
+
+Just the Docs v0.12.0 works through `remote_theme` on the existing legacy build, so the deploy
+workflow is unchanged.
+
+## Work items
+
+1. **Sidebar without content edits.** Titles, parents and order live in `_config.yml` `defaults`;
+   two section pages (`user-manual.md`, `release-notes.md`) were added at the `docs/` root.
+   - Section pages first sat at `user-manual/index.md`; they then received the folder's
+     `parent` default and became their own children, so the sections vanished. Moved to the root.
+   - `jekyll-titles-from-headings` was tried and removed: pages start with a "Back to ..." line,
+     so the plugin finds no heading. Explicit titles were taken from each page's H1.
+   - Six user-manual pages are not in the landing page's table of contents (Atlas and index
+     management sub-pages). They are ordered right after their parent page.
+2. **OS dark mode.** Just the Docs only offers a fixed `color_scheme` (issue #234 is open). A
+   `head_custom.html` link loads the theme's dark stylesheet with
+   `media="(prefers-color-scheme: dark)"`. A JavaScript toggle (`jtd.setTheme`) was not chosen:
+   it needs a stored preference and flashes on load.
+3. **Microsoft styling, kept small.** Segoe UI, Cascadia Mono, `#0067b8` links and buttons in light
+   mode, semibold headings. The dark scheme keeps the theme's lighter link color for contrast.
+   - Locally the overrides were silently ignored. Cause: the preview passed `--source C:\local\...`
+     while the folder is `C:\Local`; in safe mode Jekyll then drops `docs/_sass` from the Sass load
+     path. A local-only quirk, documented in the README.
+4. **Search, breadcrumbs, GitHub and Marketplace links, "Edit this page on GitHub", back to top.**
+   Built-in theme options.
+
+## Outcome
+
+Verified locally with `github-pages` 232 (Jekyll 3.10, safe mode, Ruby 3.3 on Windows):
+
+- Build in about 20 seconds with no warnings.
+- Sidebar: Overview, User Manual (30 pages), Release Notes (14, newest first).
+- Light and dark rendering follow the emulated OS setting; computed link color, heading weight and
+  font family confirmed in both.
+- Search returns user manual and release notes results.
+- All 24 distinct `microsoft.github.io/vscode-documentdb` URLs used by the README, `package.json`,
+  the extension source, the landing page, user manual and release notes return 200. A crawl of the
+  built site found 94 distinct internal links, none broken.
+
+Not verified:
+
+- The live GitHub Pages build.
+- Mobile layout beyond the theme's defaults.
+- Every page visually; spot checks only.
+
+## Follow-up (2026-10-16): structured user manual
+
+Operator request: give the user manual the structure the landing page already describes, and
+improve page headers now that navigation exists. Constraint: no existing file moves, because
+outside links point at them; new files are allowed.
+
+- **Hierarchy in front matter, not folders.** Four new category pages (Connecting to Databases,
+  Data Management, Querying, AI Features) sit in `user-manual/`; existing pages are re-parented
+  through `parent`. Nesting follows the landing page's table of contents (Service Discovery, its
+  Kubernetes and MongoDB Atlas sub-pages, Local Instances, Manage Indexes).
+  - Where a page's old "Back to ..." line disagreed with the landing page (Copy Connection String
+    pointed to Service Discovery; Managed Identity to Connect with a URL), the landing page won.
+- **Navigation moved from `_config.yml` `defaults` into each page.** Rejected keeping it in
+  `_config.yml`: a new page would need edits in two places, and the explicit config titles only
+  existed to avoid touching content, which is now allowed.
+- **Headers:** the "Back to ..." blockquote, the `---` rule under it and any leading HTML comment
+  were replaced by front matter. Breadcrumbs cover the "back" role. H1s are unchanged.
+- **Sidebar titles** are shorter than the H1 where useful, unique (Just the Docs matches parents by
+  title) and self-explanatory, because they are also the browser tab title.
+- **Release notes** use `nav_order = major * 1000 + minor * 10` with `child_nav_order: desc`, so a
+  new release needs only its own front matter. The writing-release-notes skill and its examples now
+  produce this header. `CONTRIBUTING.md` strips front matter (`sed '1,/^---$/d'`) when posting
+  release notes as a GitHub discussion.
+
+Verified locally: the sidebar renders the intended tree, breadcrumbs follow it (for example User
+Manual > Connecting to Databases > Service Discovery > MongoDB Atlas > Browse and Connect to MongoDB
+Atlas), no "same title as its parent" warning, all 24 absolute URLs return 200 and none of the 97
+internal links are broken. The local build time rose from about 20 seconds to about 110 seconds.
diff --git a/docs/assets/images/documentdb-icon-dark.svg b/docs/assets/images/documentdb-icon-dark.svg
new file mode 100644
index 000000000..d5146b691
--- /dev/null
+++ b/docs/assets/images/documentdb-icon-dark.svg
@@ -0,0 +1,11 @@
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/assets/images/documentdb-icon-light.svg b/docs/assets/images/documentdb-icon-light.svg
new file mode 100644
index 000000000..50fb495b7
--- /dev/null
+++ b/docs/assets/images/documentdb-icon-light.svg
@@ -0,0 +1,11 @@
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/assets/js/page-toc.js b/docs/assets/js/page-toc.js
new file mode 100644
index 000000000..39335e7ab
--- /dev/null
+++ b/docs/assets/js/page-toc.js
@@ -0,0 +1,102 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+// "On this page" panel: lists the article's h2/h3 sections and highlights the one in view.
+// The theme has no right-side table of contents; layout lives in _sass/custom/custom.scss.
+(function () {
+    'use strict';
+
+    function init() {
+        var wrap = document.querySelector('.main-content-wrap');
+        var main = document.querySelector('#main-content main');
+        if (!wrap || !main) {
+            return;
+        }
+
+        var headings = Array.prototype.filter.call(main.querySelectorAll('h2[id], h3[id]'), function (h) {
+            return !h.closest('.no_toc') && !h.classList.contains('no_toc');
+        });
+        if (headings.length < 3) {
+            return;
+        }
+
+        var aside = document.createElement('aside');
+        aside.className = 'page-toc';
+        aside.setAttribute('aria-labelledby', 'page-toc-title');
+
+        var title = document.createElement('p');
+        title.className = 'page-toc-title';
+        title.id = 'page-toc-title';
+        title.textContent = 'On this page';
+        aside.appendChild(title);
+
+        var list = document.createElement('ul');
+
+        // First entry returns to the top of the article (the layout's #top element).
+        var introItem = document.createElement('li');
+        introItem.className = 'page-toc-intro';
+        var intro = document.createElement('a');
+        intro.href = '#top';
+        intro.textContent = 'Introduction';
+        intro.addEventListener('click', function (event) {
+            event.preventDefault();
+            window.scrollTo(0, 0);
+            history.replaceState(null, '', location.pathname + location.search);
+        });
+        introItem.appendChild(intro);
+        list.appendChild(introItem);
+
+        var links = headings.map(function (h) {
+            var item = document.createElement('li');
+            item.className = 'page-toc-' + h.tagName.toLowerCase();
+            var link = document.createElement('a');
+            link.href = '#' + h.id;
+            link.textContent = h.textContent.trim();
+            item.appendChild(link);
+            list.appendChild(item);
+            return link;
+        });
+        aside.appendChild(list);
+        wrap.appendChild(aside);
+
+        // The current section is the last heading that has scrolled into the top 40% of the
+        // viewport; before the first one, the introduction is current.
+        function update() {
+            var threshold = window.innerHeight * 0.4;
+            var current = null;
+            for (var i = 0; i < headings.length; i++) {
+                if (headings[i].getBoundingClientRect().top <= threshold) {
+                    current = i;
+                } else {
+                    break;
+                }
+            }
+            setActive(intro, current === null);
+            links.forEach(function (link, k) {
+                setActive(link, k === current);
+            });
+        }
+
+        function setActive(link, active) {
+            link.classList.toggle('active', active);
+            if (active) {
+                link.setAttribute('aria-current', 'location');
+            } else {
+                link.removeAttribute('aria-current');
+            }
+        }
+
+        window.addEventListener('scroll', update, { passive: true });
+        window.addEventListener('resize', update);
+
+        update();
+    }
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', init);
+    } else {
+        init();
+    }
+})();
diff --git a/docs/favicon.ico b/docs/favicon.ico
new file mode 100644
index 000000000..988024769
Binary files /dev/null and b/docs/favicon.ico differ
diff --git a/docs/index.md b/docs/index.md
index 5978e25f0..16f753da6 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,10 +1,11 @@
-# DocumentDB for VS Code
-
-[Install from Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-documentdb)
+---
+title: 'Overview'
+nav_order: 1
+---
 
-[Join the Discussion Board](https://github.com/microsoft/vscode-documentdb/discussions)
+# DocumentDB for VS Code
 
-[Report Issues](https://github.com/microsoft/vscode-documentdb/issues)
+[Install from Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-documentdb) · [Join the Discussion Board](https://github.com/microsoft/vscode-documentdb/discussions) · [Report Issues](https://github.com/microsoft/vscode-documentdb/issues)
 
 ---
 
@@ -12,9 +13,9 @@
 
 **DocumentDB for VS Code** helps you browse, manage, and query **DocumentDB** and **MongoDB** databases across any cloud, hybrid, or local environment.
 
-
DocumentDB with a Collection View and auto-completion

+
DocumentDB with a Collection View and auto-completion

 
-# Features
+## Features
 
 ### Universal DocumentDB and MongoDB Support
 
@@ -39,8 +40,6 @@ DocumentDB for VS Code focuses on providing developer productivity features with
 We believe in building in the open. All development, roadmap planning, and feature discussions happen publicly on GitHub.
 Your feedback, contributions, and ideas shape the future of the extension.
 
-# Table of Contents
-
 ## User Manual
 
 The User Manual provides guidance on using DocumentDB for VS Code. It contains detailed documentation for specific features and concepts. These documents provide additional context and examples for features you encounter while using the extension:
diff --git a/docs/release-notes.md b/docs/release-notes.md
new file mode 100644
index 000000000..b59935622
--- /dev/null
+++ b/docs/release-notes.md
@@ -0,0 +1,11 @@
+---
+title: Release Notes
+nav_order: 3
+child_nav_order: desc
+has_toc: true
+permalink: /release-notes/
+---
+
+# Release Notes
+
+What changed in each release of DocumentDB for VS Code.
diff --git a/docs/release-notes/0.10.md b/docs/release-notes/0.10.md
index 525479a81..0f211820b 100644
--- a/docs/release-notes/0.10.md
+++ b/docs/release-notes/0.10.md
@@ -1,5 +1,7 @@
-> **Release Notes** - [Back to Release Notes](../index.md#release-notes)
-
+---
+title: 'v0.10'
+parent: 'Release Notes'
+nav_order: 100
 ---
 
 # DocumentDB for VS Code Extension v0.10
@@ -14,7 +16,7 @@ This is the largest release of the extension so far, and it lands three major fe
 
 Getting a local database running should not be a research project. **DocumentDB Local** setup does the whole thing for you: it pulls the official [DocumentDB](https://documentdb.io/) image, creates a persistent Docker volume, waits until the database actually accepts connections, and saves a ready-to-use connection in the Connections view.
 
-
DocumentDB Local setup view on the Introduction step, showing the four-step Introduction, Configure, Set up, Done progression, with Set up DocumentDB Local highlighted under Your own DocumentDB in the Connections view

+
DocumentDB Local setup view on the Introduction step, showing the four-step Introduction, Configure, Set up, Done progression, with Set up DocumentDB Local highlighted under Your own DocumentDB in the Connections view

 
 Open the **Connections** view, expand **Your own DocumentDB**, and select **Set up DocumentDB Local**. On the happy path you keep the defaults, select **Start DocumentDB Local**, and then select **Open Connection**. Credentials are generated for you, sample data is included, and an available host port is picked automatically.
 
@@ -44,7 +46,7 @@ Pre-release refinements: [#841](https://github.com/microsoft/vscode-documentdb/p
 
 **MongoDB Atlas** joins Azure and Kubernetes as a first-class Service Discovery provider. Browse your Atlas organizations, projects, and clusters directly in the extension, then save any cluster as a regular DocumentDB connection without copying endpoints by hand.
 
-
Add a MongoDB Atlas connection view on the Choose method step, offering a recommended Service Account option and an API Key option, with Sign in to view MongoDB Atlas clusters highlighted under MongoDB Atlas in the Service Discovery view

+
Add a MongoDB Atlas connection view on the Choose method step, offering a recommended Service Account option and an API Key option, with Sign in to view MongoDB Atlas clusters highlighted under MongoDB Atlas in the Service Discovery view

 
 You can start from the **Service Discovery** view, or from **New Connection** > **Service Discovery** > **MongoDB Atlas**.
 
@@ -80,7 +82,7 @@ Pre-release refinements: [#799](https://github.com/microsoft/vscode-documentdb/p
 
 Indexes are where query performance is won or lost, and until now you had to leave the extension to work with them. Collection View gains an **Indexes** tab, sitting between **Results** and **Query Insights**, so index work happens next to the queries it affects. You can also double-click the collection's **Indexes** node in the Explorer to open Collection View directly on that tab.
 
-
Indexes tab in Collection View showing Total Indexes, Total Size, Total Usage, and Unused Indexes metrics above a filterable index table with type badges, size bars, usage counts, and per-row delete and hide actions

+
Indexes tab in Collection View showing Total Indexes, Total Size, Total Usage, and Unused Indexes metrics above a filterable index table with type badges, size bars, usage counts, and per-row delete and hide actions

 
 #### Inspect what you have
 
diff --git a/docs/release-notes/0.11.md b/docs/release-notes/0.11.md
index 56631a51d..a4ea62f96 100644
--- a/docs/release-notes/0.11.md
+++ b/docs/release-notes/0.11.md
@@ -1,5 +1,7 @@
-> **Release Notes** - [Back to Release Notes](../index.md#release-notes)
-
+---
+title: 'v0.11'
+parent: 'Release Notes'
+nav_order: 110
 ---
 
 # DocumentDB for VS Code Extension v0.11
@@ -12,7 +14,7 @@ We are excited to announce **DocumentDB for VS Code Extension v0.11**. Explore y
 
 We are introducing a major new feature: the **Cluster Dashboard**. Opened from a cluster tree node, it gives you a focused inventory of everything a cluster holds, without leaving VS Code. The dashboard shows an overview with cluster identity, connection status, round-trip time, and Azure high-availability facts, plus a details view with server and other metadata you can copy directly.
 
-
Cluster Dashboard for Contoso Production showing connected and high availability status, cluster storage and document metrics, and a filterable database inventory with storage, data, index, collection, and document statistics

+
Cluster Dashboard for Contoso Production showing connected and high availability status, cluster storage and document metrics, and a filterable database inventory with storage, data, index, collection, and document statistics

 
 Below the header, a database and collection inventory reports storage, data, index, collection, and document statistics where the server provides them, with sorting, filtering, drill-in, refresh, create, and delete actions. Open Shell and Copy Connection String are one click away, and a failed or partial read shows a clear retry state instead of a guessed number.
 
diff --git a/docs/release-notes/0.2.1.md b/docs/release-notes/0.2.1.md
index 036c4ca9b..43abded55 100644
--- a/docs/release-notes/0.2.1.md
+++ b/docs/release-notes/0.2.1.md
@@ -1,7 +1,7 @@
-
-
-> **Release Notes** — [Back to Release Notes](../index#release-notes)
-
+---
+title: 'v0.2.1'
+parent: 'Release Notes'
+nav_order: 21
 ---
 
 # DocumentDB for VS Code Extension v0.2.1
diff --git a/docs/release-notes/0.2.2.md b/docs/release-notes/0.2.2.md
index ec24e5f76..37e17dde1 100644
--- a/docs/release-notes/0.2.2.md
+++ b/docs/release-notes/0.2.2.md
@@ -1,7 +1,7 @@
-
-
-> **Release Notes** — [Back to Release Notes](../index#release-notes)
-
+---
+title: 'v0.2.2'
+parent: 'Release Notes'
+nav_order: 22
 ---
 
 # DocumentDB for VS Code Extension v0.2.2
diff --git a/docs/release-notes/0.2.3.md b/docs/release-notes/0.2.3.md
index 841883c57..26f55577c 100644
--- a/docs/release-notes/0.2.3.md
+++ b/docs/release-notes/0.2.3.md
@@ -1,7 +1,7 @@
-
-
-> **Release Notes** — [Back to Release Notes](../index#release-notes)
-
+---
+title: 'v0.2.3'
+parent: 'Release Notes'
+nav_order: 23
 ---
 
 # DocumentDB for VS Code Extension v0.2.3
diff --git a/docs/release-notes/0.2.4.md b/docs/release-notes/0.2.4.md
index 5a4a86707..6916ae2e6 100644
--- a/docs/release-notes/0.2.4.md
+++ b/docs/release-notes/0.2.4.md
@@ -1,7 +1,7 @@
-
-
-> **Release Notes** — [Back to Release Notes](../index#release-notes)
-
+---
+title: 'v0.2.4'
+parent: 'Release Notes'
+nav_order: 24
 ---
 
 # DocumentDB for VS Code Extension v0.2.4
diff --git a/docs/release-notes/0.3.md b/docs/release-notes/0.3.md
index 32e8385a2..984849aa9 100644
--- a/docs/release-notes/0.3.md
+++ b/docs/release-notes/0.3.md
@@ -1,7 +1,7 @@
-
-
-> **Release Notes** — [Back to Release Notes](../index#release-notes)
-
+---
+title: 'v0.3'
+parent: 'Release Notes'
+nav_order: 30
 ---
 
 # DocumentDB for VS Code Extension v0.3
@@ -21,7 +21,7 @@ The available authentication methods are:
 - **Username and Password**: The traditional authentication method.
 - **Entra ID for Azure DocumentDB**: Authenticate using your Microsoft Entra ID credentials.
 
-
Authentication Method Selection

+
Authentication Method Selection

 
 #### **Service Discovery**
 
diff --git a/docs/release-notes/0.4.md b/docs/release-notes/0.4.md
index 20695feb5..2007a76d6 100644
--- a/docs/release-notes/0.4.md
+++ b/docs/release-notes/0.4.md
@@ -1,14 +1,14 @@
-
-
-> **Release Notes** — [Back to Release Notes](../index#release-notes)
-
+---
+title: 'v0.4'
+parent: 'Release Notes'
+nav_order: 40
 ---
 
 # DocumentDB for VS Code Extension v0.4
 
 We are excited to announce the release of **DocumentDB for VS Code Extension v0.4**. This is a landmark update that introduces deep integration with the Azure ecosystem, adds powerful new service discovery capabilities, and aligns our branding with the official [DocumentDB](https://documentdb.io) identity.
 
-
DocumentDB Logo

+
DocumentDB Logo

 
 This release improves how developers working with Azure discover, connect to, and manage their MongoDB-compatible databases, all from within a unified VS Code experience.
 
@@ -30,7 +30,7 @@ This collaboration provides a single, authoritative view for all your Azure reso
 - **Coordinated Orchestration**: The Azure Resources extension now directs which extension manages which resource, ensuring a stable and conflict-free experience.
 - **Automatic Migration**: Existing MongoDB connections are automatically migrated for an efficient transition.
 
-
Authentication Method Selection

+
Authentication Method Selection

 
 ### 2️⃣ **Service Discovery for Azure Cosmos DB for MongoDB (RU)** ([#244](https://github.com/microsoft/vscode-documentdb/issues/244))
 
diff --git a/docs/release-notes/0.5.md b/docs/release-notes/0.5.md
index 9a980c4fa..37dacb5da 100644
--- a/docs/release-notes/0.5.md
+++ b/docs/release-notes/0.5.md
@@ -1,7 +1,7 @@
-
-
-> **Release Notes** — [Back to Release Notes](../index.md#release-notes)
-
+---
+title: 'v0.5'
+parent: 'Release Notes'
+nav_order: 50
 ---
 
 # DocumentDB for VS Code Extension v0.5
diff --git a/docs/release-notes/0.6.md b/docs/release-notes/0.6.md
index 3e975fe27..dc7eee09e 100644
--- a/docs/release-notes/0.6.md
+++ b/docs/release-notes/0.6.md
@@ -1,5 +1,7 @@
-> **Release Notes** — [Back to Release Notes](../index.md#release-notes)
-
+---
+title: 'v0.6'
+parent: 'Release Notes'
+nav_order: 60
 ---
 
 # DocumentDB for VS Code Extension v0.6
@@ -12,7 +14,7 @@ We are excited to announce the release of **DocumentDB for VS Code Extension v0.
 
 We are introducing a major new feature: **Query Insights with Performance Advisor**. This powerful tool helps you understand and optimize your queries directly within VS Code. When you run a `find` query against your DocumentDB or MongoDB API database, a new **"Query Insights"** tab appears, providing a three-stage analysis of your query's performance.
 
-
Authentication Method Selection

+
Authentication Method Selection

 
 - **Stage 1: Initial Performance View**
   The first stage provides an immediate, low-cost static analysis of your query. It visualizes the query plan, showing how the database intends to execute your query. This helps you understand performance bottlenecks and the query's processing stages without re-running it.
@@ -49,7 +51,7 @@ We've enhanced the query authoring experience to support more sophisticated quer
 
 The `projection` and `sort` fields also support the same rich autocompletion that was previously available for the `filter` field.
 
-
Authentication Method Selection

+
Authentication Method Selection

 
 ### ⭐ Index Management from the Tree View
 
@@ -57,7 +59,7 @@ Managing your indexes is now easier and more intuitive than ever. You can now `d
 
 Hovering over an index will show you its details, and the context menu provides the available management operations. This direct workflow helps you maintain your indexes efficiently right from the explorer.
 
-
Authentication Method Selection

+
Authentication Method Selection

 
 ## Key Fixes and Improvements
 
diff --git a/docs/release-notes/0.7.md b/docs/release-notes/0.7.md
index 6567a4b91..af6a3003a 100644
--- a/docs/release-notes/0.7.md
+++ b/docs/release-notes/0.7.md
@@ -1,5 +1,7 @@
-> **Release Notes** — [Back to Release Notes](../index.md#release-notes)
-
+---
+title: 'v0.7'
+parent: 'Release Notes'
+nav_order: 70
 ---
 
 # DocumentDB for VS Code Extension v0.7
@@ -14,7 +16,7 @@ It includes **Lightweight Data Migration** for collection copying, adds **Folder
 
 We're introducing **Lightweight Data Migration** (also known as "**Collection Copy-and-Paste**"). This feature enables you to copy collections and paste them into new or existing collections, across different databases or even different servers - all directly within VS Code.
 
-
Lightweight Data Migration Overview

+
Copy and paste in three steps: 1, right-click the source collection and choose Copy Collection; 2, right-click the target and choose Paste Collection; 3, choose how to handle conflicts, then paste

 
 Designed for **smaller-to-medium datasets** that can be streamed through your local machine, this feature simplifies moving data between environments. It's useful for:
 
@@ -42,7 +44,7 @@ When pasting into an existing collection, the migration wizard offers four confl
 
 Managing multiple database connections is now easier with hierarchical folder organization. We've redesigned the **Connections View** to support **hierarchical folder organization**, converting what was previously a flat list into an organized system.
 
-
Folder Management in Connections View

+
Folder Management in Connections View

 
 **Key Capabilities**
 
diff --git a/docs/release-notes/0.8.md b/docs/release-notes/0.8.md
index 841d52e2f..e6438ceac 100644
--- a/docs/release-notes/0.8.md
+++ b/docs/release-notes/0.8.md
@@ -1,5 +1,7 @@
-> **Release Notes** : [Back to Release Notes](../index.md#release-notes)
-
+---
+title: 'v0.8'
+parent: 'Release Notes'
+nav_order: 80
 ---
 
 # DocumentDB for VS Code Extension v0.8
@@ -16,7 +18,7 @@ The filter, project, sort, and aggregation editors in the Collection View now un
 
 The editor knows your schema and guides you through every keystroke, so you no longer need to look up operator syntax or guess between similar operators like `$gte` and `$gt`.
 
-
Collection View autocompletion showing true/false suggestions for a boolean field, followed by comparison operators sorted by relevance

+
Collection View autocompletion showing true/false suggestions for a boolean field, followed by comparison operators sorted by relevance

 
 In this example, the field `additionalInfo.isFamilyFriendly` is a boolean. The editor suggests `true` and `false` first, followed by comparison operators. Each suggestion shows its category (boolean literal, comparison, projection, element) and the documentation panel at the bottom describes the selected item.
 
@@ -33,7 +35,7 @@ In this example, the field `additionalInfo.isFamilyFriendly` is a boolean. The e
 
 The Query Playground introduces a `.documentdb.js` file type that lets you write and run JavaScript scripts against your cluster, directly inside VS Code. Think of it as a notebook-style scratchpad for DocumentDB.
 
-
Query Playground showing CodeLens buttons: Run All at the top, and Run, Collection View, and Shell links on each block

+
Query Playground showing CodeLens buttons: Run All at the top, and Run, Collection View, and Shell links on each block

 
 The screenshot shows a `.documentdb.js` file connected to a cluster. The **Run All** CodeLens at the top runs the entire file, while each block has its own **Run** button plus shortcuts to open the same query in the **Collection View** or the **Interactive Shell**.
 
@@ -54,7 +56,7 @@ Just install the extension and start writing queries. No platform-specific heada
 
 A full REPL terminal embedded in VS Code, giving you a shell experience fully integrated with the extension's connection management. Open it from any cluster, database, or collection node in the tree view, and you're immediately connected and ready to explore.
 
-
Interactive Shell showing tab completion for collection methods and ghost text suggesting a field name from the local schema

+
Interactive Shell showing tab completion for collection methods and ghost text suggesting a field name from the local schema

 
 The screenshot shows two key features: tab completion suggesting `find()`, `findOne()`, and other collection methods after typing `db.restaurants.find`, and ghost text suggesting the field name `reviews` after the user typed `re` in a query. The field suggestion comes from schema information gathered locally as you browse and query your data.
 
@@ -76,7 +78,7 @@ All three query surfaces (Collection View, Query Playground, and Interactive She
 
 Every collection node in the tree view now shows three inline action buttons for instant access:
 
-
Inline action buttons on a collection node: Open Collection View, New Query Playground, Open Interactive Shell

+
Inline action buttons on a collection node: Open Collection View, New Query Playground, Open Interactive Shell

 
 From left to right: **Open Collection View**, **New Query Playground**, and **Open Interactive Shell**. The same actions are available through right-click context menus on database and collection nodes.
 
diff --git a/docs/release-notes/0.9.md b/docs/release-notes/0.9.md
index 33a786ec9..73f793803 100644
--- a/docs/release-notes/0.9.md
+++ b/docs/release-notes/0.9.md
@@ -1,5 +1,7 @@
-> **Release Notes** - [Back to Release Notes](../index.md#release-notes)
-
+---
+title: 'v0.9'
+parent: 'Release Notes'
+nav_order: 90
 ---
 
 # DocumentDB for VS Code Extension v0.9
@@ -14,7 +16,7 @@ This release expands the extension's multicloud reach with first-class **Kuberne
 
 We are introducing **Kubernetes service discovery**, bringing true multicloud and hybrid-cloud support to the extension. If you run DocumentDB-compatible clusters in any Kubernetes environment (AKS, EKS, GKE, OpenShift, or local clusters like kind, minikube, k3s, or Docker Desktop), the extension can now find them automatically and connect you without manual configuration.
 
-
Kubernetes Service Discovery tree showing two kubeconfig sources, a context expanded into namespaces, and discovered DocumentDB targets with connectivity indicators

+
Kubernetes Service Discovery tree showing two kubeconfig sources, a context expanded into namespaces, and discovered DocumentDB targets with connectivity indicators

 
 #### Multiple kubeconfig sources
 
@@ -25,7 +27,7 @@ The new **Kubernetes Clusters** root in the Discovery view lets you register one
 - **Paste kubeconfig YAML…**: paste YAML directly; a copy is saved in VS Code Secret Storage.
 - **Drag-and-drop**: drop a kubeconfig file onto the Discovery view; you are asked to confirm (with an option to preview the file) before it is imported.
 
-
Select kubeconfig source quick pick showing the three options: Default kubeconfig, Kubeconfig file…, and Paste kubeconfig YAML…

+
Select kubeconfig source quick pick showing the three options: Default kubeconfig, Kubeconfig file…, and Paste kubeconfig YAML…

 
 #### Auto-discovery and DocumentDB Kubernetes Operator awareness
 
@@ -67,7 +69,7 @@ For the full feature reference, see the [Kubernetes Service Discovery](https://m
 
 **Query Insights** now streams AI-generated recommendations progressively, eliminating the ~15-second blank wait that existed before. After clicking **Get AI Performance Insights**, results appear as they are generated: you can read the summary while individual index recommendations are still being produced.
 
-
Query Insights panel mid-stream: summary text appearing line by line, one completed recommendation card, and a second card being progressively revealed

+
Query Insights panel mid-stream: summary text appearing line by line, one completed recommendation card, and a second card being progressively revealed

 
 Previously, the extension buffered the entire AG-generated response (which took 10–20 s to generate) before parsing and rendering it all at once. Users had no signal that anything was happening past the first second. The new experience connects the model's natural streaming output directly to the UI:
 
diff --git a/docs/release-notes/1.0.md b/docs/release-notes/1.0.md
index 5d88fda56..eac000430 100644
--- a/docs/release-notes/1.0.md
+++ b/docs/release-notes/1.0.md
@@ -1,5 +1,7 @@
-> **Release Notes** - [Back to Release Notes](../index.md#release-notes)
-
+---
+title: 'v1.0'
+parent: 'Release Notes'
+nav_order: 1000
 ---
 
 # DocumentDB for VS Code Extension v1.0
diff --git a/docs/release-notes/images/0.10.0_documentdb_local_dark.png b/docs/release-notes/images/0.10.0_documentdb_local_dark.png
new file mode 100644
index 000000000..2e0529347
Binary files /dev/null and b/docs/release-notes/images/0.10.0_documentdb_local_dark.png differ
diff --git a/docs/release-notes/images/0.10.0_index_management_dark.png b/docs/release-notes/images/0.10.0_index_management_dark.png
new file mode 100644
index 000000000..702d8621a
Binary files /dev/null and b/docs/release-notes/images/0.10.0_index_management_dark.png differ
diff --git a/docs/release-notes/images/0.10.0_mongodb_atlas_discovery_dark.png b/docs/release-notes/images/0.10.0_mongodb_atlas_discovery_dark.png
new file mode 100644
index 000000000..19596c7b4
Binary files /dev/null and b/docs/release-notes/images/0.10.0_mongodb_atlas_discovery_dark.png differ
diff --git a/docs/release-notes/images/0.11.0_cluster_dashboard_dark.png b/docs/release-notes/images/0.11.0_cluster_dashboard_dark.png
new file mode 100644
index 000000000..0add6eb9d
Binary files /dev/null and b/docs/release-notes/images/0.11.0_cluster_dashboard_dark.png differ
diff --git a/docs/release-notes/images/0.3.0_authentication_methods_dark.png b/docs/release-notes/images/0.3.0_authentication_methods_dark.png
new file mode 100644
index 000000000..193ed7aea
Binary files /dev/null and b/docs/release-notes/images/0.3.0_authentication_methods_dark.png differ
diff --git a/docs/release-notes/images/0.4.0_azure_resources_dark.png b/docs/release-notes/images/0.4.0_azure_resources_dark.png
new file mode 100644
index 000000000..f04d18e3a
Binary files /dev/null and b/docs/release-notes/images/0.4.0_azure_resources_dark.png differ
diff --git a/docs/release-notes/images/0.4.0_documentdb-logo_dark.png b/docs/release-notes/images/0.4.0_documentdb-logo_dark.png
new file mode 100644
index 000000000..8f242a5cb
Binary files /dev/null and b/docs/release-notes/images/0.4.0_documentdb-logo_dark.png differ
diff --git a/docs/release-notes/images/0.6.0_index_management_dark.png b/docs/release-notes/images/0.6.0_index_management_dark.png
new file mode 100644
index 000000000..596c62c36
Binary files /dev/null and b/docs/release-notes/images/0.6.0_index_management_dark.png differ
diff --git a/docs/release-notes/images/0.6.0_project_sort_skip_limit_dark.png b/docs/release-notes/images/0.6.0_project_sort_skip_limit_dark.png
new file mode 100644
index 000000000..ce547d06b
Binary files /dev/null and b/docs/release-notes/images/0.6.0_project_sort_skip_limit_dark.png differ
diff --git a/docs/release-notes/images/0.6.0_query_insights_dark.png b/docs/release-notes/images/0.6.0_query_insights_dark.png
new file mode 100644
index 000000000..46ba43c26
Binary files /dev/null and b/docs/release-notes/images/0.6.0_query_insights_dark.png differ
diff --git a/docs/release-notes/images/0.7.0_copy_and_paste.png b/docs/release-notes/images/0.7.0_copy_and_paste.png
deleted file mode 100644
index 7277773f8..000000000
Binary files a/docs/release-notes/images/0.7.0_copy_and_paste.png and /dev/null differ
diff --git a/docs/release-notes/images/0.7.0_folder_management_dark.png b/docs/release-notes/images/0.7.0_folder_management_dark.png
new file mode 100644
index 000000000..fba785999
Binary files /dev/null and b/docs/release-notes/images/0.7.0_folder_management_dark.png differ
diff --git a/docs/release-notes/images/0.8.0_autocompletion_dark.png b/docs/release-notes/images/0.8.0_autocompletion_dark.png
new file mode 100644
index 000000000..645c8cb92
Binary files /dev/null and b/docs/release-notes/images/0.8.0_autocompletion_dark.png differ
diff --git a/docs/release-notes/images/0.8.0_inline_action_buttons_dark.png b/docs/release-notes/images/0.8.0_inline_action_buttons_dark.png
new file mode 100644
index 000000000..6ca40e171
Binary files /dev/null and b/docs/release-notes/images/0.8.0_inline_action_buttons_dark.png differ
diff --git a/docs/release-notes/images/0.8.0_interactive_shell_dark.png b/docs/release-notes/images/0.8.0_interactive_shell_dark.png
new file mode 100644
index 000000000..0a1bb2060
Binary files /dev/null and b/docs/release-notes/images/0.8.0_interactive_shell_dark.png differ
diff --git a/docs/release-notes/images/0.8.0_query_playground_dark.png b/docs/release-notes/images/0.8.0_query_playground_dark.png
new file mode 100644
index 000000000..e837c6e76
Binary files /dev/null and b/docs/release-notes/images/0.8.0_query_playground_dark.png differ
diff --git a/docs/release-notes/images/0.9.0_kubernetes_add_source_dark.png b/docs/release-notes/images/0.9.0_kubernetes_add_source_dark.png
new file mode 100644
index 000000000..dafe21245
Binary files /dev/null and b/docs/release-notes/images/0.9.0_kubernetes_add_source_dark.png differ
diff --git a/docs/release-notes/images/0.9.0_kubernetes_discovery_dark.png b/docs/release-notes/images/0.9.0_kubernetes_discovery_dark.png
new file mode 100644
index 000000000..60bff5611
Binary files /dev/null and b/docs/release-notes/images/0.9.0_kubernetes_discovery_dark.png differ
diff --git a/docs/release-notes/images/0.9.0_query_insights_streaming_dark.png b/docs/release-notes/images/0.9.0_query_insights_streaming_dark.png
new file mode 100644
index 000000000..9afb1ad1d
Binary files /dev/null and b/docs/release-notes/images/0.9.0_query_insights_streaming_dark.png differ
diff --git a/docs/user-manual.md b/docs/user-manual.md
new file mode 100644
index 000000000..a1068e262
--- /dev/null
+++ b/docs/user-manual.md
@@ -0,0 +1,10 @@
+---
+title: User Manual
+nav_order: 2
+has_toc: true
+permalink: /user-manual/
+---
+
+# User Manual
+
+Guides for connecting to databases, managing data and querying with DocumentDB for VS Code.
diff --git a/docs/user-manual/ai-features.md b/docs/user-manual/ai-features.md
new file mode 100644
index 000000000..0217b9881
--- /dev/null
+++ b/docs/user-manual/ai-features.md
@@ -0,0 +1,9 @@
+---
+title: 'AI Features'
+parent: 'User Manual'
+nav_order: 4
+---
+
+# AI Features
+
+How AI features in the extension choose a model and how usage is billed.
diff --git a/docs/user-manual/ai-utility-model.md b/docs/user-manual/ai-utility-model.md
index 71932b651..22e382f33 100644
--- a/docs/user-manual/ai-utility-model.md
+++ b/docs/user-manual/ai-utility-model.md
@@ -1,5 +1,7 @@
-> **User Manual** - [Back to User Manual](../index#user-manual)
-
+---
+title: 'AI Model and Billing'
+parent: 'AI Features'
+nav_order: 1
 ---
 
 # AI Features: Utility Model and Pricing
diff --git a/docs/user-manual/collection-view-index-management-troubleshooting.md b/docs/user-manual/collection-view-index-management-troubleshooting.md
index 79e468449..d61419b4f 100644
--- a/docs/user-manual/collection-view-index-management-troubleshooting.md
+++ b/docs/user-manual/collection-view-index-management-troubleshooting.md
@@ -1,5 +1,7 @@
-> **User Manual** | [Manage Indexes in Collection View](./collection-view-index-management) | [Back to User Manual](../index#user-manual)
-
+---
+title: 'Troubleshoot Index Management'
+parent: 'Manage Indexes'
+nav_order: 3
 ---
 
 # Troubleshoot Index Management
diff --git a/docs/user-manual/collection-view-index-management.md b/docs/user-manual/collection-view-index-management.md
index 6146ce2d1..4a964a0ea 100644
--- a/docs/user-manual/collection-view-index-management.md
+++ b/docs/user-manual/collection-view-index-management.md
@@ -1,5 +1,8 @@
-> **User Manual** | [Back to User Manual](../index#user-manual)
-
+---
+title: 'Manage Indexes'
+parent: 'Data Management'
+nav_order: 1
+has_toc: false
 ---
 
 # Manage Indexes in Collection View
diff --git a/docs/user-manual/collection-view-querying.md b/docs/user-manual/collection-view-querying.md
index f64ab2cb8..7830929ea 100644
--- a/docs/user-manual/collection-view-querying.md
+++ b/docs/user-manual/collection-view-querying.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to User Manual](../index#user-manual)
-
+---
+title: 'Querying in Collection View'
+parent: 'Querying'
+nav_order: 1
 ---
 
 # Collection View: Querying
@@ -17,7 +19,7 @@ There are several ways to open a collection in the Collection View:
 3. **From the Interactive Shell**: Click the `↗ Collection View` link that appears after query results.
 4. **From the Query Playground**: Use the CodeLens link to open the referenced collection.
 
-
Inline action buttons on a collection node: Open Collection View, New Query Playground, Open Interactive Shell

+
Inline action buttons on a collection node: Open Collection View, New Query Playground, Open Interactive Shell

 
 The three inline icons next to each collection node are (from left to right): **Open Collection View**, **New Query Playground**, and **Open Interactive Shell**.
 
@@ -143,7 +145,7 @@ The extension doesn't just know field names, it also knows their types. This kno
 - After a **string** field: `$regex` and `$in` are prioritized
 - After a **boolean** field: `true`/`false` value suggestions appear at the top
 
-
Autocompletion for a boolean field showing true/false values first, then comparison operators

+
Autocompletion for a boolean field showing true/false values first, then comparison operators

 
 In this example, the field `additionalInfo.isFamilyFriendly` is a boolean. The editor suggests `true` and `false` first, followed by comparison operators sorted by relevance. The documentation panel at the bottom describes the selected item.
 
diff --git a/docs/user-manual/collection-view-vector-indexes.md b/docs/user-manual/collection-view-vector-indexes.md
index 378fed048..a265d71b4 100644
--- a/docs/user-manual/collection-view-vector-indexes.md
+++ b/docs/user-manual/collection-view-vector-indexes.md
@@ -1,5 +1,7 @@
-> **User Manual** | [Manage Indexes in Collection View](./collection-view-index-management) | [Back to User Manual](../index#user-manual)
-
+---
+title: 'Vector Indexes'
+parent: 'Manage Indexes'
+nav_order: 2
 ---
 
 # Vector Indexes in Collection View
diff --git a/docs/user-manual/collection-view-wildcard-indexes.md b/docs/user-manual/collection-view-wildcard-indexes.md
index 17e3d7e63..fa5487d93 100644
--- a/docs/user-manual/collection-view-wildcard-indexes.md
+++ b/docs/user-manual/collection-view-wildcard-indexes.md
@@ -1,5 +1,7 @@
-> **User Manual** | [Manage Indexes in Collection View](./collection-view-index-management) | [Back to User Manual](../index#user-manual)
-
+---
+title: 'Wildcard Indexes'
+parent: 'Manage Indexes'
+nav_order: 1
 ---
 
 # Wildcard Indexes in Collection View
diff --git a/docs/user-manual/connect-with-managed-identity.md b/docs/user-manual/connect-with-managed-identity.md
index db55d2a81..152d9be18 100644
--- a/docs/user-manual/connect-with-managed-identity.md
+++ b/docs/user-manual/connect-with-managed-identity.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to Connecting with a URL](./how-to-construct-url) | [Back to User Manual](../index#user-manual)
-
+---
+title: 'Connect with a Managed Identity'
+parent: 'Connecting to Databases'
+nav_order: 2
 ---
 
 # Connect with a Managed Identity
diff --git a/docs/user-manual/connecting-to-databases.md b/docs/user-manual/connecting-to-databases.md
new file mode 100644
index 000000000..ed7e35a34
--- /dev/null
+++ b/docs/user-manual/connecting-to-databases.md
@@ -0,0 +1,9 @@
+---
+title: 'Connecting to Databases'
+parent: 'User Manual'
+nav_order: 1
+---
+
+# Connecting to Databases
+
+Connect to DocumentDB and MongoDB databases: with a URL or connection string, through service discovery in Azure, Kubernetes and MongoDB Atlas, or to a database running on your machine.
diff --git a/docs/user-manual/copy-and-paste.md b/docs/user-manual/copy-and-paste.md
index 75f36b121..da909505c 100644
--- a/docs/user-manual/copy-and-paste.md
+++ b/docs/user-manual/copy-and-paste.md
@@ -1,7 +1,7 @@
-
-
-> **Learn More** - [Back to Learn More Index](../index#user-manual)
-
+---
+title: 'Copy and Paste Collections'
+parent: 'Data Management'
+nav_order: 3
 ---
 
 # Copy and Paste Collections
@@ -23,7 +23,7 @@ The **Copy and Paste** feature in DocumentDB for VS Code provides a convenient w
 
 The copy-and-paste process is designed to be efficient for smaller collections by streaming data through your local machine. Here’s a step-by-step breakdown of the process:
 
-
Copy-and-Paste process that uses a local sistem

+
Copy and paste streams documents from the source collection into an in-memory buffer in VS Code on your machine, then bulk writes them to the target collection, repeating until every document is copied

 
 1.  **Data Streaming**: The extension initiates a stream from the source collection, reading documents one by one.
 2.  **In-Memory Buffering**: Documents are collected into a buffer in your computer's memory.
@@ -250,7 +250,7 @@ A final summary is displayed, showing the source, the target, and the chosen con
 
 The copy-and-paste feature is a developer convenience, not a dedicated migration tool. For production-level data migrations, especially those involving large datasets, complex transformations, or the need for data verification, a specialized migration service is strongly recommended.
 
-
Copy-and-Paste process that uses a local sistem

+
A dedicated migration service in the data center moves data directly from the source cluster to the target cluster, while your machine only monitors progress

 
 Dedicated migration tools offer significant advantages:
 
diff --git a/docs/user-manual/copy-connection-string.md b/docs/user-manual/copy-connection-string.md
index d3e36fb06..be62a6f7f 100644
--- a/docs/user-manual/copy-connection-string.md
+++ b/docs/user-manual/copy-connection-string.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to Service Discovery](./service-discovery) | [Back to User Manual](../index#user-manual)
-
+---
+title: 'Copy Connection String'
+parent: 'Data Management'
+nav_order: 4
 ---
 
 # Copy Connection String
diff --git a/docs/user-manual/data-management.md b/docs/user-manual/data-management.md
new file mode 100644
index 000000000..e34f4e43f
--- /dev/null
+++ b/docs/user-manual/data-management.md
@@ -0,0 +1,9 @@
+---
+title: 'Data Management'
+parent: 'User Manual'
+nav_order: 2
+---
+
+# Data Management
+
+Manage indexes, copy collections between connections, migrate data and share connection strings.
diff --git a/docs/user-manual/data-migrations.md b/docs/user-manual/data-migrations.md
index c8ed4dc40..9ab955422 100644
--- a/docs/user-manual/data-migrations.md
+++ b/docs/user-manual/data-migrations.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to User Manual](../index#user-manual)
-
+---
+title: 'Data Migrations (Experimental)'
+parent: 'Data Management'
+nav_order: 2
 ---
 
 # Data Migrations in DocumentDB for VS Code
diff --git a/docs/user-manual/how-to-construct-url.md b/docs/user-manual/how-to-construct-url.md
index 476aee56b..195705db1 100644
--- a/docs/user-manual/how-to-construct-url.md
+++ b/docs/user-manual/how-to-construct-url.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to User Manual](../index#user-manual)
-
+---
+title: 'Connect with a URL'
+parent: 'Connecting to Databases'
+nav_order: 1
 ---
 
 # How to Construct a URL That Opens the Extension
diff --git a/docs/user-manual/images/autocompletion-boolean-field_dark.png b/docs/user-manual/images/autocompletion-boolean-field_dark.png
new file mode 100644
index 000000000..645c8cb92
Binary files /dev/null and b/docs/user-manual/images/autocompletion-boolean-field_dark.png differ
diff --git a/docs/user-manual/images/copy-and-paste-no-local-system.png b/docs/user-manual/images/copy-and-paste-no-local-system.png
index 804a94071..6f31ad4ad 100644
Binary files a/docs/user-manual/images/copy-and-paste-no-local-system.png and b/docs/user-manual/images/copy-and-paste-no-local-system.png differ
diff --git a/docs/user-manual/images/copy-and-paste-no-local-system_dark.png b/docs/user-manual/images/copy-and-paste-no-local-system_dark.png
new file mode 100644
index 000000000..cc03d804f
Binary files /dev/null and b/docs/user-manual/images/copy-and-paste-no-local-system_dark.png differ
diff --git a/docs/user-manual/images/copy-and-paste-via-local-system.png b/docs/user-manual/images/copy-and-paste-via-local-system.png
index 3b914f598..ca578af69 100644
Binary files a/docs/user-manual/images/copy-and-paste-via-local-system.png and b/docs/user-manual/images/copy-and-paste-via-local-system.png differ
diff --git a/docs/user-manual/images/copy-and-paste-via-local-system_dark.png b/docs/user-manual/images/copy-and-paste-via-local-system_dark.png
new file mode 100644
index 000000000..ee6c39474
Binary files /dev/null and b/docs/user-manual/images/copy-and-paste-via-local-system_dark.png differ
diff --git a/docs/user-manual/images/inline-action-buttons_dark.png b/docs/user-manual/images/inline-action-buttons_dark.png
new file mode 100644
index 000000000..6ca40e171
Binary files /dev/null and b/docs/user-manual/images/inline-action-buttons_dark.png differ
diff --git a/docs/user-manual/images/interactive-shell-completions_dark.png b/docs/user-manual/images/interactive-shell-completions_dark.png
new file mode 100644
index 000000000..0a1bb2060
Binary files /dev/null and b/docs/user-manual/images/interactive-shell-completions_dark.png differ
diff --git a/docs/user-manual/images/local-connection_dark.png b/docs/user-manual/images/local-connection_dark.png
new file mode 100644
index 000000000..533b493b1
Binary files /dev/null and b/docs/user-manual/images/local-connection_dark.png differ
diff --git a/docs/user-manual/images/query-playground-codelens_dark.png b/docs/user-manual/images/query-playground-codelens_dark.png
new file mode 100644
index 000000000..e837c6e76
Binary files /dev/null and b/docs/user-manual/images/query-playground-codelens_dark.png differ
diff --git a/docs/user-manual/images/service-discovery-activation-vm_dark.png b/docs/user-manual/images/service-discovery-activation-vm_dark.png
new file mode 100644
index 000000000..a4112d1c6
Binary files /dev/null and b/docs/user-manual/images/service-discovery-activation-vm_dark.png differ
diff --git a/docs/user-manual/images/service-discovery-activation_dark.png b/docs/user-manual/images/service-discovery-activation_dark.png
new file mode 100644
index 000000000..a4112d1c6
Binary files /dev/null and b/docs/user-manual/images/service-discovery-activation_dark.png differ
diff --git a/docs/user-manual/images/service-discovery-filter-vm_dark.png b/docs/user-manual/images/service-discovery-filter-vm_dark.png
new file mode 100644
index 000000000..a2704bf41
Binary files /dev/null and b/docs/user-manual/images/service-discovery-filter-vm_dark.png differ
diff --git a/docs/user-manual/interactive-shell.md b/docs/user-manual/interactive-shell.md
index 85f9f60ed..3f9baf132 100644
--- a/docs/user-manual/interactive-shell.md
+++ b/docs/user-manual/interactive-shell.md
@@ -1,5 +1,7 @@
-> **User Manual** - [Back to User Manual](../index#user-manual)
-
+---
+title: 'Interactive Shell'
+parent: 'Querying'
+nav_order: 3
 ---
 
 # Interactive Shell
@@ -33,7 +35,7 @@ There are several ways to open an Interactive Shell session:
 3. **From the Collection View**: Use the **Open in Shell** toolbar button to export your current find query into a new shell session.
 4. **From the Query Playground**: Use a CodeLens link to launch a shell for the same connection.
 
-
Inline action buttons on a collection node: Open Collection View, New Query Playground, Open Interactive Shell

+
Inline action buttons on a collection node: Open Collection View, New Query Playground, Open Interactive Shell

 
 The three inline icons next to each collection node are (from left to right): Open Collection View, New Query Playground, and **Open Interactive Shell**.
 
@@ -100,7 +102,7 @@ Variables, functions, and other JavaScript state persist until you close the she
 
 The shell provides two forms of input assistance:
 
-
Interactive Shell showing tab completion for collection methods and ghost text suggesting a field name

+
Interactive Shell showing tab completion for collection methods and ghost text suggesting a field name

 
 In this example, the shell suggests `find()`, `findOne()`, and other methods after typing `db.restaurants.find` (top). It also suggests the field name `reviews` as ghost text after the user typed `re` in a query (bottom). Field suggestions come from schema information gathered locally as you browse and query your data.
 
diff --git a/docs/user-manual/local-connection-documentdb-local.md b/docs/user-manual/local-connection-documentdb-local.md
index fc36733b4..8764f7b08 100644
--- a/docs/user-manual/local-connection-documentdb-local.md
+++ b/docs/user-manual/local-connection-documentdb-local.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to User Manual](../index#user-manual)
-
+---
+title: 'Connect to DocumentDB Local'
+parent: 'Local Instances'
+nav_order: 3
 ---
 
 # DocumentDB Local
diff --git a/docs/user-manual/local-connection-mongodb-ru.md b/docs/user-manual/local-connection-mongodb-ru.md
index 92497bd35..d9c8fe08c 100644
--- a/docs/user-manual/local-connection-mongodb-ru.md
+++ b/docs/user-manual/local-connection-mongodb-ru.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to User Manual](../index#user-manual)
-
+---
+title: 'Azure Cosmos DB for MongoDB (RU) Emulator'
+parent: 'Local Instances'
+nav_order: 2
 ---
 
 # Azure CosmosDB for MongoDB (RU) Emulator
diff --git a/docs/user-manual/local-connection.md b/docs/user-manual/local-connection.md
index 96d51c4c2..57b094271 100644
--- a/docs/user-manual/local-connection.md
+++ b/docs/user-manual/local-connection.md
@@ -1,12 +1,15 @@
-> **User Manual** — [Back to User Manual](../index#user-manual)
-
+---
+title: 'Local Instances'
+parent: 'Connecting to Databases'
+nav_order: 5
+has_toc: false
 ---
 
 # Local Connection
 
 **DocumentDB for VS Code** allows you to connect to local DocumentDB and MongoDB instances. This can be useful for development, testing, or working with emulators on your own machine.
 
-
Local connection UI screenshot

+
Local connection UI screenshot

 
 ## How to Connect Locally
 
diff --git a/docs/user-manual/local-quick-start.md b/docs/user-manual/local-quick-start.md
index 83130bdda..380d7b130 100644
--- a/docs/user-manual/local-quick-start.md
+++ b/docs/user-manual/local-quick-start.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to User Manual](../index#user-manual)
-
+---
+title: 'Set up DocumentDB Local'
+parent: 'Local Instances'
+nav_order: 1
 ---
 
 # Set up DocumentDB Local
diff --git a/docs/user-manual/managing-azure-discovery.md b/docs/user-manual/managing-azure-discovery.md
index e1b342832..94d75faa8 100644
--- a/docs/user-manual/managing-azure-discovery.md
+++ b/docs/user-manual/managing-azure-discovery.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to User Manual](../index#user-manual)
-
+---
+title: 'Managing Azure Accounts and Subscriptions'
+parent: 'Service Discovery'
+nav_order: 6
 ---
 
 # Managing Azure Discovery (Accounts, Tenants, and Subscriptions)
diff --git a/docs/user-manual/query-playground.md b/docs/user-manual/query-playground.md
index 04b3d4d3d..53187d3c2 100644
--- a/docs/user-manual/query-playground.md
+++ b/docs/user-manual/query-playground.md
@@ -1,5 +1,7 @@
-> **User Manual** - [Back to User Manual](../index#user-manual)
-
+---
+title: 'Query Playground'
+parent: 'Querying'
+nav_order: 2
 ---
 
 # Query Playground
@@ -31,7 +33,7 @@ There are several ways to open a new Query Playground:
 3. **From the Collection View**: Use the **Open in Playground** toolbar button to export your current find query into a new playground file.
 4. **From the Command Palette**: Run `DocumentDB: New Query Playground`.
 
-
Inline action buttons on a collection node: Open Collection View, New Query Playground, Open Interactive Shell

+
Inline action buttons on a collection node: Open Collection View, New Query Playground, Open Interactive Shell

 
 The three inline icons next to each collection node are (from left to right): Open Collection View, **New Query Playground**, and Open Interactive Shell.
 
@@ -77,7 +79,7 @@ Because the playground uses a full JavaScript runtime, you can write queries the
 
 The playground provides two execution modes, each triggered through CodeLens buttons that appear above your code:
 
-
Query Playground showing Run All at the top, and Run, Collection View, Shell CodeLens links on each block

+
Query Playground showing Run All at the top, and Run, Collection View, Shell CodeLens links on each block

 
 | Mode          | Trigger                                                                          | Behavior                                  |
 | ------------- | -------------------------------------------------------------------------------- | ----------------------------------------- |
diff --git a/docs/user-manual/query-runtime.md b/docs/user-manual/query-runtime.md
index 84aee0f4d..3a3f6f9fb 100644
--- a/docs/user-manual/query-runtime.md
+++ b/docs/user-manual/query-runtime.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to User Manual](../index#user-manual)
-
+---
+title: 'How Queries Run Behind the Scenes'
+parent: 'Querying'
+nav_order: 4
 ---
 
 # Query Runtime: How It Works Behind the Scenes
diff --git a/docs/user-manual/querying.md b/docs/user-manual/querying.md
new file mode 100644
index 000000000..4d111e6e7
--- /dev/null
+++ b/docs/user-manual/querying.md
@@ -0,0 +1,9 @@
+---
+title: 'Querying'
+parent: 'User Manual'
+nav_order: 3
+---
+
+# Querying
+
+Find, filter and analyze documents in the Collection View, the Query Playground and the Interactive Shell.
diff --git a/docs/user-manual/service-discovery-azure-cosmosdb-for-mongodb-ru.md b/docs/user-manual/service-discovery-azure-cosmosdb-for-mongodb-ru.md
index 8c66ef8d3..974162267 100644
--- a/docs/user-manual/service-discovery-azure-cosmosdb-for-mongodb-ru.md
+++ b/docs/user-manual/service-discovery-azure-cosmosdb-for-mongodb-ru.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to User Manual](../index#user-manual)
-
+---
+title: 'Azure Cosmos DB for MongoDB (RU)'
+parent: 'Service Discovery'
+nav_order: 2
 ---
 
 # Azure CosmosDB for MongoDB (RU) Service Discovery Plugin
@@ -19,7 +21,7 @@ You can access this plugin in two ways:
 - From the `Service Discovery` panel in the extension sidebar.
 - When adding a new connection, select the `Azure CosmosDB for MongoDB (RU)` option.
 
-
Service Discovery Activation

+
Service Discovery Activation

 
 ## How It Works
 
diff --git a/docs/user-manual/service-discovery-azure-cosmosdb-for-mongodb-vcore.md b/docs/user-manual/service-discovery-azure-cosmosdb-for-mongodb-vcore.md
index fc62a258c..16e6247e3 100644
--- a/docs/user-manual/service-discovery-azure-cosmosdb-for-mongodb-vcore.md
+++ b/docs/user-manual/service-discovery-azure-cosmosdb-for-mongodb-vcore.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to User Manual](../index#user-manual)
-
+---
+title: 'Azure DocumentDB'
+parent: 'Service Discovery'
+nav_order: 1
 ---
 
 # Azure DocumentDB Service Discovery Plugin
@@ -19,7 +21,7 @@ You can access this plugin in two ways:
 - Through the `Service Discovery` panel in the extension sidebar.
 - When adding a new connection, select the `Azure DocumentDB` option.
 
-
Service Discovery Activation

+
Service Discovery Activation

 
 ## How It Works
 
diff --git a/docs/user-manual/service-discovery-azure-vms.md b/docs/user-manual/service-discovery-azure-vms.md
index 31b047ea7..e2c1cc42d 100644
--- a/docs/user-manual/service-discovery-azure-vms.md
+++ b/docs/user-manual/service-discovery-azure-vms.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to User Manual](../index#user-manual)
-
+---
+title: 'Azure VMs (DocumentDB)'
+parent: 'Service Discovery'
+nav_order: 3
 ---
 
 # Azure VMs (DocumentDB) Service Discovery Plugin
@@ -19,7 +21,7 @@ You can access this plugin in two ways:
 - Through the `Service Discovery` panel in the extension sidebar.
 - When adding a new connection, select the `Azure VMs (DocumentDB)` option.
 
-
Service Discovery Activation

+
Service Discovery Activation

 
 ## How It Works
 
@@ -58,7 +60,7 @@ This provider supports the following management features:
 - **Filter Resources**: Control which tenants and subscriptions are displayed, and customize the VM tag filter. Click the funnel icon next to the provider name.
 - **Refresh**: Reload the resource list after making changes. Click the refresh icon.
 
-
Filter Azure VM resources

+
Filter Azure VM resources

 
 For detailed instructions on account and subscription management, see [Managing Azure Discovery (Accounts, Tenants, and Subscriptions)](./managing-azure-discovery).
 
@@ -73,7 +75,7 @@ Step 1: Select Tenants (if multi-tenant)
 Step 2: Select Subscriptions
 Step 3: Configure VM Tag Filter
 ┌────────────────────────────────────────────┐
-│ Enter the tag name to filter VMs          │
+│ Enter the tag name to filter VMs           │
 ├────────────────────────────────────────────┤
 │ DocumentDB                                 │  ← Default value
 └────────────────────────────────────────────┘
diff --git a/docs/user-manual/service-discovery-kubernetes-getting-started.md b/docs/user-manual/service-discovery-kubernetes-getting-started.md
index a3daab1dd..4f17695cd 100644
--- a/docs/user-manual/service-discovery-kubernetes-getting-started.md
+++ b/docs/user-manual/service-discovery-kubernetes-getting-started.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to Kubernetes Service Discovery](./service-discovery-kubernetes) | [Back to Service Discovery](./service-discovery) | [Back to User Manual](../index#user-manual)
-
+---
+title: 'Kubernetes: Getting Started and Test Lab'
+parent: 'Kubernetes'
+nav_order: 1
 ---
 
 # Kubernetes Service Discovery: Getting Started and Test Lab
diff --git a/docs/user-manual/service-discovery-kubernetes.md b/docs/user-manual/service-discovery-kubernetes.md
index c33b7db25..4e99d8490 100644
--- a/docs/user-manual/service-discovery-kubernetes.md
+++ b/docs/user-manual/service-discovery-kubernetes.md
@@ -1,5 +1,8 @@
-> **User Manual** - [Back to Service Discovery](./service-discovery) | [Back to User Manual](../index#user-manual)
-
+---
+title: 'Kubernetes'
+parent: 'Service Discovery'
+nav_order: 4
+has_toc: false
 ---
 
 # Kubernetes Service Discovery
diff --git a/docs/user-manual/service-discovery-mongodb-atlas-browse.md b/docs/user-manual/service-discovery-mongodb-atlas-browse.md
index 0ce2a9391..2830ee0c7 100644
--- a/docs/user-manual/service-discovery-mongodb-atlas-browse.md
+++ b/docs/user-manual/service-discovery-mongodb-atlas-browse.md
@@ -1,5 +1,7 @@
-> **User Manual** | [MongoDB Atlas Service Discovery](./service-discovery-mongodb-atlas) | [Back to User Manual](../index#user-manual)
-
+---
+title: 'Browse and Connect to MongoDB Atlas'
+parent: 'MongoDB Atlas'
+nav_order: 1
 ---
 
 # Browse and Connect to MongoDB Atlas
diff --git a/docs/user-manual/service-discovery-mongodb-atlas-credentials.md b/docs/user-manual/service-discovery-mongodb-atlas-credentials.md
index 4daf9388e..fafcd3610 100644
--- a/docs/user-manual/service-discovery-mongodb-atlas-credentials.md
+++ b/docs/user-manual/service-discovery-mongodb-atlas-credentials.md
@@ -1,5 +1,7 @@
-> **User Manual** | [MongoDB Atlas Service Discovery](./service-discovery-mongodb-atlas) | [Back to User Manual](../index#user-manual)
-
+---
+title: 'Manage MongoDB Atlas Credentials'
+parent: 'MongoDB Atlas'
+nav_order: 2
 ---
 
 # Manage MongoDB Atlas Credentials
diff --git a/docs/user-manual/service-discovery-mongodb-atlas-troubleshooting.md b/docs/user-manual/service-discovery-mongodb-atlas-troubleshooting.md
index 335d8b3d0..79dd13c61 100644
--- a/docs/user-manual/service-discovery-mongodb-atlas-troubleshooting.md
+++ b/docs/user-manual/service-discovery-mongodb-atlas-troubleshooting.md
@@ -1,5 +1,7 @@
-> **User Manual** | [MongoDB Atlas Service Discovery](./service-discovery-mongodb-atlas) | [Back to User Manual](../index#user-manual)
-
+---
+title: 'Troubleshoot MongoDB Atlas Discovery'
+parent: 'MongoDB Atlas'
+nav_order: 3
 ---
 
 # Troubleshoot MongoDB Atlas Service Discovery
diff --git a/docs/user-manual/service-discovery-mongodb-atlas.md b/docs/user-manual/service-discovery-mongodb-atlas.md
index 9762ee164..55f7e49b2 100644
--- a/docs/user-manual/service-discovery-mongodb-atlas.md
+++ b/docs/user-manual/service-discovery-mongodb-atlas.md
@@ -1,5 +1,8 @@
-> **User Manual** | [Back to Service Discovery](./service-discovery) | [Back to User Manual](../index#user-manual)
-
+---
+title: 'MongoDB Atlas'
+parent: 'Service Discovery'
+nav_order: 5
+has_toc: false
 ---
 
 # MongoDB Atlas Service Discovery
diff --git a/docs/user-manual/service-discovery.md b/docs/user-manual/service-discovery.md
index aeea21027..0aad92916 100644
--- a/docs/user-manual/service-discovery.md
+++ b/docs/user-manual/service-discovery.md
@@ -1,5 +1,8 @@
-> **User Manual** — [Back to User Manual](../index#user-manual)
-
+---
+title: 'Service Discovery'
+parent: 'Connecting to Databases'
+nav_order: 4
+has_toc: false
 ---
 
 # Service Discovery in DocumentDB for VS Code
diff --git a/docs/user-manual/troubleshooting-srv-dns.md b/docs/user-manual/troubleshooting-srv-dns.md
index b69825728..95d483556 100644
--- a/docs/user-manual/troubleshooting-srv-dns.md
+++ b/docs/user-manual/troubleshooting-srv-dns.md
@@ -1,5 +1,7 @@
-> **User Manual** — [Back to User Manual](../index#user-manual)
-
+---
+title: 'Troubleshoot SRV DNS Lookups'
+parent: 'Connecting to Databases'
+nav_order: 3
 ---
 
 # Troubleshoot SRV DNS Lookups (`querySrv EBADRESP`)
diff --git a/docs/vscode-documentdb-hero-screenshot_dark.png b/docs/vscode-documentdb-hero-screenshot_dark.png
new file mode 100644
index 000000000..b4b1ec82b
Binary files /dev/null and b/docs/vscode-documentdb-hero-screenshot_dark.png differ
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 1a32c6e98..752782725 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -179,6 +179,16 @@ export default ts.config(
             'react/prop-types': 'off', // TypeScript handles prop validation
         },
     },
+    // Docs site scripts run in the browser (GitHub Pages), not in Node.
+    {
+        files: ['docs/assets/js/**/*.js'],
+
+        languageOptions: {
+            globals: {
+                ...globals.browser,
+            },
+        },
+    },
     // Vitest unit tests in src/ (they import their test API from 'vitest'; no test globals)
     {
         files: ['src/**/*.test.ts'],