Merge pull request #196 from posit-dev/enh-mcp-docs

enh: clean up MCP docs pages

Author: rich-iannone

great_docs/_mcp_docs.py

@@ -597,16 +597,16 @@ def _generate_mcp_index_page(
         f'<span class="mcp-tile-label">{get_translation("mcp_prompts", language)}</span>'
         f'<span class="mcp-tile-count">{n_prompts}</span></span>'
     )
-    lines.append(
-        f'<span class="mcp-tile mcp-tile-completions">'
-        f'<span class="mcp-tile-label">{get_translation("mcp_completions", language)}</span>'
-        f'<span class="mcp-tile-count">{completions_mark}</span></span>'
-    )
     lines.append(
         f'<span class="mcp-tile mcp-tile-instructions">'
         f'<span class="mcp-tile-label">{get_translation("mcp_instructions", language)}</span>'
         f'<span class="mcp-tile-count">{instructions_mark}</span></span>'
     )
+    lines.append(
+        f'<span class="mcp-tile mcp-tile-completions">'
+        f'<span class="mcp-tile-label">{get_translation("mcp_completions", language)}</span>'
+        f'<span class="mcp-tile-count">{completions_mark}</span></span>'
+    )
     lines.append("</div>")
     lines.append("")
 

great_docs/_translations.py

@@ -6178,31 +6178,31 @@
         "he": "משאבים",
     },
     "mcp_resource_templates": {
-        "en": "Resource Templates",
-        "fr": "Modèles de ressources",
-        "de": "Ressourcenvorlagen",
-        "es": "Plantillas de recursos",
-        "pt": "Modelos de recursos",
-        "it": "Modelli di risorse",
-        "nl": "Bronsjablonen",
-        "ja": "リソーステンプレート",
-        "ko": "리소스 템플릿",
-        "zh-Hans": "资源模板",
-        "zh-Hant": "資源模板",
-        "ru": "Шаблоны ресурсов",
-        "pl": "Szablony zasobów",
-        "tr": "Kaynak şablonları",
-        "sv": "Resursmallar",
-        "da": "Ressourceskabeloner",
-        "nb": "Ressursmaler",
-        "is": "Auðlindasniðmát",
-        "fi": "Resurssipohjat",
-        "cs": "Šablony zdrojů",
-        "ro": "Șabloane de resurse",
-        "el": "Πρότυπα πόρων",
-        "hi": "संसाधन टेम्प्लेट",
-        "ar": "قوالب الموارد",
-        "he": "תבניות משאבים",
+        "en": "Templates",
+        "fr": "Modèles",
+        "de": "Vorlagen",
+        "es": "Plantillas",
+        "pt": "Modelos",
+        "it": "Modelli",
+        "nl": "Sjablonen",
+        "ja": "テンプレート",
+        "ko": "템플릿",
+        "zh-Hans": "模板",
+        "zh-Hant": "模板",
+        "ru": "Шаблоны",
+        "pl": "Szablony",
+        "tr": "Şablonlar",
+        "sv": "Mallar",
+        "da": "Skabeloner",
+        "nb": "Maler",
+        "is": "Sniðmát",
+        "fi": "Pohjat",
+        "cs": "Šablony",
+        "ro": "Șabloane",
+        "el": "Πρότυπα",
+        "hi": "टेम्प्लेट",
+        "ar": "قوالب",
+        "he": "תבניות",
     },
     "mcp_prompts": {
         "en": "Prompts",

great_docs/assets/great-docs.scss

@@ -21,10 +21,10 @@ $label-constant-color: mix($primary, $orange-500, 20%);
 $label-typealias-color: mix($primary, $yellow-500, 20%);
 $label-cli-color: mix($primary, $green-600, 20%);
 $label-cli-group-color: mix($primary, $green-600, 20%);
-$label-mcp-tool-color: mix($primary, $purple-600, 20%);
-$label-mcp-resource-color: mix($primary, $teal-500, 20%);
-$label-mcp-resource-template-color: mix($primary, $teal-500, 20%);
-$label-mcp-prompt-color: mix($primary, $orange-400, 20%);
+$label-mcp-tool-color: #e6194B;
+$label-mcp-resource-color: #3cb44b;
+$label-mcp-resource-template-color: #f032e6;
+$label-mcp-prompt-color: #4363d8;
 $label-mcp-color: mix($primary, $purple-600, 20%);
 
 $signature-background-color: shade-color(tint-color($primary, 96%), 2%);
@@ -601,8 +601,8 @@ $method-like-labels: (method, classmethod, staticmethod);
 }
 
 // MCP capability tiles
