From f9de6ead0ca28cdcf1bc06ce0c6cffa175abd84d Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Fri, 14 Aug 2026 14:48:17 +0100 Subject: [PATCH 1/3] fix(docs): lead the version badge with the mcpd version and give it room The landing-page badge read 'Version: v0.1.0 (documents mcpd v0.5.0)' -- leading with the docs version and jammed between the title and tagline. It now renders 'mcpd v0.5.0 (docs v0.1.0)' (or 'docs vX' when no mcpd release is resolved) and sits below the tagline, before the first divider, via an explicit marker in index.md. Replaces the heading-and-fence-scanning injection with a straightforward marker replacement, which also fails loudly if the marker is ever removed. --- docs/index.md | 2 + scripts/prepare_gitbook_site.py | 39 +++++++---------- scripts/test_prepare_gitbook_site.py | 64 +++++++++++++--------------- 3 files changed, 47 insertions(+), 58 deletions(-) diff --git a/docs/index.md b/docs/index.md index 3a2c6c2..edf3f0f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,6 +2,8 @@ > *Run your agents, not your infrastructure.* + + --- `mcpd` is a toolchain and runtime developed by [Mozilla AI](https://mozilla.ai) that simplifies the configuration, diff --git a/scripts/prepare_gitbook_site.py b/scripts/prepare_gitbook_site.py index e3b7c5b..4620309 100644 --- a/scripts/prepare_gitbook_site.py +++ b/scripts/prepare_gitbook_site.py @@ -70,29 +70,20 @@ def render_summary_commands(template: str, entries: list[str]) -> str: return template[:begin] + block + template[end:] -def _inject_version_badge(content: str, docs_version: str, mcpd_version: str = "") -> str: - """Insert a version indicator after the first top-level heading.""" - version_line = f"Version: {docs_version}" - if mcpd_version: - version_line += f" (documents mcpd {mcpd_version})" - lines = content.split("\n") - in_fence = False - for i, line in enumerate(lines): - if line.lstrip().startswith("```"): - in_fence = not in_fence - continue - if not in_fence and line.startswith("# "): - j = i + 1 - while j < len(lines) and not lines[j].strip(): - j += 1 - lines[j:j] = [ - '{% hint style="info" icon="tag" %}', - version_line, - "{% endhint %}", - "", - ] - break - return "\n".join(lines) +VERSION_MARKER = "" + + +def _render_version_badge(docs_version: str, mcpd_version: str) -> str: + """Return the version hint block, leading with the mcpd release when known.""" + label = f"mcpd {mcpd_version} (docs {docs_version})" if mcpd_version else f"docs {docs_version}" + return f'{{% hint style="info" icon="tag" %}}\n{label}\n{{% endhint %}}' + + +def _apply_version_badge(content: str, docs_version: str, mcpd_version: str) -> str: + """Replace the version marker with the rendered badge.""" + if VERSION_MARKER not in content: + raise ValueError(f"missing {VERSION_MARKER} marker") + return content.replace(VERSION_MARKER, _render_version_badge(docs_version, mcpd_version)) def generate_summary() -> None: @@ -112,7 +103,7 @@ def stamp_version(docs_version: str, mcpd_version: str) -> None: index = SITE_DIR / "index.md" if index.exists(): index.write_text( - _inject_version_badge(index.read_text(encoding="utf-8"), docs_version, mcpd_version), + _apply_version_badge(index.read_text(encoding="utf-8"), docs_version, mcpd_version), encoding="utf-8", ) diff --git a/scripts/test_prepare_gitbook_site.py b/scripts/test_prepare_gitbook_site.py index 7c22351..89fc898 100644 --- a/scripts/test_prepare_gitbook_site.py +++ b/scripts/test_prepare_gitbook_site.py @@ -5,7 +5,8 @@ import pytest from prepare_gitbook_site import ( - _inject_version_badge, + _apply_version_badge, + _render_version_badge, command_nav_entries, command_title, render_summary_commands, @@ -61,37 +62,32 @@ def test_missing_markers_raises(self) -> None: render_summary_commands("no markers here\n", ["* [x](commands/x.md)"]) -class TestInjectVersionBadge: - def test_inserts_after_heading_with_blank_line(self) -> None: - content = "# Title\n\nBody text" - result = _inject_version_badge(content, "1.2.3") - expected = ( - '# Title\n\n{% hint style="info" icon="tag" %}\n' - "Version: 1.2.3\n{% endhint %}\n\nBody text" +class TestRenderVersionBadge: + def test_leads_with_mcpd_version(self) -> None: + assert _render_version_badge("v0.1.0", "v0.5.0") == ( + '{% hint style="info" icon="tag" %}\n' + "mcpd v0.5.0 (docs v0.1.0)\n" + "{% endhint %}" ) - assert result == expected - - def test_no_heading_returns_unchanged(self) -> None: - content = "No heading here" - assert _inject_version_badge(content, "1.0.0") == content - - def test_only_first_heading_is_modified(self) -> None: - content = "# First\n\nText\n\n# Second\n\nMore text" - result = _inject_version_badge(content, "2.0.0") - assert result.count("Version: ") == 1 - - def test_heading_inside_code_fence_is_skipped(self) -> None: - content = "```\n# Not a heading\n```\n\n# Real heading\n\nBody" - result = _inject_version_badge(content, "1.0.0") - assert "Version: 1.0.0" in result - assert result.index("Version: 1.0.0") > result.index("# Real heading") - - def test_heading_inside_indented_code_fence_is_skipped(self) -> None: - content = " ```\n# Not a heading\n ```\n\n# Real heading\n\nBody" - result = _inject_version_badge(content, "1.0.0") - assert "Version: 1.0.0" in result - assert result.index("Version: 1.0.0") > result.index("# Real heading") - - def test_includes_mcpd_version_when_provided(self) -> None: - result = _inject_version_badge("# Title\n\nBody", "v1.2.3", "v0.4.0") - assert "Version: v1.2.3 (documents mcpd v0.4.0)" in result + + def test_docs_only_when_no_mcpd_version(self) -> None: + assert _render_version_badge("v0.1.0", "") == ( + '{% hint style="info" icon="tag" %}\n' + "docs v0.1.0\n" + "{% endhint %}" + ) + + +class TestApplyVersionBadge: + def test_replaces_marker_in_place(self) -> None: + content = "# mcpd\n\n> tagline\n\n\n\n---\n" + assert _apply_version_badge(content, "v0.1.0", "v0.5.0") == ( + "# mcpd\n\n> tagline\n\n" + '{% hint style="info" icon="tag" %}\n' + "mcpd v0.5.0 (docs v0.1.0)\n" + "{% endhint %}\n\n---\n" + ) + + def test_raises_when_marker_missing(self) -> None: + with pytest.raises(ValueError): + _apply_version_badge("# mcpd\n\nno marker here\n", "v0.1.0", "v0.5.0") From bb8015b9228527057cfc49d15d8d3a935974417e Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Fri, 14 Aug 2026 14:54:10 +0100 Subject: [PATCH 2/3] docs: add the mcpd logo to the landing page Sibling products on docs.mozilla.ai (encoderfile, llamafile) show their product logo on the home page for visual identification. Re-add the mcpd logo -- dropped in the migration because it depended on the old MkDocs custom CSS -- as a plain PNG image under the H1, which needs no theming. The SVG is also available if preferred. --- docs/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/index.md b/docs/index.md index edf3f0f..86440f4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,7 @@ # mcpd +![mcpd](assets/mcpd-logo.png) + > *Run your agents, not your infrastructure.* From 8e447583a6ba0186909232b0414ceaaa6938f56c Mon Sep 17 00:00:00 2001 From: Peter Wilson Date: Fri, 14 Aug 2026 15:20:36 +0100 Subject: [PATCH 3/3] docs: constrain the landing-page logo to a sensible size The logo PNG is 1660x1697 (near square), so GitBook scaled it to the column width and rendered it huge. Cap it at width 200 with an tag, matching the README's sizing and llamafile's git-synced pattern. --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 86440f4..9de0b11 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # mcpd -![mcpd](assets/mcpd-logo.png) +mcpd > *Run your agents, not your infrastructure.*