microsoft · tnaum-ms · Dec 11, 2025 · Dec 11, 2025 · Dec 11, 2025 · Dec 11, 2025
@@ -131,6 +131,12 @@ jobs:
 
                       To update the preview, trigger this workflow again with the same PR number.
 
+                      ### ⚠️ Known Limitations
+
+                      **Config sharing:** All deployments (production + PR previews) share the same Jekyll `_config.yml` from the `gh-pages` branch root. Changes to config settings will affect all deployments.
+
+                      **Asset links:** PR previews use the production `baseurl` setting, so some CSS/JS/image links may not work correctly in the preview. This is a known limitation of the current GitHub Pages setup.
+
                       ---
                       **🔍 Monitor deployment:**
                       - [Workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})

@@ -0,0 +1,162 @@
+# Theme Customization Guide
+
+This directory contains customization files for the Minima theme used with GitHub Pages.
+
+## 📁 File Structure
+
+```
+docs/
+├── _config.yml              # Main Jekyll configuration
+├── assets/css/
+│   └── style.scss          # Main stylesheet (imports theme + custom overrides)
+├── _sass/minima/
+│   ├── custom-variables.scss  # Variable overrides (colors, fonts, spacing)
+│   └── custom-styles.scss     # CSS style overrides
+└── _includes/
+    ├── custom-head.html      # Custom <head> content (favicons, fonts, etc.)
+    └── sub-footer.html       # Custom content before </body> tag
+```
+
+## 🎨 Available Skins
+
+Minima includes several built-in color schemes. Change in `_config.yml`:
+
+- `classic` (default) - Light color scheme
+- `dark` - Dark variant
+- `auto` - Adaptive (switches based on OS/browser preference)
+- `solarized` - Adaptive solarized scheme
+- `solarized-light` - Light solarized
+- `solarized-dark` - Dark solarized
+
+```yaml
+minima:
+  skin: classic # Change this value
+```
+
+## 🔧 Customization Order
+
+1. **Variables First**: Edit `_sass/minima/custom-variables.scss`
+   - Override colors, fonts, spacing BEFORE they're used
+   - Cannot override actual CSS styles here
+
+2. **Styles Second**: Edit `_sass/minima/custom-styles.scss`
+   - Override CSS styles AFTER base theme is loaded
+   - Cannot override Sass variables here
+
+3. **Main Stylesheet**: Edit `assets/css/style.scss`
+   - Additional custom CSS/SCSS at the bottom
+   - One-off overrides that don't fit elsewhere
+
+## 📝 Common Customizations
+
+### Change Colors
+
+Edit `_sass/minima/custom-variables.scss`:
+
+```scss
+$brand-color: #0078d4;
+$link-base-color: #0078d4;
+$text-color: #333333;
+$background-color: #ffffff;
+```
+
+### Change Fonts
+
+Edit `_sass/minima/custom-variables.scss`:
+
+```scss
+$base-font-family:
+  'Inter',
+  -apple-system,
+  system-ui,
+  sans-serif;
+$code-font-family: 'Fira Code', 'Consolas', monospace;
+```
+
+### Adjust Layout Width
+
+Edit `_sass/minima/custom-variables.scss`:
+
+```scss
+$content-width: 1000px;
+```
+
+### Custom Navigation
+
+Edit `_config.yml`:
+
+```yaml
+minima:
+  nav_pages:
+    - index.md
+    - user-manual.md
+    - about.md
+```
+
+### Add Social Links
+
+Edit `_config.yml`:
+
+```yaml
+minima:
+  social_links:
+    - title: GitHub Repository
+      icon: github
+      url: 'https://github.com/microsoft/vscode-documentdb'
+```
+
+### Add Favicon
+
+1. Generate favicons at https://realfavicongenerator.net/
+2. Add the provided code to `_includes/custom-head.html`
+
+## 🔌 GitHub Pages Plugins
+
+These plugins are enabled in `_config.yml`:
+
+- `jekyll-feed` - Generates RSS/Atom feed
+- `jekyll-seo-tag` - SEO optimization
+- `jekyll-sitemap` - XML sitemap
+- `jekyll-mentions` - GitHub @mentions
+- `jekyll-redirect-from` - Page redirects
+- `jekyll-avatar` - GitHub avatars
+- `jemoji` - Emoji support
+
+See [GitHub Pages dependencies](https://pages.github.com/versions/) for all available plugins.
+
+## 🚀 Testing Locally
+
+1. Install Ruby and Bundler
+2. Create a `Gemfile` in the docs folder:
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'github-pages', group: :jekyll_plugins
+gem 'webrick' # Required for Ruby 3.0+
+```
+
+3. Run:
+
+```bash
+cd docs
+bundle install
+bundle exec jekyll serve
+```
+
+4. Visit http://localhost:4000
+
+## 📚 Additional Resources
+
+- [Minima Theme Documentation](https://github.com/jekyll/minima)
+- [Jekyll Documentation](https://jekyllrb.com/docs/)
+- [GitHub Pages Documentation](https://docs.github.com/en/pages)
+- [Liquid Template Language](https://shopify.github.io/liquid/)
+- [Font Awesome Icons](https://fontawesome.com/search?ic=brands) (for social links)
+
+## ⚠️ Important Notes
+
+- The remote theme is pinned to commit `1e8a445` for stability
+- Changes to `_config.yml` require restarting the Jekyll server
+- CSS changes are picked up automatically in watch mode
+- Front matter (the `---` lines) is required in `assets/css/style.scss`
@@ -1,2 +1,85 @@
+# Remote theme configuration for GitHub Pages
+remote_theme: 'jekyll/minima@1e8a445'
+
+# Site settings
 title: DocumentDB for VS Code
 description: Learn more about the DocumentDB for VS Code Extension
+# WARNING: All deployments (production + PR previews) share this single config
+# due to GitHub Pages limitations. This baseurl is set for production.
+baseurl: '/vscode-documentdb'
+url: 'https://microsoft.github.io'
+
+# GitHub Pages supported plugins
+# See: https://pages.github.com/versions/
+plugins:
+    - jekyll-remote-theme # REQUIRED for remote_theme to work
+    - jekyll-feed
+    - jekyll-seo-tag
+    - jekyll-sitemap
+    - jekyll-mentions
+    - jekyll-redirect-from
+    - jekyll-avatar
+    - jemoji
+
+# Author metadata (for SEO and theme)
+author:
+    name: Microsoft
+    email: '' # Optional
+
+# Minima theme configuration
+minima:
+    # Skin selection: classic (default), dark, auto, solarized, solarized-light, solarized-dark
+    skin: auto
+
+    # Date format (Liquid date filter)
+    # See: http://shopify.github.io/liquid/filters/date/
+    date_format: '%b %-d, %Y'
+
+    # Show post excerpts on the home page
+    show_excerpts: false
+
+    # Hide site feed link in footer
+    hide_site_feed_link: false
+
+    # Navigation pages - customize which pages appear in header nav
+    # Uncomment and modify to control navigation order
+    # nav_pages:
+    #   - about.md
+    #   - index.md
+
+    # Social links (displayed in footer)
+    # Uses Font Awesome icons: https://fontawesome.com/search?ic=brands
+    social_links:
+        # - title: GitHub Repository
+        #   icon: github
+        #   url: "https://github.com/microsoft/vscode-documentdb"
+        # - title: X (Twitter)
+        #   icon: x-twitter
+        #   url: "https://twitter.com/yourhandle"
+        # - title: LinkedIn
+        #   icon: linkedin
+        #   url: "https://linkedin.com/company/microsoft"
+
+# Google Analytics (optional)
+# google_analytics: G-NNNNNNNNNN
+
+# Disqus comments (optional) - only shows in production
+# disqus:
+#   shortname: your_disqus_shortname
+
+# # Build settings
+# markdown: kramdown
+# kramdown:
+#     input: GFM
+#     hard_wrap: false
+#     syntax_highlighter: rouge
+
+# Exclude from processing
+exclude:
+    - Gemfile
+    - Gemfile.lock
+    - node_modules
+    - vendor/bundle/
+    - vendor/cache/
+    - vendor/gems/
+    - vendor/ruby/
@@ -0,0 +1,20 @@
+<!-- Custom head content -->
+<!-- This file is automatically included in the <head> section by Minima -->
+
+<!-- Example: Add custom meta tags -->
+<!-- <meta name="keywords" content="documentdb, mongodb, vscode, azure, cosmos db"> -->
+
+<!-- Example: Add favicon -->
+<!-- Generate favicons at https://realfavicongenerator.net/ and paste the code here -->
+<!-- <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
+<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
+<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
+<link rel="manifest" href="/site.webmanifest"> -->
+
+<!-- Example: Add custom fonts -->
+<!-- <link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet"> -->
+
+<!-- Example: Add custom analytics or tracking -->
+<!-- <script async src="https://example.com/analytics.js"></script> -->
@@ -0,0 +1,28 @@
+<!-- Sub-footer content -->
+<!-- This file is included just before the </body> tag by Minima -->
+
+<!-- Example: Add deferred JavaScript -->
+<!-- <script defer src="/assets/js/custom.js"></script> -->
+
+<!-- Example: Add a cookie consent banner -->
+<!-- <div id="cookie-consent">
+  <p>This site uses cookies to improve your experience.</p>
+  <button onclick="acceptCookies()">Accept</button>
+</div> -->
+
+<!-- Example: Add a back-to-top button -->
+<!-- <button id="back-to-top" title="Go to top">↑</button>
+<script>
+  window.addEventListener('scroll', function() {
+    const btn = document.getElementById('back-to-top');
+    if (window.pageYOffset > 300) {
+      btn.style.display = 'block';
+    } else {
+      btn.style.display = 'none';
+    }
+  });
+
+  document.getElementById('back-to-top').addEventListener('click', function() {
+    window.scrollTo({ top: 0, behavior: 'smooth' });
+  });
+</script> -->