Docs site: switch to Just the Docs with OS dark mode

.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 `<picture>` 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`. |

.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]

.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:<Port>/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
+}

.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

.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

.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

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=<repository id> -f cat=<category id> -f title="vX.Y.Z" -f body="$(cat docs/release-notes/X.Y.md)" \
+}' -f repo=<repository id> -f cat=<category id> -f title="vX.Y.Z" -f body="$(sed '1,/^---$/d' docs/release-notes/X.Y.md)" \
   --jq '.data.createDiscussion.discussion.url'
 ```
 

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

docs/_includes/head_custom.html

@@ -0,0 +1,3 @@
+<!-- Follow the OS color scheme: overlay the dark stylesheet only when the OS prefers dark. -->
+<link rel="stylesheet" href="{{ '/assets/css/just-the-docs-dark.css' | relative_url }}" media="(prefers-color-scheme: dark)">
+<script src="{{ '/assets/js/page-toc.js' | relative_url }}" defer></script>

docs/_includes/title.html

@@ -0,0 +1,9 @@
+{%- comment -%}
+  Overrides the theme's title.html: DocumentDB icon next to the site title.
+  The <picture> source swaps to the dark-background icon when the OS prefers dark.
+{%- endcomment -%}
+<picture class="site-icon">
+  <source srcset="{{ '/assets/images/documentdb-icon-dark.svg' | relative_url }}" media="(prefers-color-scheme: dark)">
+  <img src="{{ '/assets/images/documentdb-icon-light.svg' | relative_url }}" alt="" width="28" height="28">
+</picture>
+<span>{{ site.title | replace: ' for VS Code', ' for&nbsp;VS&nbsp;Code' }}</span>