docs(site): add \"Edit this page\" link and restyle the TOC like docs.docker.com

The right-column aside on every content page now mirrors
docs.docker.com (e.g. https://docs.docker.com/get-started/introduction/develop-with-containers/):

  \u2022 \"Edit this page\" link with a pencil icon at the top, pointing
    at GitHub's web editor for the source file. The exact URL is
    resolved at build time via a new <meta name=\"docs-edit-url\">
    tag set in default.html using {{ page.path }}.
  \u2022 \"Table of contents\" heading at text-lg / weight 500 (was a tiny
    uppercase \"On this page\" eyebrow).
  \u2022 TOC links bumped to .875rem (\u224814px) and re-colored to the same
    \"#566581\" (gray-600) light / \"#E7EAEF\" (gray-100) dark that
    docs.docker.com uses, with hover/active picking up font-weight
    500 + a 2px gray-300 left border on the active entry.\n  \u2022 The aside is widened from 220 \u2192 260 px so longer headings stop\n    being clipped.\n\nbuildTOC() in js/app.js was updated to render the edit link\nunconditionally (even on short pages with no TOC entries) and to\nrender the TOC body whenever the page has \u22652 sub-headings (was 3).\nScroll-spy and smooth-scroll behavior unchanged.

Author: dgageot

docs/_layouts/default.html

@@ -6,6 +6,13 @@
   <title>{% if page.title and page.url != '/' %}{{ page.title }} – Docker Agent Docs{% else %}Docker Agent — Run AI agents from YAML, like containers{% endif %}</title>
   <meta name="description" content="{{ page.description | default: site.description }}">
 
+  {% comment %}
+    Source path of the current page on disk, used by the right-column
+    \"Edit this page\" link in js/app.js. We point at GitHub's web editor
+    on the configured repo + branch.
+  {% endcomment %}
+  <meta name="docs-edit-url" content="https://github.com/docker/docker-agent/edit/main/docs/{{ page.path | replace_first: 'docs/', '' | default: 'index.md' }}">
+
   <meta property="og:title" content="{% if page.title and page.url != '/' %}{{ page.title }} – Docker Agent Docs{% else %}Docker Agent — Run AI agents from YAML, like containers{% endif %}">
   <meta property="og:description" content="{{ page.description | default: site.description }}">
   <meta property="og:type" content="{% if page.url == '/' %}website{% else %}article{% endif %}">

docs/css/style.css

@@ -92,7 +92,7 @@
 
   --sidebar-width: 260px;
   --header-height: 56px;
-  --toc-width: 220px;
+  --toc-width: 260px;
 
   --font-sans: 'Roboto Flex', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
   --font-mono: 'Roboto Mono', ui-monospace, 'SF Mono', Menlo, Monaco, Consolas, monospace;
@@ -386,63 +386,116 @@ body {
   scroll-margin-top: calc(var(--header-height) + 16px);
 }
 
-/* ===== Table of Contents (right sidebar) ===== */
+/* ===== Table of Contents (right sidebar) =====
+ * Layout, font sizes and colors mirror docs.docker.com's right-column
+ * \"Edit this page\" + \"Table of contents\" pattern. */
 .toc-aside {
   position: fixed;
   top: var(--header-height);
   right: 0;
   width: var(--toc-width);
   height: calc(100vh - var(--header-height));
-  padding: 32px 16px 32px 0;
+  padding: 24px 24px 32px 16px;
   overflow-y: auto;
   scrollbar-width: thin;
   scrollbar-color: var(--border) transparent;
+  font-size: 0.875rem;            /* docs.docker.com .prose-sm */
+  line-height: 1.71;
 }
 
 .toc-inner {
-  border-left: 1px solid var(--border);
-  padding-left: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
 }
 
-.toc-title {
-  font-size: 0.65rem;
-  font-weight: 700;
-  text-transform: uppercase;
-  letter-spacing: 0.1em;
-  color: var(--text-muted);
-  margin-bottom: 12px;
+/* Edit-this-page action row */
+.toc-actions {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  margin-bottom: 8px;
+}
+.toc-action {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--gray-600);
+  text-decoration: none;
+  font-weight: 400;
+  padding: 4px 0;
+  transition: color 0.12s;
+}
+[data-theme="dark"] .toc-action,
+:root:not([data-theme="light"]) .toc-action {
+  color: var(--gray-100);
+}
+.toc-action:hover {
+  color: var(--text);
+  text-decoration: none;
+}
+.toc-action svg {
+  width: 16px;
+  height: 16px;
+  flex-shrink: 0;
+  opacity: 0.85;
+}
+
+.toc-heading {
+  font-size: 1.05rem;             /* docs.docker.com text-lg */
+  font-weight: 500;
+  color: var(--text);
+  margin-top: 8px;
+  margin-bottom: 4px;
+  letter-spacing: -0.005em;
 }
 
 .toc-nav {
   display: flex;
   flex-direction: column;
+  border-left: 1px solid var(--border);
+  padding-left: 0;
 }
 
 .toc-link {
-  font-size: 0.78rem;
-  color: var(--text-muted);
-  text-decoration: none;
-  padding: 3px 0;
-  line-height: 1.4;
-  transition: color 0.12s;
+  display: block;
+  padding: 6px 0 6px 12px;
+  margin-left: -1px;              /* sit on top of .toc-nav border */
   border-left: 2px solid transparent;
-  margin-left: -17px;
-  padding-left: 15px;
+  color: var(--gray-600);
+  text-decoration: none;
+  font-size: 0.875rem;
+  font-weight: 400;
+  line-height: 1.5;
+  transition: color 0.12s, border-color 0.12s, font-weight 0.12s;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  overflow: hidden;
+}
+[data-theme="dark"] .toc-link,
+:root:not([data-theme="light"]) .toc-link {
+  color: var(--gray-100);
 }
 .toc-link:hover {
   color: var(--text);
+  font-weight: 500;
+  text-decoration: none;
 }
 .toc-link:focus-visible {
   outline: 2px solid var(--accent);
   outline-offset: 2px;
 }
 .toc-link.active {
-  color: var(--accent);
-  border-left-color: var(--accent);
+  color: var(--text);
+  font-weight: 500;
+  border-left-color: var(--gray-300);
+}
+[data-theme="dark"] .toc-link.active,
+:root:not([data-theme="light"]) .toc-link.active {
+  border-left-color: var(--gray-300);
 }
 .toc-link.toc-h3 {
-  padding-left: 27px;
-  font-size: 0.72rem;
+  padding-left: 28px;
 }
 
 @media (min-width: 1280px) {

docs/js/app.js

@@ -33,38 +33,64 @@ function toggleTheme() {
 }
 
 // ---------- Table of Contents ----------
+// The right-column aside on each page contains:
+//   1. An \"Edit this page\" link to the source on GitHub (resolved
+//      from a <meta name=\"docs-edit-url\"> set in the layout).
+//   2. A \"Table of contents\" heading + nested links to in-page
+//      <h2 id> / <h3 id> headings.
+// We render the heading + nav unconditionally when there are at least
+// 2 headings; the edit link renders even on short pages.
 function buildTOC() {
   if (!$content) return;
 
   const headings = $content.querySelectorAll('h2[id], h3[id]');
-  if (headings.length < 3) return;
+  const editUrl = (document.querySelector('meta[name="docs-edit-url"]') || {}).content || '';
+
+  // Don't bother rendering the aside on extremely short pages with no
+  // navigation value at all.
+  if (headings.length < 2 && !editUrl) return;
 
   const aside = document.createElement('aside');
   aside.className = 'toc-aside';
-  aside.setAttribute('aria-label', 'Table of contents');
-  aside.innerHTML = `
-    <div class="toc-inner">
-      <div class="toc-title">On this page</div>
+  aside.setAttribute('aria-label', 'On this page');
+
+  const tocBody = headings.length >= 2
+    ? `
+      <div class="toc-heading">Table of contents</div>
       <nav class="toc-nav">
         ${Array.from(headings).map(h => {
           const level = h.tagName === 'H3' ? 'toc-h3' : '';
           return `<a class="toc-link ${level}" href="#${h.id}" data-id="${h.id}">${h.textContent}</a>`;
         }).join('')}
-      </nav>
-    </div>`;
+      </nav>`
+    : '';
+
+  const editBlock = editUrl
+    ? `
+      <div class="toc-actions">
+        <a class="toc-action" href="${editUrl}" target="_blank" rel="noopener">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"/><path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"/></svg>
+          <span>Edit this page</span>
+        </a>
+      </div>`
+    : '';
+
+  aside.innerHTML = `<div class="toc-inner">${editBlock}${tocBody}</div>`;
 
   const main = document.querySelector('.main');
   if (main) main.appendChild(aside);
 
-  aside.addEventListener('click', (e) => {
-    const link = e.target.closest('.toc-link');
-    if (!link) return;
-    e.preventDefault();
-    const target = document.getElementById(link.dataset.id);
-    if (target) target.scrollIntoView({ behavior: 'smooth', block: 'start' });
-  });
+  if (headings.length >= 2) {
+    aside.addEventListener('click', (e) => {
+      const link = e.target.closest('.toc-link');
+      if (!link) return;
+      e.preventDefault();
+      const target = document.getElementById(link.dataset.id);
+      if (target) target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    });
 
-  setupScrollSpy(headings, aside);
+    setupScrollSpy(headings, aside);
+  }
 }
 
 function setupScrollSpy(headings, aside) {