diff --git a/.github/workflows/deploy-documentation-preview.yml b/.github/workflows/deploy-documentation-preview.yml index d1dcccf4..dcf4d0bf 100644 --- a/.github/workflows/deploy-documentation-preview.yml +++ b/.github/workflows/deploy-documentation-preview.yml @@ -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 }}) diff --git a/docs/THEME_CUSTOMIZATION.md b/docs/THEME_CUSTOMIZATION.md new file mode 100644 index 00000000..5aee9760 --- /dev/null +++ b/docs/THEME_CUSTOMIZATION.md @@ -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 content (favicons, fonts, etc.) + └── sub-footer.html # Custom content before 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` diff --git a/docs/_config.yml b/docs/_config.yml index 932d5433..f9f1cb94 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -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/ diff --git a/docs/_includes/custom-head.html b/docs/_includes/custom-head.html new file mode 100644 index 00000000..efa8db39 --- /dev/null +++ b/docs/_includes/custom-head.html @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + diff --git a/docs/_includes/sub-footer.html b/docs/_includes/sub-footer.html new file mode 100644 index 00000000..c298bc80 --- /dev/null +++ b/docs/_includes/sub-footer.html @@ -0,0 +1,28 @@ + + + + + + + + + + + diff --git a/docs/_sass/minima/custom-styles.scss b/docs/_sass/minima/custom-styles.scss new file mode 100644 index 00000000..09ed4651 --- /dev/null +++ b/docs/_sass/minima/custom-styles.scss @@ -0,0 +1,130 @@ +// ---------------------------------------------------------------------------- +// Minima Custom Styles +// ---------------------------------------------------------------------------- +// This file allows you to override CSS styles AFTER the base theme styles +// have been defined. This is where you put your custom CSS rules. +// +// NOTE: This file is imported AFTER all base styles and layout styles, so you +// can override any existing styles. However, you CANNOT override Sass variables +// here (use custom-variables.scss for that). +// ---------------------------------------------------------------------------- + +// Example: Custom heading styles +// ---------------------------------------------------------------------------- +// h1, h2, h3, h4, h5, h6 { +// font-weight: 600; +// } +// +// h1 { +// border-bottom: 2px solid $border-color-01; +// padding-bottom: 0.3em; +// } + +// Example: Custom link styles +// ---------------------------------------------------------------------------- +// a { +// text-decoration: underline; +// text-decoration-color: rgba($link-base-color, 0.3); +// +// &:hover { +// text-decoration-color: $link-hover-color; +// } +// } + +// Example: Custom navigation styles +// ---------------------------------------------------------------------------- +// .site-nav { +// .page-link { +// font-weight: 500; +// padding: 8px 16px; +// border-radius: 4px; +// +// &:hover { +// background-color: rgba($brand-color, 0.1); +// } +// } +// } + +// Example: Custom footer styles +// ---------------------------------------------------------------------------- +// .site-footer { +// padding: $spacing-unit * 1.5 0; +// +// .footer-heading { +// font-size: 18px; +// margin-bottom: $spacing-unit / 2; +// } +// } + +// Example: Custom post styles +// ---------------------------------------------------------------------------- +// .post-content { +// h2 { +// margin-top: $spacing-unit * 1.5; +// font-size: 28px; +// } +// +// h3 { +// margin-top: $spacing-unit; +// font-size: 22px; +// } +// +// img { +// border-radius: 4px; +// box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1); +// } +// } + +// Example: Custom code block styles +// ---------------------------------------------------------------------------- +// pre, code { +// border-radius: 4px; +// } +// +// pre { +// padding: $spacing-unit / 2; +// } +// +// code { +// padding: 2px 6px; +// } + +// Example: Custom blockquote styles +// ---------------------------------------------------------------------------- +// blockquote { +// border-left: 4px solid $brand-color; +// padding-left: $spacing-unit / 2; +// font-style: italic; +// background-color: rgba($brand-color, 0.05); +// border-radius: 0 4px 4px 0; +// } + +// Example: Custom table styles +// ---------------------------------------------------------------------------- +// table { +// border-radius: 4px; +// overflow: hidden; +// +// th { +// background-color: $brand-color; +// color: white; +// } +// +// tr:hover { +// background-color: rgba($brand-color, 0.05); +// } +// } + +// Example: Utility classes +// ---------------------------------------------------------------------------- +// .text-center { +// text-align: center; +// } +// +// .mt-1 { margin-top: $spacing-unit / 2; } +// .mt-2 { margin-top: $spacing-unit; } +// .mt-3 { margin-top: $spacing-unit * 1.5; } +// +// .mb-1 { margin-bottom: $spacing-unit / 2; } +// .mb-2 { margin-bottom: $spacing-unit; } +// .mb-3 { margin-bottom: $spacing-unit * 1.5; } diff --git a/docs/_sass/minima/custom-variables.scss b/docs/_sass/minima/custom-variables.scss new file mode 100644 index 00000000..e073d781 --- /dev/null +++ b/docs/_sass/minima/custom-variables.scss @@ -0,0 +1,76 @@ +// ---------------------------------------------------------------------------- +// Minima Custom Variables +// ---------------------------------------------------------------------------- +// This file allows you to override Sass variables and mixins BEFORE they are +// used in the theme. This is useful for changing colors, fonts, spacing, etc. +// +// NOTE: This file is imported BEFORE base styles, so you can only override +// variables here, not actual CSS styles. For style overrides, use custom-styles.scss +// ---------------------------------------------------------------------------- + +// Typography +// ---------------------------------------------------------------------------- +// $base-font-family: -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", "Segoe UI Emoji", "Segoe UI Symbol", "Apple Color Emoji", Roboto, Helvetica, Arial, sans-serif !default; +// $code-font-family: "Menlo", "Inconsolata", "Consolas", "Roboto Mono", "Ubuntu Mono", "Liberation Mono", "Courier New", monospace !default; +// $base-font-size: 16px !default; +// $base-font-weight: 400 !default; +// $small-font-size: $base-font-size * 0.875 !default; +// $base-line-height: 1.5 !default; + +// Spacing +// ---------------------------------------------------------------------------- +// $spacing-unit: 30px !default; + +// Layout widths +// ---------------------------------------------------------------------------- +// $content-width: 800px !default; +// $on-palm: 600px !default; +// $on-laptop: 800px !default; +// $on-medium: 1000px !default; +// $on-large: 1200px !default; + +// Color variables (skin-agnostic, customizable per skin) +// ---------------------------------------------------------------------------- +// The following are examples - actual variables depend on the active skin +// Uncomment and modify as needed: + +// Brand colors +// $brand-color: #2a7ae2 !default; +// $brand-color-light: lighten($brand-color, 40%) !default; +// $brand-color-dark: darken($brand-color, 25%) !default; + +// Link colors +// $link-base-color: #2a7ae2 !default; +// $link-visited-color: darken($link-base-color, 15%) !default; +// $link-hover-color: #1756a9 !default; + +// Text colors +// $text-color: #111111 !default; +// $background-color: #fdfdfd !default; +// $code-background-color: #f5f5f5 !default; + +// Border colors +// $border-color-01: lighten($text-color, 60%) !default; +// $border-color-02: lighten($text-color, 55%) !default; +// $border-color-03: lighten($text-color, 50%) !default; + +// Table colors +// $table-text-color: $text-color !default; +// $table-zebra-color: lighten($text-color, 65%) !default; +// $table-header-bg-color: lighten($text-color, 60%) !default; +// $table-header-border: lighten($text-color, 55%) !default; +// $table-border-color: $border-color-01 !default; + +// Custom mixins +// ---------------------------------------------------------------------------- +// @mixin relative-font-size($ratio) { +// font-size: #{$ratio}rem; +// } + +// Media query mixins +// ---------------------------------------------------------------------------- +// @mixin media-query($device) { +// @media screen and (max-width: $device) { +// @content; +// } +// } diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss new file mode 100644 index 00000000..a654535e --- /dev/null +++ b/docs/assets/css/style.scss @@ -0,0 +1,61 @@ +--- +--- + +// Only the main Sass file needs front matter (the dashes are required) + +// Import the skin (choose one or use site.minima.skin variable) +@import "minima/skins/{{ site.minima.skin | default: 'classic' }}", 'minima/initialize'; + +// ---------------------------------------------------------------------------- +// Your custom CSS/SCSS overrides go below this line +// ---------------------------------------------------------------------------- + +// Example: Override link colors +// a { +// color: #0066cc; +// +// &:visited { +// color: #551a8b; +// } +// +// &:hover { +// color: #003366; +// } +// } + +// Example: Override header background +// .site-header { +// background-color: #f8f9fa; +// border-bottom: 2px solid #0078d4; +// } + +// Example: Override footer styles +// .site-footer { +// background-color: #2d2d30; +// color: #ffffff; +// } + +// Example: Custom button styles +// .btn-primary { +// background-color: #0078d4; +// color: white; +// padding: 10px 20px; +// border-radius: 4px; +// text-decoration: none; +// display: inline-block; +// +// &:hover { +// background-color: #005a9e; +// } +// } + +// Example: Override code block styles +// pre, code { +// background-color: #f5f5f5; +// border: 1px solid #ddd; +// } + +// Example: Adjust content width +// .wrapper { +// max-width: 1200px; +// }