docs!: update docsite

.ci/lint-docs-source-page.sh

@@ -0,0 +1,136 @@
+#!/bin/bash
+set -e
+
+
+python3 - << 'EOF'
+"""
+MCP TOOLBOX: SOURCE PAGE LINTER
+===============================
+This script enforces a standardized structure for integration Source pages 
+(source.md files). It ensures users can predictably find connection details
+and configurations across all database integrations.
+
+Note: The structural _index.md folder wrappers are intentionally ignored 
+by this script as they should only contain YAML frontmatter.
+
+MAINTENANCE GUIDE:
+------------------
+1. TO ADD A NEW HEADING: 
+   Add the exact heading text to the 'ALLOWED_ORDER' list in the desired 
+   sequence.
+
+2. TO MAKE A HEADING MANDATORY/OPTIONAL: 
+   Add or remove the heading text in the 'REQUIRED' set. 
+
+3. TO IGNORE NEW CONTENT TYPES:
+   Update the regex in the 'clean_body' variable to strip out 
+   Markdown before linting.
+
+4. SCOPE:
+   This script only targets docs/en/integrations/**/source.md.
+"""
+
+import os
+import re
+import sys
+from pathlib import Path
+
+# --- CONFIGURATION ---
+ALLOWED_ORDER = [
+    "About",
+    "Available Tools",
+    "Requirements",
+    "Example",
+    "Reference",
+    "Advanced Usage",
+    "Troubleshooting",
+    "Additional Resources"
+]
+REQUIRED = {"About", "Example", "Reference"}
+
+# Regex to catch any variation of the list-tools shortcode
+SHORTCODE_PATTERN = r"\{\{<\s*list-tools.*?>\}\}"
+# ---------------------
+
+integration_dir = Path("./docs/en/integrations")
+if not integration_dir.exists():
+    print("Info: Directory './docs/en/integrations' not found. Skipping linting.")
+    sys.exit(0)
+
+has_errors = False
+source_pages_found = 0
+
+# ONLY scan files specifically named "source.md"
+for filepath in integration_dir.rglob("source.md"):
+    source_pages_found += 1
+    file_errors = False
+
+    if filepath.parent.parent != integration_dir:
+        continue
+
+    with open(filepath, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    match = re.match(r'^\s*---\s*\n(.*?)\n---\s*(.*)', content, re.DOTALL)
+    if match:
+        frontmatter, body = match.group(1), match.group(2)
+    else:
+        print(f"[{filepath}] Error: Missing or invalid YAML frontmatter.")
+        has_errors = True
+        continue
+
+    # 1. Check for linkTitle: "Source" in frontmatter
+    link_title_match = re.search(r"^linkTitle:\s*[\"']?(.*?)[\"']?\s*$", frontmatter, re.MULTILINE)
+    if not link_title_match or link_title_match.group(1).strip() != "Source":
+        print(f"[{filepath}] Error: Frontmatter must contain exactly linkTitle: \"Source\".")
+        file_errors = True
+
+    # 2. Check for weight: 1 in frontmatter
+    weight_match = re.search(r"^weight:\s*[\"']?(\d+)[\"']?\s*$", frontmatter, re.MULTILINE)
+    if not weight_match or weight_match.group(1).strip() != "1":
+        print(f"[{filepath}] Error: Frontmatter must contain exactly weight: 1.")
+        file_errors = True
+
+    # 3. Check Shortcode Placement & Available Tools Section (Only if present)
+    tools_section_match = re.search(r"^##\s+Available Tools\s*(.*?)(?=^##\s|\Z)", body, re.MULTILINE | re.DOTALL)
+    if tools_section_match:
+        if not re.search(SHORTCODE_PATTERN, tools_section_match.group(1)):
+            print(f"[{filepath}] Error: The list-tools shortcode must be placed under the '## Available Tools' heading.")
+            file_errors = True
+
+    # Strip code blocks from body to avoid linting example markdown headings
+    clean_body = re.sub(r"```.*?```", "", body, flags=re.DOTALL)
+
+    if re.search(r"^#\s+\w+", clean_body, re.MULTILINE):
+        print(f"[{filepath}] Error: H1 (#) headings are forbidden in the body.")
+        file_errors = True
+
+    h2s = [h.strip() for h in re.findall(r"^##\s+(.*)", clean_body, re.MULTILINE)]
+
+    # Missing Required Headings
+    missing = REQUIRED - set(h2s)
+    if missing:
+        print(f"[{filepath}] Error: Missing required H2 headings: {missing}")
+        file_errors = True
+
+    if unauthorized := (set(h2s) - set(ALLOWED_ORDER)):
+        print(f"[{filepath}] Error: Unauthorized H2s found: {unauthorized}")
+        file_errors = True
+
+    # 5. Order Check
+    if [h for h in h2s if h in ALLOWED_ORDER] != [h for h in ALLOWED_ORDER if h in h2s]:
+        print(f"[{filepath}] Error: Headings out of order. Reference: {ALLOWED_ORDER}")
+        file_errors = True
+
+    if file_errors: has_errors = True
+
+# Handle final output based on what was found
+if source_pages_found == 0:
+    print("Info: No 'source.md' files found in integrations. Passing gracefully.")
+    sys.exit(0)
+elif has_errors:
+    print(f"\nLinting failed. Please fix the structure errors in the {source_pages_found} 'source.md' file(s) above.")
+    sys.exit(1)
+else:
+    print(f"Success: {source_pages_found} 'source.md' file(s) passed structure validation.")
+EOF

.ci/lint-docs-tool-page.sh

@@ -0,0 +1,155 @@
+#!/bin/bash
+set -e
+
+python3 - << 'EOF'
+"""
+MCP TOOLBOX: TOOL PAGE LINTER
+=============================
+This script enforces a standardized structure for individual Tool pages 
+and their parent directory wrappers. It ensures LLM agents can parse 
+tool capabilities and parameter definitions reliably.
+
+MAINTENANCE GUIDE:
+------------------
+1. TO ADD A NEW HEADING: 
+   Add the exact heading text to the 'ALLOWED_ORDER' list in the desired 
+   sequence.
+
+2. TO MAKE A HEADING MANDATORY/OPTIONAL: 
+   Add or remove the heading text in the 'REQUIRED' set.
+
+3. TO UPDATE SHORTCODE LOGIC:
+   If the shortcode name changes, update the 'SHORTCODE_PATTERN' variable.
+
+4. SCOPE & BEHAVIOR:
+   This script targets all .md files in docs/en/integrations/**/tools/.
+   - For `_index.md` files: It only validates the frontmatter (requiring 
+     `title: "Tools"` and `weight: 2`) and ignores the body.
+   - For regular tool files: It validates H1/H2 hierarchy, checks for 
+     required headings ("About", "Example"), and enforces that the 
+     `{{< compatible-sources >}}` shortcode is paired with the 
+     "## Compatible Sources" heading.
+"""
+
+import os
+import re
+import sys
+from pathlib import Path
+
+# --- CONFIGURATION ---
+ALLOWED_ORDER = [
+    "About",
+    "Compatible Sources",
+    "Requirements",
+    "Parameters",
+    "Example",
+    "Output Format",
+    "Reference",
+    "Advanced Usage",
+    "Troubleshooting",
+    "Additional Resources"
+]
+REQUIRED = {"About", "Example"}
+SHORTCODE_PATTERN = r"\{\{<\s*compatible-sources.*?>\}\}"
+# ---------------------
+
+integration_dir = Path("./docs/en/integrations")
+if not integration_dir.exists():
+    print("Info: Directory './docs/en/integrations' not found. Skipping linting.")
+    sys.exit(0)
+
+has_errors = False
+tools_pages_found = 0
+
+# Specifically target the tools directories
+for filepath in integration_dir.rglob("tools/*.md"):
+    tools_pages_found += 1
+    with open(filepath, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    # Separate YAML frontmatter from the markdown body
+    match = re.match(r'^\s*---\s*\n(.*?)\n---\s*(.*)', content, re.DOTALL)
+    if match:
+        frontmatter = match.group(1)
+        body = match.group(2)
+    else:
+        print(f"[{filepath}] Error: Missing or invalid YAML frontmatter.")
+        has_errors = True
+        continue
+
+    file_errors = False
+
+    # --- SPECIAL VALIDATION FOR tools/_index.md ---
+    if filepath.name == "_index.md":
+        title_match = re.search(r"^title:\s*[\"']?(.*?)[\"']?\s*$", frontmatter, re.MULTILINE)
+        if not title_match or title_match.group(1).strip() != "Tools":
+            print(f"[{filepath}] Error: tools/_index.md must have exactly title: \"Tools\"")
+            file_errors = True
+
+        weight_match = re.search(r"^weight:\s*(\d+)\s*$", frontmatter, re.MULTILINE)
+        if not weight_match or weight_match.group(1).strip() != "2":
+            print(f"[{filepath}] Error: tools/_index.md must have exactly weight: 2")
+            file_errors = True
+
+        if file_errors:
+            has_errors = True
+        continue # Skip the rest of the body linting for this structural file
+
+    # --- VALIDATION FOR REGULAR TOOL PAGES ---
+    # If the file has no markdown content (metadata placeholder only), skip it entirely
+    if not body.strip():
+        continue
+
+    # 1. Check Shortcode Placement
+    sources_section_match = re.search(r"^##\s+Compatible Sources\s*(.*?)(?=^##\s|\Z)", body, re.MULTILINE | re.DOTALL)
+    if sources_section_match:
+        if not re.search(SHORTCODE_PATTERN, sources_section_match.group(1)):
+            print(f"[{filepath}] Error: The compatible-sources shortcode must be placed under '## Compatible Sources'.")
+            file_errors = True
+    elif re.search(SHORTCODE_PATTERN, body):
+        print(f"[{filepath}] Error: Shortcode found, but '## Compatible Sources' heading is missing.")
+        file_errors = True
+
+    # 2. Strip code blocks from body to avoid linting example markdown headings
+    clean_body = re.sub(r"```.*?```", "", body, flags=re.DOTALL)
+
+    # 3. Check H1 Headings
+    if re.search(r"^#\s+\w+", clean_body, re.MULTILINE):
+        print(f"[{filepath}] Error: H1 headings (#) are forbidden in the body.")
+        file_errors = True
+
+    # 4. Check H2 Headings
+    h2s = re.findall(r"^##\s+(.*)", clean_body, re.MULTILINE)
+    h2s = [h2.strip() for h2 in h2s]
+
+    # Missing Required
+    if missing := (REQUIRED - set(h2s)):
+        print(f"[{filepath}] Error: Missing required H2 headings: {missing}")
+        file_errors = True
+
+    # Unauthorized Headings
+    if unauthorized := (set(h2s) - set(ALLOWED_ORDER)):
+        print(f"[{filepath}] Error: Unauthorized H2 headings found: {unauthorized}")
+        file_errors = True
+
+    # Strict Ordering
+    filtered_h2s = [h for h in h2s if h in ALLOWED_ORDER]
+    expected_order = [h for h in ALLOWED_ORDER if h in h2s]
+    if filtered_h2s != expected_order:
+        print(f"[{filepath}] Error: Headings are out of order.")
+        print(f"  Expected: {expected_order}")
+        print(f"  Found:    {filtered_h2s}")
+        file_errors = True
+
+    if file_errors:
+        has_errors = True
+
+if tools_pages_found == 0:
+    print("Info: No tool directories found. Passing gracefully.")
+    sys.exit(0)
+elif has_errors:
+    print("Linting failed for Tool pages. Please fix the structure errors above.")
+    sys.exit(1)
+else:
+    print(f"Success: All {tools_pages_found} Tool page(s) passed structure validation.")
+EOF

.ci/sample_tests/pre_post_processing/go.integration.cloudbuild.yaml

@@ -48,7 +48,7 @@ timeout: 1200s
 substitutions:
   _TARGET_LANG: "go"
   _IMAGE: "golang:1.25.7"
-  _TARGET_ROOT: "docs/en/samples/pre_post_processing/go"
+  _TARGET_ROOT: "docs/en/documentation/configuration/pre-post-processing/go"
   _TABLE_NAME: "hotels_go_pre_post_processing"
   _SQL_FILE: ".ci/sample_tests/setup_hotels.sql"
   _AGENT_FILE_PATTERN: "agent.go"

.ci/sample_tests/pre_post_processing/js.integration.cloudbuild.yaml

@@ -48,7 +48,7 @@ timeout: 1200s
 substitutions:
   _TARGET_LANG: "js"
   _IMAGE: "node:22"
-  _TARGET_ROOT: "docs/en/samples/pre_post_processing/js"
+  _TARGET_ROOT: "docs/en/documentation/configuration/pre-post-processing/js"
   _TABLE_NAME: "hotels_js_pre_post_processing"
   _SQL_FILE: ".ci/sample_tests/setup_hotels.sql"
   _AGENT_FILE_PATTERN: "agent.js"

.ci/sample_tests/pre_post_processing/py.integration.cloudbuild.yaml

@@ -48,7 +48,7 @@ timeout: 1200s
 substitutions:
   _TARGET_LANG: "python"
   _IMAGE: "gcr.io/google.com/cloudsdktool/cloud-sdk:537.0.0"
-  _TARGET_ROOT: "docs/en/samples/pre_post_processing/python"
+  _TARGET_ROOT: "docs/en/documentation/configuration/pre-post-processing/python"
   _TABLE_NAME: "hotels_py_pre_post_processing"
   _SQL_FILE: ".ci/sample_tests/setup_hotels.sql"
   _AGENT_FILE_PATTERN: "agent.py"

.ci/sample_tests/quickstart/go.integration.cloudbuild.yaml

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 steps:
-  - name: 'golang:1.25.1'
+  - name: 'golang:1.25.7'
     id: 'go-quickstart-test'
     entrypoint: 'bash'
     args:
@@ -30,7 +30,7 @@ steps:
       - 'GCP_PROJECT=${_GCP_PROJECT}'
       - 'DATABASE_NAME=${_DATABASE_NAME}'
       - 'DB_USER=${_DB_USER}'
-      - 'TARGET_ROOT=docs/en/getting-started/quickstart/go'
+      - 'TARGET_ROOT=docs/en/documentation/getting-started/quickstart/go'
       - 'TARGET_LANG=go'
       - 'TABLE_NAME=hotels_go'
       - 'SQL_FILE=.ci/sample_tests/setup_hotels.sql'
@@ -49,4 +49,4 @@ availableSecrets:
 timeout: 1000s
 
 options:
-  logging: CLOUD_LOGGING_ONLY
+  logging: CLOUD_LOGGING_ONLY

.ci/sample_tests/quickstart/js.integration.cloudbuild.yaml

@@ -30,7 +30,7 @@ steps:
       - 'GCP_PROJECT=${_GCP_PROJECT}'
       - 'DATABASE_NAME=${_DATABASE_NAME}'
       - 'DB_USER=${_DB_USER}'
-      - 'TARGET_ROOT=docs/en/getting-started/quickstart/js'
+      - 'TARGET_ROOT=docs/en/documentation/getting-started/quickstart/js'
       - 'TARGET_LANG=js'
       - 'TABLE_NAME=hotels_js'
       - 'SQL_FILE=.ci/sample_tests/setup_hotels.sql'

.ci/sample_tests/quickstart/py.integration.cloudbuild.yaml

@@ -30,7 +30,7 @@ steps:
       - 'GCP_PROJECT=${_GCP_PROJECT}'
       - 'DATABASE_NAME=${_DATABASE_NAME}'
       - 'DB_USER=${_DB_USER}'
-      - 'TARGET_ROOT=docs/en/getting-started/quickstart/python'
+      - 'TARGET_ROOT=docs/en/documentation/getting-started/quickstart/python'
       - 'TARGET_LANG=python'
       - 'TABLE_NAME=hotels_python'
       - 'SQL_FILE=.ci/sample_tests/setup_hotels.sql'

.github/header-checker-lint.yml

@@ -22,7 +22,6 @@ sourceFileExtensions:
   - 'yaml'
   - 'yml'
 ignoreFiles:
-  - 'docs/en/getting-started/quickstart/**'
-  - 'docs/en/samples/**'
-  - '**/*oracle*'
-
+  - 'docs/en/documentation/**/*.go'
+  - 'docs/en/samples/**/*'
+  - '**/*oracle*'