-$label-mcp-completions-color: mix($primary, $indigo-400, 20%);
-$label-mcp-instructions-color: mix($primary, $pink-500, 20%);
+$label-mcp-completions-color: #911eb4;
+$label-mcp-instructions-color: #f58231;
 
 .mcp-capability-tiles {
   max-width: 28rem;
@@ -613,6 +613,7 @@ $label-mcp-instructions-color: mix($primary, $pink-500, 20%);
     grid-template-columns: 1fr 1fr;
     gap: 0.5rem;
     margin: 0;
+    padding-top: 10px;
   }
 }
 
@@ -638,39 +639,39 @@ $label-mcp-instructions-color: mix($primary, $pink-500, 20%);
 }
 
 .mcp-tile-tools {
-  color: $label-mcp-tool-color;
-  border-color: $label-mcp-tool-color;
-  background-color: tint-color($label-mcp-tool-color, 92%);
+  color: #e6194B;
+  border-color: #e6194B;
+  background-color: tint-color(#e6194B, 92%);
 }
 
 .mcp-tile-resources {
-  color: $label-mcp-resource-color;
-  border-color: $label-mcp-resource-color;
-  background-color: tint-color($label-mcp-resource-color, 92%);
+  color: #3cb44b;
+  border-color: #3cb44b;
+  background-color: tint-color(#3cb44b, 92%);
 }
 
 .mcp-tile-templates {
-  color: $label-mcp-resource-template-color;
-  border-color: $label-mcp-resource-template-color;
-  background-color: tint-color($label-mcp-resource-template-color, 92%);
+  color: #f032e6;
+  border-color: #f032e6;
+  background-color: tint-color(#f032e6, 92%);
 }
 
 .mcp-tile-prompts {
-  color: $label-mcp-prompt-color;
-  border-color: $label-mcp-prompt-color;
-  background-color: tint-color($label-mcp-prompt-color, 92%);
+  color: #4363d8;
+  border-color: #4363d8;
+  background-color: tint-color(#4363d8, 92%);
 }
 
-.mcp-tile-completions {
-  color: $label-mcp-completions-color;
-  border-color: $label-mcp-completions-color;
-  background-color: tint-color($label-mcp-completions-color, 92%);
+.mcp-tile-instructions {
+  color: #f58231;
+  border-color: #f58231;
+  background-color: tint-color(#f58231, 92%);
 }
 
-.mcp-tile-instructions {
-  color: $label-mcp-instructions-color;
-  border-color: $label-mcp-instructions-color;
-  background-color: tint-color($label-mcp-instructions-color, 92%);
+.mcp-tile-completions {
+  color: #911eb4;
+  border-color: #911eb4;
+  background-color: tint-color(#911eb4, 92%);
 }
 
 // Adorn callables with ()
@@ -1947,7 +1948,7 @@ div.sourceCode:hover > .gd-code-nav .gd-code-copy,
         gap: 0;
         padding-top: 0;
         padding-left: 0.5rem;
-        color: #6c757d;
+        color: #212529;
         white-space: nowrap;
         overflow: hidden;
         text-overflow: ellipsis;

great_docs/assets/keyboard-nav.js

@@ -469,10 +469,11 @@
             var item = items[i];
             if (item.section && item.section !== currentSection) {
                 currentSection = item.section;
+                // Section text comes from innerHTML (already HTML-safe), so
+                // insert directly without escaping to avoid double-encoding
+                // entities like & → &
                 html += '<li class="gd-menu-section" aria-hidden="true">' +
-                        (typeof currentSection === 'string' && currentSection.indexOf('<') !== -1
-                            ? currentSection
-                            : escapeHtml(currentSection)) + '</li>';
+                        currentSection + '</li>';
             }
             var activeClass = item.active ? ' gd-menu-item-active' : '';
             var label = item.html || escapeHtml(item.text);

great_docs/assets/post-render.py

@@ -2958,9 +2958,14 @@ def convert_table_to_dl(match):
     # Translate renderer-rendered headings, TOC, and sidebar on the index page
     content = translate_renderer_headings(content)
 
-    # Replace breadcrumb with a "Reference" title bar label
-    _reference_label = _t("reference", "Reference")
-    _ref_idx_title = f'<h1 class="quarto-secondary-nav-title no-breadcrumbs gd-ref-title">{html.escape(_reference_label)}</h1>'
+    # Replace breadcrumb with an "API / Index" title bar label
+    _ref_idx_title = (
+        '<h1 class="quarto-secondary-nav-title no-breadcrumbs gd-ref-title">'
+        '<span class="gd-ref-title-prefix">API</span>'
+        '<span class="gd-ref-title-sep">/</span>'
+        '<span class="gd-ref-title-name">Index</span>'
+        "</h1>"
+    )
     _bc_pat = r'<nav class="quarto-page-breadcrumbs[^"]*"[^>]*>.*?</nav>'
     content = re.sub(_bc_pat, _ref_idx_title, content, flags=re.DOTALL)
 
@@ -2972,6 +2977,71 @@ def convert_table_to_dl(match):
     print(f"Index file not found: {index_file}")
 
 
+# Modify the MCP index page to replace breadcrumbs with a styled title
+mcp_index_file = "_site/reference/mcp/index.html"
+if os.path.exists(mcp_index_file):
+    print(f"Processing MCP index file: {mcp_index_file}")
+    with open(mcp_index_file, "r", encoding="utf-8") as file:
+        content = file.read()
+
+    _mcp_idx_title = (
+        '<h1 class="quarto-secondary-nav-title no-breadcrumbs gd-ref-title">'
+        '<span class="gd-ref-title-prefix">MCP</span>'
+        '<span class="gd-ref-title-sep">/</span>'
+        '<span class="gd-ref-title-name">Index</span>'
+        "</h1>"
+    )
+    _bc_pat = r'<nav class="quarto-page-breadcrumbs[^"]*"[^>]*>.*?</nav>'
+    content = re.sub(_bc_pat, _mcp_idx_title, content, flags=re.DOTALL)
+
+    with open(mcp_index_file, "w", encoding="utf-8") as file:
+        file.write(content)
+
+    print("MCP index file processing complete")
+else:
+    print(f"MCP index file not found: {mcp_index_file}")
+
+
+# Process individual MCP reference pages (tools, resources, prompts) to add
+# "MCP / object_name" title bar in the secondary nav
+mcp_html_files = [
+    f for f in glob.glob("_site/reference/mcp/*.html") if os.path.basename(f) != "index.html"
+]
+
+if mcp_html_files:
+    print(f"Processing {len(mcp_html_files)} MCP reference pages...")
+
+    for html_file in mcp_html_files:
+        with open(html_file, "r", encoding="utf-8") as file:
+            content = file.read()
+
+        # Extract the display name from the doc-object-name span
+        _obj_name_match = re.search(r'<span class="doc-object-name[^"]*">([^<]+)</span>', content)
+        _mcp_name = (
+            _obj_name_match.group(1)
+            if _obj_name_match
+            else os.path.basename(html_file).replace(".html", "")
+        )
+
+        _mcp_title_html = (
+            f'<h1 class="quarto-secondary-nav-title no-breadcrumbs gd-ref-title">'
+            f'<span class="gd-ref-title-prefix">MCP</span>'
+            f'<span class="gd-ref-title-sep">/</span>'
+            f'<span class="gd-ref-title-name">{html.escape(_mcp_name)}</span>'
+            f"</h1>"
+        )
+
+        # MCP pages use bread-crumbs: false, so Quarto renders the title inside
+        # an h1.quarto-secondary-nav-title.no-breadcrumbs element
+        _h1_pat = r'<h1 class="quarto-secondary-nav-title no-breadcrumbs[^"]*">.*?</h1>'
+        content = re.sub(_h1_pat, _mcp_title_html, content, count=1, flags=re.DOTALL)
+
+        with open(html_file, "w", encoding="utf-8") as file:
+            file.write(content)
+
+    print(f"Styled {len(mcp_html_files)} MCP reference page titles")
+
+
 # Update quarto-secondary-nav-title to display "User Guide" text
 # This improves the mobile navigation by making it clear what the sidebar toggle reveals
 all_html_files = glob.glob("_site/**/*.html", recursive=True)