From 05a1c6e5c18087c347447f9ec987aae96b2b2532 Mon Sep 17 00:00:00 2001 From: Disha Prakash Date: Thu, 19 Mar 2026 20:20:38 +0000 Subject: [PATCH 1/3] Add new UI and samples UI --- .github/header-checker-lint.yml | 2 +- .hugo/assets/scss/_styles_project.scss | 13 + .hugo/assets/scss/components/_callouts.scss | 26 ++ .hugo/assets/scss/components/_header.scss | 213 ++++++++++ .hugo/assets/scss/components/_layout.scss | 27 ++ .hugo/assets/scss/components/_search.scss | 245 +++++++++++ .../scss/components/_secondary_nav.scss | 43 ++ .hugo/assets/scss/components/_sidebar.scss | 151 +++++++ .hugo/assets/scss/components/_typography.scss | 37 ++ .hugo/hugo.cloudflare.toml | 4 +- .hugo/hugo.toml | 4 +- .hugo/layouts/_default/home.releases.releases | 2 + .hugo/layouts/docs/redirect.html | 11 + .hugo/layouts/partials/hooks/body-end.html | 228 +++++++++- .hugo/layouts/partials/hooks/head-end.html | 2 +- .hugo/layouts/partials/llms-header.html | 21 +- .../partials/navbar-version-selector.html | 2 +- .hugo/layouts/partials/search-input.html | 400 ++++++------------ .../shortcodes/compatible-sources.html | 4 +- .hugo/layouts/shortcodes/list-db.html | 98 +++++ .hugo/layouts/shortcodes/list-tools.html | 101 +++-- .hugo/layouts/shortcodes/samples-gallery.html | 274 ++++++++++++ .hugo/static/js/custom-layout.js | 155 +++++++ DEVELOPER.md | 71 ++-- GEMINI.md | 42 +- docs/en/blogs/_index.md | 2 +- .../documentation/getting-started/_index.md | 4 +- .../alloydb/samples/mcp_quickstart.md | 2 +- .../integrations/snowflake/samples/sample.md | 4 +- docs/en/{samples-hub => samples}/_index.md | 8 +- .../deploy_adk_agent.md | 2 + .../prompts_quickstart_gemini_cli.md | 2 + 32 files changed, 1828 insertions(+), 372 deletions(-) create mode 100644 .hugo/assets/scss/components/_callouts.scss create mode 100644 .hugo/assets/scss/components/_header.scss create mode 100644 .hugo/assets/scss/components/_layout.scss create mode 100644 .hugo/assets/scss/components/_search.scss create mode 100644 .hugo/assets/scss/components/_secondary_nav.scss create mode 100644 .hugo/assets/scss/components/_sidebar.scss create mode 100644 .hugo/assets/scss/components/_typography.scss create mode 100644 .hugo/layouts/docs/redirect.html create mode 100644 .hugo/layouts/shortcodes/list-db.html create mode 100644 .hugo/layouts/shortcodes/samples-gallery.html create mode 100644 .hugo/static/js/custom-layout.js rename docs/en/{samples-hub => samples}/_index.md (86%) rename docs/en/{samples-hub => samples}/deploy_adk_agent.md (98%) rename docs/en/{samples-hub => samples}/prompts_quickstart_gemini_cli.md (99%) diff --git a/.github/header-checker-lint.yml b/.github/header-checker-lint.yml index 0520ae4f91df..e6c6b3f0dcfe 100644 --- a/.github/header-checker-lint.yml +++ b/.github/header-checker-lint.yml @@ -23,5 +23,5 @@ sourceFileExtensions: - 'yml' ignoreFiles: - 'docs/en/documentation/**/*.go' - - 'docs/en/samples-hub/**/*' + - 'docs/en/samples/**/*' - '**/*oracle*' \ No newline at end of file diff --git a/.hugo/assets/scss/_styles_project.scss b/.hugo/assets/scss/_styles_project.scss index 34a7e05c22c8..37028c49dcbf 100644 --- a/.hugo/assets/scss/_styles_project.scss +++ b/.hugo/assets/scss/_styles_project.scss @@ -1,3 +1,16 @@ +/* ========================================================================== + PROJECT SCSS HUB + Custom theme overrides and UI components. + ========================================================================== */ + +@import 'components/typography'; +@import 'components/layout'; +@import 'components/header'; +@import 'components/sidebar'; +@import 'components/callouts'; +@import 'components/secondary_nav'; +@import 'components/search'; + @import 'td/code-dark'; // Make tabs scrollable horizontally instead of wrapping diff --git a/.hugo/assets/scss/components/_callouts.scss b/.hugo/assets/scss/components/_callouts.scss new file mode 100644 index 000000000000..5e11dda7c44d --- /dev/null +++ b/.hugo/assets/scss/components/_callouts.scss @@ -0,0 +1,26 @@ +/* ========================================================================== + CALLOUTS & NOTICES + Styling for alerts, tips, and admonition blocks. + ========================================================================== */ + +.td-content .alert code, +.td-content .notice code, +.td-content .admonition code { + background-color: #ffffff !important; + color: rgba(32, 33, 36, 0.95) !important; + padding: 0.2rem 0.4rem !important; + border-radius: 4px !important; + border: 1px solid rgba(0, 0, 0, 0.05) !important; + font-weight: 500 !important; +} + +html[data-bs-theme="dark"] .td-content .alert code, +body.dark .td-content .alert code, +html[data-bs-theme="dark"] .td-content .notice code, +body.dark .td-content .notice code, +html[data-bs-theme="dark"] .td-content .admonition code, +body.dark .td-content .admonition code { + background-color: rgba(255, 255, 255, 0.15) !important; + color: #ffffff !important; + border-color: rgba(255, 255, 255, 0.1) !important; +} \ No newline at end of file diff --git a/.hugo/assets/scss/components/_header.scss b/.hugo/assets/scss/components/_header.scss new file mode 100644 index 000000000000..68a1766328e5 --- /dev/null +++ b/.hugo/assets/scss/components/_header.scss @@ -0,0 +1,213 @@ +/* ========================================================================== + HEADER & NAVIGATION + Primary navbar, secondary tabbed nav, utilities, and mobile layouts. + ========================================================================== */ + +/* Main Header Structure */ +header { position: sticky !important; top: 0; z-index: 1060; width: 100%; background-color: var(--bs-body-bg, #ffffff); transform: translateZ(0); } +header, .td-navbar { z-index: 1060 !important; } + +.td-navbar { + position: relative !important; width: 100% !important; + + /* Header Utility Buttons */ + .navbar-nav { + gap: 0.35rem; align-items: center; + + li.td-light-dark-menu > button, + li.nav-item:has(a[href*="github"]) > a, + li.nav-item:has(a[href*="Releases"], .dropdown-toggle):not(.td-light-dark-menu) > a { + background-color: transparent !important; background-image: none !important; border: 1.5px solid transparent !important; + box-shadow: none !important; outline: none !important; color: rgba(255, 255, 255, 0.85) !important; + font-weight: 500 !important; font-size: 0.95rem !important; text-decoration: none !important; white-space: nowrap; + display: flex !important; align-items: center !important; justify-content: center !important; + transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1) !important; + + i, svg { font-size: 1.15rem !important; fill: rgba(255, 255, 255, 0.85) !important; transition: all 0.2s ease-in-out !important; } + + &:hover { + background-color: #ffffff !important; color: $primary !important; + box-shadow: 0 4px 10px rgba(0, 0, 0, 0.1), 0 0 0 2px rgba(255, 255, 255, 0.2) !important; + transform: translateY(-1px) !important; opacity: 1; + i, svg { fill: $primary !important; opacity: 1; } + } + &:active { transform: translateY(0px) !important; background-color: rgba(255, 255, 255, 0.15) !important; } + } + + li.nav-item:has(a[href*="github"]) > a, + li.nav-item:has(a[href*="Releases"], .dropdown-toggle):not(.td-light-dark-menu) > a { + border-radius: 50px !important; padding: 0.35rem 1.1rem !important; + i, svg { margin-right: 0.4rem !important; } + } + + li.nav-item:has(a[href*="Releases"], .dropdown-toggle):not(.td-light-dark-menu) > a.dropdown-toggle::after { + display: inline-block !important; margin-left: 0.5rem !important; vertical-align: middle !important; + border-top: 0.4em solid; border-right: 0.4em solid transparent; border-bottom: 0; border-left: 0.4em solid transparent; + transition: transform 0.2s ease; + } + + li.nav-item.show > a.dropdown-toggle::after, + a.dropdown-toggle.show::after { transform: rotate(180deg); } + + li.td-light-dark-menu > button { + width: 38px !important; height: 38px !important; padding: 0 !important; border-radius: 50% !important; + &::after { display: none !important; } + i, svg { margin: 0 !important; width: 1.15rem !important; height: 1.15rem !important; } + } + } + + /* Universal Dropdowns */ + .dropdown-menu { + z-index: 1065 !important; margin-top: 0.6rem !important; background-color: #ffffff !important; + border: 1px solid rgba(0, 0, 0, 0.08) !important; border-radius: 12px !important; + box-shadow: 0 12px 34px rgba(0, 0, 0, 0.15) !important; padding: 0.6rem !important; + min-width: 200px !important; max-height: 60vh !important; overflow-y: auto !important; + scrollbar-width: thin; scrollbar-color: rgba(0, 0, 0, 0.2) rgba(0, 0, 0, 0.05); + animation: dropdownFadeIn 0.25s cubic-bezier(0.16, 1, 0.3, 1) forwards !important; transform-origin: top right; + + &::-webkit-scrollbar { width: 8px; display: block !important; } + &::-webkit-scrollbar-track { background: rgba(0, 0, 0, 0.05) !important; border-radius: 10px; margin: 5px; } + &::-webkit-scrollbar-thumb { + background: rgba(0, 0, 0, 0.2) !important; border-radius: 10px; border: 2px solid transparent; background-clip: content-box; + &:hover { background: rgba(0, 0, 0, 0.35) !important; background-clip: content-box; } + } + } + + .dropdown-item { + border-radius: 8px !important; padding: 0.6rem 1rem !important; color: #495057 !important; + margin-bottom: 4px !important; transition: all 0.2s ease !important; display: flex !important; + align-items: center !important; font-weight: 500 !important; + + i, svg { margin-right: 12px !important; width: 16px !important; text-align: center; } + + &:hover, &:focus { + background-color: rgba(68, 132, 244, 0.08) !important; color: #4484f4 !important; transform: translateX(4px) !important; + } + + &:not(.active-version):not(.active):not(:has(i)):not(:has(svg)) { + opacity: 0.75 !important; font-weight: 400 !important; transition: opacity 0.2s ease !important; + &:hover { opacity: 1 !important; } + } + + &.active-version, &.active { + background-color: rgba(68, 132, 244, 0.08) !important; color: #4484f4 !important; font-weight: 600 !important; + position: relative; padding-left: 2rem !important; border-left: 4px solid #4484f4 !important; + &:hover { background-color: rgba(68, 132, 244, 0.12) !important; transform: translateX(4px) !important; } + } + } +} + +/* Tabbed Secondary Navbar */ +#secondary-nav { + position: fixed; top: 4rem; left: 0; right: 0; height: 52px; z-index: 1055 !important; + background: linear-gradient(rgba(0, 0, 0, 0.08), rgba(0, 0, 0, 0.08)), $primary; + box-shadow: inset 0 4px 12px rgba(0, 0, 0, 0.15); border-bottom: 1px solid rgba(0, 0, 0, 0.1); + display: flex; align-items: center; position: relative !important; top: 0 !important; + width: 100%; max-width: 100vw; box-sizing: border-box; + + .container-fluid { + display: flex; align-items: center; width: 100%; height: 100%; overflow-x: auto !important; flex-wrap: nowrap !important; + scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; + &::-webkit-scrollbar { display: none; } + } + .sec-nav-list { + display: flex; margin: 0; padding: 0 1.5rem; list-style: none; gap: 28px; + align-items: center; height: 100%; width: auto; flex-shrink: 0 !important; flex-wrap: nowrap; overflow: visible !important; + } + .sec-nav-icons { display: flex; gap: 1.5rem; list-style: none; margin: 0 0 0 auto; padding: 0 1.5rem 0 2rem; align-items: center; flex-shrink: 0 !important; } + li { height: 100%; display: flex; align-items: center; } + a { + color: rgba(255, 255, 255, 0.7) !important; font-weight: 500; text-decoration: none; + font-size: 14.5px; letter-spacing: 0.2px; height: 100%; display: flex; align-items: center; + padding: 0 2px; border-bottom: 2px solid transparent; margin-bottom: 0; transition: color 0.15s ease, border-color 0.15s ease; white-space: nowrap; + &:hover { color: #ffffff !important; } + &.active { color: #ffffff !important; font-weight: 600; border-bottom: 2px solid #ffffff; } + } +} + +/* Dark Mode Overrides */ +html[data-bs-theme="dark"], body.dark { + .td-navbar .navbar-nav { + li.td-light-dark-menu > button, + li.nav-item:has(a[href*="github"]) > a, + li.nav-item:has(a[href*="Releases"], .dropdown-toggle):not(.td-light-dark-menu) > a { + background-color: transparent !important; box-shadow: none !important; color: #e8eaed !important; + i, svg { fill: #e8eaed !important; } + &:hover { + background-color: #303134 !important; color: #f8f9fa !important; border-color: #8ab4f8 !important; + box-shadow: 0 4px 10px rgba(0, 0, 0, 0.3), 0 0 0 2px rgba(138, 180, 248, 0.15) !important; + i, svg { fill: #f8f9fa !important; } + } + } + } + .td-navbar .dropdown-menu { + background-color: #202124 !important; border-color: rgba(255, 255, 255, 0.12) !important; + box-shadow: 0 12px 40px rgba(0, 0, 0, 0.6) !important; scrollbar-color: rgba(255, 255, 255, 0.2) rgba(255, 255, 255, 0.05); + } + .td-navbar .dropdown-item { + color: #e8eaed !important; + &:hover, &:focus { background-color: rgba(138, 180, 248, 0.12) !important; color: #8ab4f8 !important; } + &.active-version, &.active { + background-color: rgba(138, 180, 248, 0.12) !important; color: #8ab4f8 !important; border-left-color: #8ab4f8 !important; + &::before { color: #8ab4f8; } + &:hover { background-color: rgba(138, 180, 248, 0.18) !important; } + } + } + #secondary-nav { + background: linear-gradient(rgba(0, 0, 0, 0.15), rgba(0, 0, 0, 0.15)), $primary; box-shadow: inset 0 4px 15px rgba(0, 0, 0, 0.3); border-bottom: 1px solid rgba(255, 255, 255, 0.05); + a { color: rgba(255, 255, 255, 0.7) !important; &:hover { color: #ffffff !important; } &.active { color: #ffffff !important; border-bottom-color: #ffffff; } } + } +} + +/* Desktop Adjustments */ +@media (min-width: 992px) { + .td-navbar .custom-pagefind-wrapper { + position: relative !important; left: 50% !important; top: 50% !important; transform: translate(-50%, -50%) !important; + width: 100% !important; max-width: 500px !important; margin: 0 !important; z-index: 1060 !important; + transition: opacity 0.15s ease-out, transform 0.15s ease-out, box-shadow 0.15s ease-out !important; + } + .td-navbar .pagefind-ui__drawer { left: 0 !important; right: 0 !important; width: 100% !important; max-width: 100% !important; } +} + +/* Mobile Layout & Scaling */ +@media (max-width: 991.98px) { + header, .td-navbar { position: relative !important; } + .td-navbar { height: auto !important; padding-bottom: 0.5rem !important; flex-wrap: nowrap !important; justify-content: space-between !important; min-height: 4rem !important; } + header .navbar-toggler { display: inline-flex !important; z-index: 1080 !important; margin-left: auto !important; } + .td-navbar .container-fluid { display: flex !important; flex-wrap: wrap !important; justify-content: space-between !important; align-items: center !important; } + .td-navbar .navbar-nav, .td-navbar .navbar-toggler { flex-direction: row !important; order: 2 !important; width: auto !important; margin-left: auto !important; } + .td-navbar .custom-pagefind-wrapper { display: none !important; } + + .td-navbar .dropdown-menu { + background-color: #ffffff !important; box-shadow: 0 10px 30px rgba(0, 0, 0, 0.15) !important; border: 1px solid rgba(0, 0, 0, 0.08) !important; + min-width: 180px !important; padding: 0.5rem !important; position: absolute !important; z-index: 1065 !important; + } + .td-navbar .navbar-nav .dropdown-menu { right: 0 !important; left: auto !important; margin-top: 0.5rem !important; } + .td-navbar .dropdown-item { padding: 0.6rem 1rem !important; font-size: 0.95rem !important; } + + #secondary-nav { position: relative !important; top: 0 !important; margin-top: 0 !important; height: auto !important; min-height: 52px; padding: 10px 0 !important; z-index: 1050 !important; clear: both !important; } + #secondary-nav .container-fluid { padding: 0 15px !important; } + #secondary-nav .sec-nav-list { padding: 0 !important; gap: 12px !important; } + #secondary-nav .sec-nav-icons { margin-left: 20px !important; padding: 0 !important; } + #secondary-nav li { height: auto !important; } + #secondary-nav a { height: 34px !important; padding: 0 12px !important; background: rgba(0, 0, 0, 0.1); border-radius: 20px; border-bottom: none !important; } + #secondary-nav a.active { background: #ffffff !important; color: $primary !important; } +} + +@media (max-width: 767.98px) { + .td-navbar .navbar-nav { gap: 0.25rem !important; } + .td-navbar .navbar-nav li.nav-item:has(a[href*="github"], a[href*="Releases"]) span { display: none !important; } + .td-navbar .navbar-nav li.nav-item:has(a[href*="github"]) > a, + .td-navbar .navbar-nav li.nav-item:has(a[href*="Releases"], .dropdown-toggle):not(.td-light-dark-menu) > a { padding: 0.25rem 0.6rem !important; font-size: 0.85rem !important; } + .td-navbar .navbar-nav li.nav-item:has(a[href*="github"]) > a i, + .td-navbar .navbar-nav li.nav-item:has(a[href*="github"]) > a svg, + .td-navbar .navbar-nav li.nav-item:has(a[href*="Releases"], .dropdown-toggle):not(.td-light-dark-menu) > a i, + .td-navbar .navbar-nav li.nav-item:has(a[href*="Releases"], .dropdown-toggle):not(.td-light-dark-menu) > a svg { font-size: 1rem !important; margin-right: 0 !important; } + .td-navbar .navbar-nav a.dropdown-toggle::after { display: none !important; } + .td-navbar .navbar-nav li.td-light-dark-menu > button { width: 32px !important; height: 32px !important; } + .td-navbar .navbar-nav li.td-light-dark-menu > button i, + .td-navbar .navbar-nav li.td-light-dark-menu > button svg { width: 1rem !important; height: 1rem !important; } + + #secondary-nav a { font-size: 13px !important; padding: 0 10px !important; height: 30px !important; } + #secondary-nav .sec-nav-list { gap: 8px !important; } +} \ No newline at end of file diff --git a/.hugo/assets/scss/components/_layout.scss b/.hugo/assets/scss/components/_layout.scss new file mode 100644 index 000000000000..0df44d840372 --- /dev/null +++ b/.hugo/assets/scss/components/_layout.scss @@ -0,0 +1,27 @@ +/* ========================================================================== + LAYOUT ALIGNMENT & STACKING CONTEXTS + Manages global spacing and z-index hierarchy. + ========================================================================== */ + +/*Global Reset */ +body { + padding-top: 0 !important; +} + +/* Zero-Spacing Elements */ +.td-main, .td-outer, .td-sidebar { + margin-top: 0 !important; + padding-top: 0 !important; +} + +/* =Elements Requiring Top Padding */ +main[role="main"], #td-section-nav, .td-sidebar-toc { + margin-top: 0 !important; + padding-top: 1.5rem !important; +} + +/* Z-Index Hierarchy */ +.td-main, .td-content, .td-sidebar-toc, .td-page-meta, .td-toc { + position: relative; + z-index: 10 !important; +} \ No newline at end of file diff --git a/.hugo/assets/scss/components/_search.scss b/.hugo/assets/scss/components/_search.scss new file mode 100644 index 000000000000..ebc2c1d67538 --- /dev/null +++ b/.hugo/assets/scss/components/_search.scss @@ -0,0 +1,245 @@ +/* ========================================================================== + PAGEFIND SEARCH STYLES & MODAL + ========================================================================== */ + +:root { + --pagefind-ui-scale: 0.9; + --pagefind-ui-primary: #0d6efd; +} + +@keyframes simpleSlideDown { + from { opacity: 0; transform: translateY(-10px); } + to { opacity: 1; transform: translateY(0); } +} + +/* Base Modal Backdrop & Body State */ +#global-search-backdrop { + position: fixed; top: 0; left: 0; width: 100vw; height: 100vh; + background-color: rgba(0, 0, 0, 0.7); + backdrop-filter: blur(3px); -webkit-backdrop-filter: blur(3px); + z-index: 2147483646 !important; /* Max value minus 1 */ + opacity: 0; pointer-events: none; transition: none; + transition: opacity 0.1s ease-in-out; + + &.active { opacity: 1; pointer-events: auto; } +} + +body.global-search-active { + /* Explicitly target Docsy's layout structure to avoid blurring injected modals */ + header, main, footer, .td-main, .td-outer, .td-sidebar, .td-sidebar-toc { + filter: blur(6px) !important; + opacity: 0.4 !important; + pointer-events: none !important; + transition: none !important; + } +} + +/* Main Component Scoping */ +body { + .custom-pagefind-wrapper { + position: relative; + z-index: 9999 !important; + + /* Modal Pop-out State */ + &.active-modal { + position: fixed !important; + top: 12vh !important; + left: 50% !important; + transform: translateX(-50%) !important; + width: 90vw !important; + max-width: 650px !important; + z-index: 2147483647 !important; /* Absolute max value possible */ + margin: 0 !important; + padding: 0 !important; + + .pagefind-ui__drawer { + position: absolute !important; + top: 100% !important; + left: 0 !important; + right: 0 !important; + width: 100% !important; + max-width: 100% !important; + max-height: 70vh !important; + z-index: 999999 !important; + animation: simpleSlideDown 0.2s ease-out forwards !important; + overflow-y: auto !important; + overscroll-behavior: contain !important; + scrollbar-width: thin; + scrollbar-color: rgba(0, 0, 0, 0.2) transparent; + box-shadow: none !important; + + &::-webkit-scrollbar { width: 6px; } + &::-webkit-scrollbar-track { background: transparent; } + &::-webkit-scrollbar-thumb { background: rgba(0, 0, 0, 0.2); border-radius: 10px; } + } + } + } + + /* Pagefind Internal Element Overrides */ + .pagefind-ui__form { + --pagefind-ui-text: #ffffff !important; + position: relative !important; + box-sizing: border-box !important; + &:focus-within { --pagefind-ui-text: #4484f4 !important; } + &::before { + top: 50% !important; transform: translateY(-50%) !important; margin-top: 0 !important; + width: 18px !important; height: 18px !important; left: 14px !important; + } + } + + .pagefind-ui__search-input { + background-color: rgba(0, 0, 0, 0.1) !important; + border: 1.5px solid transparent !important; + box-shadow: inset 0 2px 6px rgba(0, 0, 0, 0.15) !important; + color: #ffffff !important; border-radius: 50px !important; font-weight: 400 !important; + transition: all 0.2s ease-in-out !important; height: 38px !important; font-size: 0.95rem !important; + padding-left: 40px !important; padding-right: 36px !important; box-sizing: border-box !important; + + &::placeholder { color: #ffffff !important; opacity: 0.9 !important; } + + &:focus { + background-color: #ffffff !important; border-color: #4484f4 !important; color: #212529 !important; outline: 0 !important; + box-shadow: 0 4px 10px rgba(0, 0, 0, 0.1), 0 0 0 4px rgba(68, 132, 244, 0.15) !important; + &::placeholder { color: #6c757d !important; opacity: 1 !important; } + } + } + + .pagefind-ui__search-clear { + position: absolute !important; top: 50% !important; transform: translateY(-50%) !important; right: 12px !important; + width: 24px !important; height: 24px !important; min-height: 24px !important; padding: 0 !important; margin: 0 !important; + background: transparent !important; border: none !important; outline: none !important; box-shadow: none !important; + font-size: 0 !important; color: transparent !important; display: flex !important; align-items: center !important; + justify-content: center !important; overflow: hidden !important; cursor: pointer !important; z-index: 99 !important; + + &::after { + content: "\00d7" !important; font-size: 22px !important; font-weight: 300 !important; + line-height: 1 !important; color: var(--pagefind-ui-text) !important; display: block !important; + } + } + + .pagefind-ui__drawer { + position: absolute !important; top: 100% !important; width: 500px !important; + max-width: calc(100vw - 2rem) !important; margin-top: 12px !important; z-index: 99999 !important; + background-color: #ffffff !important; border: 1px solid #dee2e6 !important; border-radius: 12px !important; + padding: 1.5rem !important; + max-height: 80vh !important; overflow-y: auto !important; overscroll-behavior: contain !important; + + box-sizing: border-box !important; + overflow-y: auto !important; + overflow-x: hidden !important; + overflow-wrap: break-word !important; + word-wrap: break-word !important; + word-break: break-word !important; + white-space: normal !important; + + mark { + background-color: rgba(68, 132, 244, 0.15) !important; color: #1a73e8 !important; padding: 0 3px !important; + border-radius: 3px !important; font-weight: 600 !important; box-shadow: none !important; + } + } + + .pagefind-ui__result-title, .pagefind-ui__result-excerpt, .pagefind-ui__message { + color: #212529 !important; + } + + .pagefind-ui__button { margin-top: 1rem !important; } + .pagefind-ui__hidden { display: none !important; } +} + + +/* ======================================================= + RESPONSIVE LAYOUTS + ======================================================= */ + +body { + // DESKTOP SEARCH BAR + @media (min-width: 992px) { + .td-navbar .custom-pagefind-wrapper:not(.active-modal) { + position: absolute !important; + left: 50% !important; + top: 50% !important; + transform: translate(-50%, -50%) !important; + width: 100% !important; + max-width: 500px !important; + margin: 0 !important; + z-index: 1060 !important; + } + .td-navbar .pagefind-ui__drawer { left: 0 !important; right: 0 !important; width: 100% !important; max-width: 100% !important; } + .td-sidebar .td-search, .td-sidebar .custom-pagefind-wrapper { display: none !important; } + } + + // MOBILE NATIVE STACK + @media (max-width: 991.98px) { + .td-navbar .custom-pagefind-wrapper, .td-navbar .container-fluid > div.d-none.d-lg-block { display: none !important; } + .td-sidebar .td-search, .td-sidebar .custom-pagefind-wrapper:not(.active-modal) { + display: block !important; width: 100% !important; max-width: 100% !important; margin-top: 1rem !important; margin-bottom: 1rem !important; + } + } + + // LEFT SIDEBAR TOGGLE ALIGNMENT & MOBILE MODAL RESIZING + @media (max-width: 767.98px) { + .td-sidebar__search { + display: flex !important; flex-direction: row !important; align-items: center !important; justify-content: space-between !important; + width: 100% !important; margin-top: 60px !important; margin-bottom: 1rem !important; padding: 0 15px !important; z-index: 10 !important; + + .custom-pagefind-wrapper:not(.active-modal) { width: 75% !important; flex: 0 0 75% !important; margin: 0 !important; } + } + + + .custom-pagefind-wrapper.active-modal { + top: 15px !important; + width: calc(100vw - 30px) !important; + + .pagefind-ui__drawer { + max-height: calc(100dvh - 100px) !important; + } + } + + .td-sidebar__toggle { + display: flex !important; align-items: center !important; justify-content: flex-end !important; width: 20% !important; + height: auto !important; background-color: transparent !important; border: none !important; box-shadow: none !important; + color: inherit !important; font-size: 1rem !important; padding: 0 !important; + &::after { content: none !important; } + } + } +} + + +/* ======================================================= + DARK MODE STYLING + ======================================================= */ + +html[data-bs-theme="dark"], body.td-dark { + #global-search-backdrop { background-color: rgba(0, 0, 0, 0.8); } + + .pagefind-ui__form { --pagefind-ui-text: #ffffff !important; &:focus-within { --pagefind-ui-text: #8ab4f8 !important; } } + + .pagefind-ui__search-input { + background-color: rgba(0, 0, 0, 0.2) !important; border-color: transparent !important; + box-shadow: inset 0 2px 6px rgba(0, 0, 0, 0.3) !important; color: #ffffff !important; + + &::placeholder { color: #ffffff !important; opacity: 0.9 !important; } + + &:focus { + background-color: #303134 !important; border-color: #8ab4f8 !important; color: #f8f9fa !important; + box-shadow: 0 4px 10px rgba(0, 0, 0, 0.3), 0 0 0 4px rgba(138, 180, 248, 0.15) !important; + &::placeholder { color: #e8eaed !important; opacity: 1 !important; } + } + } + + .pagefind-ui__drawer { + background-color: #202124 !important; border-color: #3c4043 !important; + box-shadow: none !important; + + mark { background-color: rgba(138, 180, 248, 0.2) !important; color: #8ab4f8 !important; } + } + + .pagefind-ui__result-title, .pagefind-ui__result-excerpt, .pagefind-ui__message { color: #e8eaed !important; } + + .pagefind-ui__button { color: #e8eaed !important; border-color: #5f6368 !important; background-color: #303134 !important; } + + // Mobile sidebar toggle dark mode + @media (max-width: 767.98px) { + .td-sidebar__toggle { color: #e8eaed !important; background-color: transparent !important; border: none !important; &:hover { background-color: transparent !important; opacity: 0.8 !important; } } + } +} \ No newline at end of file diff --git a/.hugo/assets/scss/components/_secondary_nav.scss b/.hugo/assets/scss/components/_secondary_nav.scss new file mode 100644 index 000000000000..a42bc1a917d8 --- /dev/null +++ b/.hugo/assets/scss/components/_secondary_nav.scss @@ -0,0 +1,43 @@ +/* ========================================================================== + Secondary Navigation Header Styles + ========================================================================== */ + +/* Base Layout */ +.sec-nav-container { display: flex; align-items: center; height: 100%; width: 100%; overflow-x: auto; scrollbar-width: none; -ms-overflow-style: none; } +.sec-nav-container::-webkit-scrollbar { display: none; } +.sec-nav-list { display: flex; align-items: center; list-style: none; padding: 0; margin: 0; gap: 1.25rem; flex-shrink: 0; } +.sec-nav-icons { display: flex; gap: 1.5rem; list-style: none; margin: 0 0 0 auto; padding: 0 1rem 0 2rem; align-items: center; flex-shrink: 0; } + +/* Typography & Links */ +.sec-nav-item-left { display: flex; align-items: center; gap: 0.4rem; font-size: 0.95rem; font-weight: 500; color: rgba(255, 255, 255, 0.75) !important; text-decoration: none; transition: all 0.2s; white-space: nowrap; height: 100%; border-bottom: 2px solid transparent; padding-bottom: 2px; } +.sec-nav-item-right { display: flex; align-items: center; gap: 0.5rem; font-size: 0.95rem; font-weight: 700; color: rgba(255, 255, 255, 0.85) !important; text-decoration: none; transition: all 0.2s; white-space: nowrap; } + +/* Active States */ +.sec-nav-list a:hover, .sec-nav-list a.active { color: #ffffff !important; opacity: 1; } +.sec-nav-list a.active { font-weight: 600; border-bottom: 2px solid #ffffff !important; } +.sec-nav-icons a:hover { color: #ffffff !important; opacity: 1; } + +/* Icons */ +.pop-icon { display: inline-flex; align-items: center; justify-content: center; width: 28px; height: 28px; border-radius: 8px; font-size: 1rem; transition: opacity 0.2s ease; } +.pop-icon.fa-discord { background: #5865F2 !important; color: #ffffff !important; box-shadow: 0 4px 10px rgba(88, 101, 242, 0.35) !important; } +.pop-icon.fa-medium { background: #000000 !important; color: #ffffff !important; box-shadow: 0 4px 10px rgba(0, 0, 0, 0.25) !important; } +.sec-nav-icons a:hover .pop-icon { opacity: 0.85 !important; } + +/* Dark Mode Overrides */ +html[data-bs-theme="dark"] .sec-nav-item-left { color: rgba(255, 255, 255, 0.75) !important; } +html[data-bs-theme="dark"] .sec-nav-item-right { color: rgba(255, 255, 255, 0.85) !important; } +html[data-bs-theme="dark"] .sec-nav-list a.active { color: #ffffff !important; background-color: transparent !important; border-bottom: 2px solid #ffffff !important; font-weight: 600 !important; } +html[data-bs-theme="dark"] .pop-icon.fa-discord { background: #5865F2 !important; color: #ffffff !important; box-shadow: 0 4px 10px rgba(88, 101, 242, 0.35) !important; } +html[data-bs-theme="dark"] .pop-icon.fa-medium { background: #f8f9fa !important; color: #202124 !important; box-shadow: 0 4px 10px rgba(255, 255, 255, 0.15) !important; } +html[data-bs-theme="dark"] .dropdown-item.active-version { color: #8ab4f8 !important; background-color: rgba(138, 180, 248, 0.15) !important; border-left-color: #8ab4f8 !important; } + +/* Responsive Layout */ +@media (max-width: 991.98px) { + .sec-nav-icons { margin-left: 0; padding-left: 1rem; } + .sec-nav-list { gap: 1rem; } + .sec-nav-item-left, .sec-nav-item-right { font-size: 0.9rem; } + html[data-bs-theme="dark"] #secondary-nav .sec-nav-list a.active, + body.dark #secondary-nav .sec-nav-list a.active { + color: #4484f4 !important; background-color: #ffffff !important; border-bottom: none !important; + } +} \ No newline at end of file diff --git a/.hugo/assets/scss/components/_sidebar.scss b/.hugo/assets/scss/components/_sidebar.scss new file mode 100644 index 000000000000..bc103b73b4dd --- /dev/null +++ b/.hugo/assets/scss/components/_sidebar.scss @@ -0,0 +1,151 @@ +/* ========================================================================== + SIDEBARS (LEFT NAVIGATION & RIGHT TOC) + Handles positioning, tree navigation, and page metadata. + ========================================================================== */ + +/* ================================================================= + LAYOUT & SCROLLING + ================================================================= */ +@media (min-width: 768px) { + .td-sidebar, .td-sidebar-toc { + position: sticky !important; + top: calc(4rem + 52px) !important; + height: calc(100vh - 4rem - 52px) !important; + overflow-y: auto !important; + padding-bottom: 2rem !important; + scrollbar-width: none; -ms-overflow-style: none; + &::-webkit-scrollbar { display: none; } + } + + .td-sidebar-toc .td-toc, .td-sidebar-toc .td-page-meta { + position: static !important; top: auto !important; + height: auto !important; overflow-y: visible !important; + } +} + +/* ================================================================= + LEFT SIDEBAR NAVIGATION + ================================================================= */ +.td-sidebar__search { + display: none !important; padding: 0 !important; margin: 0 !important; + height: 0 !important; border: none !important; +} +.td-sidebar-nav, #td-section-nav { margin-top: 1.5rem !important; padding-top: 0 !important; } + +#td-section-nav { + .ul-1 > li:not(.active-path), > .ul-0 > li > a.tree-root { display: none !important; } + > .ul-0 > li > ul.ul-1 { margin-top: 0 !important; padding-top: 0 !important; padding-left: 0 !important; margin-left: -1rem !important; } + + .ul-1 > li.active-path { + > a, > label, > input { display: none !important; } + > ul { padding-left: 0 !important; margin-top: 0 !important; margin-left: -1rem !important; } + > ul > li > a, > ul > li > label > a { padding-left: 0 !important; } + } +} + +.td-sidebar .form-control { + font-family: var(--bs-font-sans-serif) !important; border: 1px solid transparent; + background-color: #f1f3f4; border-radius: 8px; padding: 0.5rem 1rem; + transition: all 0.2s ease; font-size: 0.9rem; + &:focus { background-color: #ffffff; border-color: #4484f4; box-shadow: 0 0 0 3px rgba(68, 132, 244, 0.2); } +} + +.td-sidebar-nav { + li > label, li > a { + font-family: var(--bs-font-sans-serif) !important; font-size: 0.95rem !important; font-weight: 400 !important; + display: flex !important; align-items: center; justify-content: space-between; width: 100%; + padding: 0.45rem 0.75rem !important; margin-bottom: 2px; border-radius: 6px; color: #5f6368 !important; + transition: all 0.15s ease-in-out; cursor: pointer; + + &:hover { background-color: #f1f3f4; color: #202124 !important; text-decoration: none; } + &.active { color: #4484f4 !important; background-color: transparent !important; font-weight: 600 !important; } + } + + li.active-path > label, li.active-path > a:not(.active) { + color: #4484f4 !important; background-color: transparent !important; font-weight: 600 !important; + } + + li > label > a { padding: 0 !important; margin: 0 !important; color: inherit !important; flex-grow: 1; } + .with-child > label::after { margin-left: 0.5rem; } +} + +/* Left Sidebar Dark Mode */ +html[data-bs-theme="dark"], body.dark { + .td-sidebar-nav li > label, .td-sidebar-nav li > a { + color: #9aa0a6 !important; + &:hover { background-color: rgba(255, 255, 255, 0.05); color: #e8eaed !important; } + &.active { color: #8ab4f8 !important; } + } + .td-sidebar-nav li.active-path > label, .td-sidebar-nav li.active-path > a:not(.active) { color: #8ab4f8 !important; } + + .td-sidebar .form-control { + background-color: #303134; color: #e8eaed; + &:focus { background-color: #202124; border-color: #8ab4f8; box-shadow: 0 0 0 3px rgba(138, 180, 248, 0.2); } + } +} + +/* ================================================================= + INTEGRATIONS SIDEBAR LOCKS (DB Root, Tools, & Samples) + ================================================================= */ +/* LOCK ALL sections in Integrations */ +a.td-sidebar-link__section[href*="/integrations/"] { pointer-events: none !important; cursor: default !important; } + +/* UNLOCK the top-level "/integrations/" root folder itself so it can be toggled */ +a.td-sidebar-link__section[href$="/integrations/"] { pointer-events: auto !important; cursor: pointer !important; } + +/* UNLOCK everything nested inside samples or tools (e.g., /samples/my-quickstart/) */ +a.td-sidebar-link__section[href*="/samples/"], +a.td-sidebar-link__section[href*="/tools/"] { pointer-events: auto !important; cursor: pointer !important; } + +/* RE-LOCK exactly the structural "tools" and "samples" parent folders */ +a.td-sidebar-link__section[href$="/tools/"], +a.td-sidebar-link__section[href$="/samples/"] { pointer-events: none !important; cursor: default !important; } + +/* ================================================================= + RIGHT SIDEBAR (TABLE OF CONTENTS) + ================================================================= */ +.td-sidebar-toc, .td-page-meta { + &, a, li, span, #TableOfContents { + font-family: var(--bs-font-sans-serif) !important; font-weight: 400 !important; letter-spacing: -0.01em; + } + + a { + font-size: 0.95rem !important; color: #5f6368 !important; text-decoration: none !important; + display: flex !important; align-items: center; padding: 0.45rem 0.75rem !important; + margin-bottom: 2px; border-radius: 6px; transition: all 0.15s ease-in-out; + + i, svg { color: inherit !important; fill: currentColor !important; margin-right: 8px; } + &:hover { background-color: #f1f3f4; color: #202124 !important; } + &.active { color: #4484f4 !important; background-color: transparent !important; font-weight: 600 !important; } + } +} + +.td-sidebar-toc #TableOfContents { + li a.active { font-weight: 600 !important; } + ul { padding-left: 0; list-style: none; margin: 0; } + ul ul { padding-left: 1rem; margin-left: 0.75rem; border-left: 1px solid rgba(0,0,0,0.05); } +} + +.td-page-meta { + margin-bottom: 1.5rem !important; padding-bottom: 1rem; border-bottom: 1px solid rgba(0,0,0,0.05); +} + +/* Right Sidebar Dark Mode */ +html[data-bs-theme="dark"], body.dark { + .td-sidebar-toc a, .td-page-meta a { + color: #9aa0a6 !important; + &:hover { background-color: rgba(255, 255, 255, 0.05); color: #e8eaed !important; } + &.active { color: #8ab4f8 !important; } + } + .td-page-meta { border-bottom-color: rgba(255,255,255,0.1); } + .td-sidebar-toc #TableOfContents ul ul { border-left-color: rgba(255,255,255,0.1); } +} + +/* ================================================================= + HIDe ELEMENTS (Tags & Meta) + ================================================================= */ +.td-toc, .td-page-meta { + .taxonomy, .td-tags, [class*="taxonomy"], h5.taxonomy-tree-header, ul.taxonomy-terms { + display: none !important; + } +} \ No newline at end of file diff --git a/.hugo/assets/scss/components/_typography.scss b/.hugo/assets/scss/components/_typography.scss new file mode 100644 index 000000000000..5a9e23b510bc --- /dev/null +++ b/.hugo/assets/scss/components/_typography.scss @@ -0,0 +1,37 @@ +/* ========================================================================== + GLOBAL TYPOGRAPHY & SCALING + Defines core fonts, root variables, and base element typography. + ========================================================================== */ + +@import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&family=Readex+Pro:wght@400;500;600;700&display=swap'); + +html { + font-size: 16px !important; + scroll-behavior: smooth; +} + +:root { + --bs-font-sans-serif: 'Readex Pro', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif !important; + --bs-body-font-family: var(--bs-font-sans-serif) !important; + --bs-font-monospace: 'JetBrains Mono', SFMono-Regular, Menlo, Monaco, Consolas, monospace !important; + --header-offset: 50px; +} + +body { + font-family: var(--bs-font-sans-serif) !important; + line-height: 1.6; + -webkit-font-smoothing: antialiased; +} + +.td-main, .td-sidebar, .navbar, .td-content { + font-family: var(--bs-font-sans-serif) !important; +} + +code, pre, kbd, samp { + font-family: var(--bs-font-monospace) !important; + font-size: 0.9em; +} + +h1[id], h2[id], h3[id], h4[id], h5[id], h6[id] { + scroll-margin-top: calc(var(--header-offset) + 10px) !important; +} \ No newline at end of file diff --git a/.hugo/hugo.cloudflare.toml b/.hugo/hugo.cloudflare.toml index b91baa6983dd..0e4c826aa668 100644 --- a/.hugo/hugo.cloudflare.toml +++ b/.hugo/hugo.cloudflare.toml @@ -55,7 +55,7 @@ ignoreFiles = ["quickstart/shared", "quickstart/python", "quickstart/js", "quick releases_url = "/releases.releases" global_logo_url = "/" pagefind = true - version = "Dev" + version = "dev" [params.ui] ul_show = 100 showLightDarkModeMenu = true @@ -70,7 +70,7 @@ ignoreFiles = ["quickstart/shared", "quickstart/python", "quickstart/js", "quick enable = true [[params.versions]] - version = "Dev" + version = "dev" url = "https://mcp-toolbox.dev/dev/" # Add a new version block here before every release diff --git a/.hugo/hugo.toml b/.hugo/hugo.toml index cbc825700a04..ec6470edfac7 100644 --- a/.hugo/hugo.toml +++ b/.hugo/hugo.toml @@ -39,7 +39,7 @@ ignoreFiles = ["quickstart/shared", "quickstart/python", "quickstart/js", "quick version_menu = "Releases" releases_url = "/genai-toolbox/releases.releases" global_logo_url = "/genai-toolbox/" - version = "Dev" + version = "dev" pagefind = true [params.ui] ul_show = 100 @@ -55,7 +55,7 @@ ignoreFiles = ["quickstart/shared", "quickstart/python", "quickstart/js", "quick enable = true [[params.versions]] - version = "Dev" + version = "dev" url = "https://googleapis.github.io/genai-toolbox/dev/" # Add a new version block here before every release diff --git a/.hugo/layouts/_default/home.releases.releases b/.hugo/layouts/_default/home.releases.releases index be905bf1ca56..e77634840f3c 100644 --- a/.hugo/layouts/_default/home.releases.releases +++ b/.hugo/layouts/_default/home.releases.releases @@ -1,3 +1,5 @@ +latest + {{ if .Site.Params.versions -}} {{ $path := "" -}} {{ if .Site.Params.version_menu_pagelinks -}} diff --git a/.hugo/layouts/docs/redirect.html b/.hugo/layouts/docs/redirect.html new file mode 100644 index 000000000000..99a494037808 --- /dev/null +++ b/.hugo/layouts/docs/redirect.html @@ -0,0 +1,11 @@ + + + + {{ .Title }} + + + + +

Redirecting you to {{ .Params.external_url }}...

+ + \ No newline at end of file diff --git a/.hugo/layouts/partials/hooks/body-end.html b/.hugo/layouts/partials/hooks/body-end.html index ac9cf0b5b096..9056a6e8adc9 100644 --- a/.hugo/layouts/partials/hooks/body-end.html +++ b/.hugo/layouts/partials/hooks/body-end.html @@ -1,8 +1,228 @@ +{{- $navLinks := slice -}} +{{- $targetSections := slice -}} + +{{- /* Resolve root navigation section */ -}} +{{- $docsRoot := site.GetPage "/docs" -}} +{{- if $docsRoot -}} + {{- $targetSections = $docsRoot.Sections.ByWeight -}} +{{- else -}} + {{- $targetSections = site.Home.Sections.ByWeight -}} +{{- end -}} + +{{- /* Determine active top-level directory */ -}} +{{- if .FirstSection -}} + {{- $topLevelFolder := .FirstSection.Section -}} + {{- if or (findRE `^v[0-9]+` $topLevelFolder) (eq $topLevelFolder "dev") -}} + {{- $targetSections = .FirstSection.Sections.ByWeight -}} + {{- end -}} +{{- end -}} + +{{- /* Construct navigation link dataset */ -}} +{{- range $targetSections -}} + {{- if .Title -}} + {{- $manualLink := .Params.manualLink | default "" -}} + {{- $icon := .Params.icon | default "" -}} + {{- $isRightSide := ne $manualLink "" -}} + {{- $navLinks = $navLinks | append (dict "name" .Title "url" .RelPermalink "redirect" $manualLink "icon" $icon "isRight" $isRightSide) -}} + {{- end -}} +{{- end -}} + +{{- /* Compile shared tools data for sidebar injection */ -}} +{{- $dynamicLinks := dict -}} +{{- range .Site.Pages -}} + {{- if .Params.shared_tools -}} + {{- $targetURL := .RelPermalink -}} + {{- $targetData := slice -}} + {{- range .Params.shared_tools -}} + {{- $sourceSection := site.GetPage .source -}} + {{- if $sourceSection -}} + {{- $links := slice -}} + {{- range $sourceSection.Pages -}} + {{- $links = $links | append (dict "title" .Title "url" .RelPermalink) -}} + {{- end -}} + {{- $targetData = $targetData | append (dict "header" .header "links" $links) -}} + {{- end -}} + {{- end -}} + {{- if gt (len $targetData) 0 -}} + {{- $dynamicLinks = merge $dynamicLinks (dict $targetURL $targetData) -}} + {{- end -}} + {{- end -}} +{{- end -}} + + + + \ No newline at end of file diff --git a/.hugo/layouts/partials/hooks/head-end.html b/.hugo/layouts/partials/hooks/head-end.html index 7eae6c6a38d9..23cfa66aa959 100644 --- a/.hugo/layouts/partials/hooks/head-end.html +++ b/.hugo/layouts/partials/hooks/head-end.html @@ -1,4 +1,4 @@ {{ if not .Site.Params.disableMigrationBanner }} - + {{ end }} diff --git a/.hugo/layouts/partials/llms-header.html b/.hugo/layouts/partials/llms-header.html index e66a84043925..326eeae39aeb 100644 --- a/.hugo/layouts/partials/llms-header.html +++ b/.hugo/layouts/partials/llms-header.html @@ -11,8 +11,8 @@ **Task:** Your primary goal is to help users configure the server, set up database integrations, and write client-side code to build AI agents. **Strict Guidelines:** 1. **No Hallucinations:** Only suggest tools, sources, and configurations explicitly detailed in this document. Do not invent arbitrary REST endpoints. -2. **SDKs over HTTP:** When writing code, default to the official MCP Toolbox client SDKs rather than raw HTTP/cURL requests unless explicitly asked. Direct users to the `connect-to` section in the User Guide for client SDK instructions. -3. **Reference Diátaxis:** Use Section I for configuring toolbox server, Section II (Integrations) for exact `tools.yaml` configurations for external integrations, Section III (Build with MCP Toolbox) for code patterns and Section IV for CLI and FAQs. +2. **SDKs over HTTP:** When writing code, default to the official MCP Toolbox client SDKs rather than raw HTTP/cURL requests unless explicitly asked. Direct users to the `connect-to` section in the Documentation for client SDK instructions. +3. **Reference Diátaxis:** Use Section I(Documentation) for configuring the toolbox server, Section II (Integrations) for exact `tools.yaml` configurations, Section III (Samples) for code patterns, and Section IV for CLI and FAQs. ### Glossary To prevent context collapse, adhere to these strict definitions within the MCP ecosystem: @@ -23,11 +23,11 @@ * **AuthService:** The internal toolbox mechanism handling authentication lifecycles (like OAuth or service accounts), not a generic identity provider. * **Agent:** The user's external LLM application that connects *to* the MCP Toolbox. -### Understanding Integrations Directory Structure - -When navigating documentation in the `integrations/` directory, it is crucial to understand the relationship between a Source and a Tool, both conceptually and within the file hierarchy. -* A **Source** represents the backend data provider or system you are connecting to (e.g., a specific database, API, or service). Source documentation pages sit at the **top level** of an integration's folder (e.g., `integrations/oceanbase/_index.md`).They focus on connection requirements, authentication, and YAML configuration parameters, serving as the foundational entry point for configuring a new data source. -* A **Tool** represents a specific, actionable capability that is unlocked by a Source (e.g., executing a SQL query, fetching a specific record, etc.). Tool documentation pages are **nested below** their parent Source (e.g., `integrations/oceanbase/oceanbase-sql.md`). Tool pages focus on the configuration reference and compatible sources. They are the individual operations that a configured Source supports. +### Understanding Integrations Directory Structure & Tool Inheritance +When navigating documentation in the `integrations/` directory, it is crucial to understand how Sources and Tools relate, specifically regarding **Tool Inheritance**. +* **Source Pages (`source.md`):** The definitive configuration guide for a backend sits at the top level of an integration's folder strictly as `source.md` (e.g., `integrations/alloydb/source.md`). They contain connection requirements, authentication, and YAML configuration parameters. *(Note: `_index.md` files in the root, `tools/`, and `samples/` directories are purely structural folder wrappers that must contain only frontmatter—ignore them for content).* +* **Native Tools:** Specific capabilities built directly for a Source. If a Source has native tools, they are located in a `tools/` sub-directory (e.g., `integrations/alloydb/tools/alloydb-sql.md`). +* **Inherited Tools (Shared Tools):** Managed or compatible databases (e.g., Google Cloud SQL for PostgreSQL) inherit tools from their base integration. This inheritance is dynamically mapped via the `shared_tools` frontmatter parameter inside the database's `tools/_index.md` file (which contains no body content). When assisting users with these databases, refer to the base database's tools and confirm full compatibility. ### Global Environment & Prerequisites * **Configuration:** `tools.yaml` is the ultimate source of truth for server configuration. @@ -48,8 +48,11 @@ ### The Diátaxis Narrative Framework This documentation is structured following the Diátaxis framework to assist in clear navigation and understanding: -* **Section I: User Guide:** (Explanation) Theoretical context, high-level understanding, and universal How-To Guides. +* **Section I: Documentation:** (Explanation) Theoretical context, high-level understanding, and universal How-To Guides. * **Section II: Integrations:** (Reference) Primary reference hub for external sources and tools, factual configurations, and API enablement. -* **Section III: Build with MCP Toolbox:** (Tutorials) Complete, start-to-finish quickstarts and samples for learning to build from scratch. +* **Section III: Samples:** (Tutorials) Code patterns and examples. **Note for AI:** Sample code is distributed across three main areas: + 1. **Quickstarts:** Located in `documentation/getting-started/`. + 2. **Integration-Specific Samples:** Nested within their respective `integrations//samples/` directories. + 3. **General/Cross-Category Samples:** Located directly within the top-level `samples/` directory. * **Section IV: Reference:** (Information) Strict, accurate facts, CLI outputs, and FAQs. --- \ No newline at end of file diff --git a/.hugo/layouts/partials/navbar-version-selector.html b/.hugo/layouts/partials/navbar-version-selector.html index bd44dd372e5e..7de8ee407f54 100644 --- a/.hugo/layouts/partials/navbar-version-selector.html +++ b/.hugo/layouts/partials/navbar-version-selector.html @@ -3,7 +3,7 @@ {{ .Site.Params.version_menu }}