Skip to content

[Docs] Render the guides with Zensical instead of phpDocumentor - #414

Open
chr-hertel wants to merge 3 commits into
mainfrom
docs-zensical-poc
Open

[Docs] Render the guides with Zensical instead of phpDocumentor#414
chr-hertel wants to merge 3 commits into
mainfrom
docs-zensical-poc

Conversation

@chr-hertel

@chr-hertel chr-hertel commented Aug 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

POC: render the guides with Zensical instead of phpDocumentor, matching the Python SDK docs.

  • ⚠️ Needs a repo setting: Pages source must change from a branch to "GitHub Actions" — merge first, then flip and re-run, so the live site never goes dark.
  • Zensical resolves internal links and fails the build on a dead one; phpDocumentor stays for the API reference at /api/.
  • Deploys on every push to main, PRs build without deploying; make docs and make docs-serve locally.
  • Same theme config as the Python SDK, no custom CSS; PHP highlighting fixed (Pygments needs startinline for fragments).
  • Ten flat pages become six sections, one topic per page; per-page ToCs dropped, GitHub callouts became admonitions.
  • Accuracy sweep against src/: fixed nine samples that could not run, ~13 wrong claims, and 16 broken examples/ paths.

Fix #232

@chr-hertel chr-hertel added the documentation Improvements or additions to documentation label Aug 10, 2026
@chr-hertel chr-hertel added this to the 0.8.0 milestone Aug 10, 2026
@chr-hertel
chr-hertel requested a lite review from Copilot August 10, 2026 23:44
@chr-hertel
[Docs] Render guides with Zensical, deploy via GitHub Pages actions
2ebce35 
phpDocumentor's guide renderer copies the markdown through mostly verbatim:
relative links between pages keep pointing at `*.md` targets that do not exist
in the built site, and nothing validates them, so the published guides are full
of dead links.

Zensical (the Material for MkDocs team's successor to MkDocs) resolves internal
links against the page tree and fails the build on a broken one. `zensical
build --strict` already found four dead links on the first run — three
repo-relative links escaping docs/ (fixed to point at GitHub) and one wrong
in-page anchor.

phpDocumentor stays on for the class-level API reference only; `make docs`
builds the guides into site/ and mounts the reference at site/api/, so its two
header links back to the guides now target the site root.

Deployment moves from pushing a gh-pages branch to the official GitHub Pages
actions, and from release-only to every push on main, with pull requests
building (but not deploying) so a broken link fails review instead of the site.

NOTE: this needs the repository's Pages source switched to "GitHub Actions"
(Settings -> Pages) once.
@chr-hertel
[Docs] Adopt the Python SDK's documentation look and feel
110e79b 
The docs site now uses the same theme configuration as
https://py.sdk.modelcontextprotocol.io/ so the language SDKs read as one set
of docs: the MCP mark as logo and favicon, Inter/JetBrains Mono, the
black/slate palette with a three-way (system/light/dark) toggle, instant
navigation, code copy/annotate, and a right-hand table of contents.

The markdown extension set is widened to the same list (tabbed blocks,
task lists, footnotes, emoji/icons, mermaid fences), which the content
restructure builds on.

Styling is otherwise stock: no custom stylesheet, and Zensical's own
`modern` theme variant, pinned explicitly rather than left to the default.

The one departure is code highlighting, which is broken out of the box here:
Pygments only highlights PHP after a `<?php` tag, so the guides — whose code
blocks are almost all fragments — rendered as flat plain text. The `php`
lexer is extended with `startinline`, and complete-file blocks use a
`php-file` lexer that keeps the literal open tag highlighted.
@chr-hertel
[Docs] Restructure the guides into task-oriented sections
d1c43a8 
The guides were ten flat pages, each opening with a hand-maintained table of
contents and each mixing several audiences: `mcp-elements.md` covered tools,
prompts, schema generation and handler-side logging, `transports.md` covered
both transports plus framework integration, and `server-builder.md` covered
configuration, sessions and custom message handlers.

They are now split along the same lines as the Python SDK's documentation
(https://py.sdk.modelcontextprotocol.io/), one topic per page:

  Get started        installation, first server, the Inspector
  Servers            tools, resources, resource templates, prompts,
                     completions, schema generation, registration
  Inside your handler  the ClientGateway, logging
  Running your server  builder, STDIO, HTTP, framework integration,
                     sessions, authorization
  Clients            connecting, transports, capabilities, server-initiated
                     requests, error handling
  Advanced           events, protocol extensions, custom message handlers

Prose is carried over as-is apart from the seams; what is new is the landing
page and one index page per section, which say what the section is for and
where to go next, so no page is a dead end.

The per-page "Table of Contents" lists are gone — the theme renders one from
the headings — and GitHub's `> [!IMPORTANT]` blockquotes became admonitions,
which Zensical renders as callouts rather than plain quotes.

Every code sample and factual claim was then checked against src/ and the
runnable examples, which turned up long-standing errors in the carried-over
prose. Samples that could not run: a prompt using a `system` role (MCP has
only user/assistant), `Mcp\Schema\PromptMessage` (it is under `Schema\Content`)
constructed with an array instead of a single content object,
`Mcp\Capability\Prompt\Completion\ProviderInterface` (it is
`Mcp\Capability\Completion\ProviderInterface`), `new EmbeddedResource(type:,
resource: [...])` (neither parameter exists), a `: resource` return type
(not a PHP type), `#[McpResource]` with a `{path}` variable (that is a
template), a stray quote in the builder example, a `middlewares:` argument
(it is `middleware:`), and `getRequest()->getAttribute()` in the OAuth guide
(no such method — the values arrive on the request meta). Claims corrected:
sampling's `system_prompt` option (it is `systemPrompt`), `SampleMessage`
(it is `SamplingMessage`), `Notification` called an interface (abstract
class), "parameter order matters" for URI templates (bound by name), full
RFC 6570 support (only simple `{var}`), the tool description fallback chain,
`void` returning empty content, a non-zero STDIO exit code, `ErrorEvent`
being null for parse errors, handlers being "prepended", `Psr16StoreSession`,
and PSR-3 log context being sent to the client (it is dropped). Sixteen
`examples/` paths were missing their `server/` segment.

README, the OAuth ADR and one source comment now point at the published site
instead of at markdown files that moved.
Copilot AI reviewed Aug 10, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR migrates the project’s guide documentation build from phpDocumentor guides to Zensical/MkDocs Material (matching the Python SDK docs), while keeping phpDocumentor for the generated API reference mounted at /api/. It also updates the build/deploy pipeline to publish the combined site via GitHub Pages (Actions-based deployment).

Changes:

  • Add MkDocs/Zensical configuration and reorganize guide content under docs/ into a sectioned navigation.
  • Update make docs to build Zensical guides + phpDocumentor API docs and merge them into a single site/ output.
  • Replace the previous gh-pages branch deployment with the official GitHub Pages Actions workflow and update external doc links.

Reviewed changes

Copilot reviewed 51 out of 54 changed files in this pull request and generated no comments.

Show a summary per file
File Description
src/Server/Transport/Http/OAuth/ProtectedResourceMetadataHandler.php Update docs reference path for authorization guide.
requirements-docs.txt Add pinned Zensical dependency for docs toolchain.
README.md Point documentation links to the published docs site URLs.
phpdoc.dist.xml Configure phpDocumentor to output API docs only under .phpdoc/build/api.
mkdocs.yml Add MkDocs/Zensical site configuration, theme, nav, and markdown extensions.
Makefile Split docs build into guides (Zensical) + API (phpDocumentor) and add docs-serve.
examples/client/http_discovery_calculator.php Update server startup path/port in usage comment.
docs/servers/tools.md New “Tools” guide page for server-side tooling.
docs/servers/schemas.md New schema generation/validation guide page.
docs/servers/resources.md New “Resources” guide page.
docs/servers/resource-templates.md New “Resource templates” guide page.
docs/servers/registration.md New “Registering elements” guide page.
docs/servers/prompts.md New “Prompts” guide page.
docs/servers/index.md New “Servers” section index page.
docs/servers/completions.md New completion providers guide page.
docs/server-builder.md Remove legacy top-level server builder guide (moved under docs/run/).
docs/run/stdio.md New STDIO transport guide page.
docs/run/sessions.md New sessions guide page.
docs/run/server-builder.md New server builder guide page under “Running your server”.
docs/run/index.md New “Running your server” section index page.
docs/run/http.md Refocus HTTP transport doc and convert callouts to admonitions.
docs/run/framework-integration.md New framework integration guide page.
docs/run/authorization.md Update authorization docs for new structure and middleware/meta behavior.
docs/mcp-elements.md Remove legacy monolithic “MCP Elements” guide (split into section pages).
docs/index.md Replace legacy docs landing page with new MkDocs site homepage.
docs/handlers/logging.md New handler logging guide page.
docs/handlers/index.md New “Inside your handler” section index page.
docs/handlers/client-communication.md Rename/rework handler client-communication guide.
docs/get-started/installation.md New installation guide page.
docs/get-started/inspector.md New Inspector walkthrough guide page.
docs/get-started/index.md New “Get started” section index page.
docs/get-started/first-server.md New “First server” tutorial page.
docs/favicon.svg Add docs site favicon asset.
docs/examples.md Update examples guide paths and admonition style.
docs/CNAME Add CNAME for GitHub Pages custom domain.
docs/client/transports.md New client transports guide page.
docs/client/server-requests.md New client server-initiated requests guide page.
docs/client/index.md New “Clients” section index page.
docs/client/errors.md New client error handling guide page.
docs/client/connecting.md New client connecting guide page (includes setMaxRetries() no-op note).
docs/client/capabilities.md New client capabilities guide page.
docs/client.md Remove legacy monolithic client guide (replaced by section pages).
docs/advanced/index.md New “Advanced” section index page.
docs/advanced/extensions.md Update extensions doc link to GitHub-hosted example.
docs/advanced/events.md Update events doc content/callouts.
docs/advanced/custom-handlers.md New custom message handlers guide page.
docs/.overrides/.icons/mcp.svg Add custom icon override asset for the docs theme.
adr/0001-oauth-authorization-server-out-of-scope.md Update ADR link to new authorization doc location.
.phpdoc/template/components/header-title.html.twig Point phpDocumentor header link back to site root.
.phpdoc/template/base.html.twig Point phpDocumentor “Guides” menu entry back to site root.
.gitignore Ignore built docs output (site/) and cache directory.
.github/workflows/docs.yml Replace gh-pages branch publishing with official GitHub Pages Actions deployment.
.gitattributes Exclude MkDocs/Zensical config files from export archives.
Suppressed comments (1)

docs/run/authorization.md:96

  • The Quick Start snippet instantiates OAuthRequestMetaMiddleware() without importing it, so the example won’t run as-is when copied. Either add a use Mcp\Server\Transport\Http\Middleware\OAuthRequestMetaMiddleware; import or fully-qualify the class here.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

@chr-hertel chr-hertel mentioned this pull request Aug 11, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@Nyholm Nyholm Awaiting requested review from Nyholm Nyholm is a code owner
@CodeWithKyrian CodeWithKyrian Awaiting requested review from CodeWithKyrian CodeWithKyrian is a code owner
@soyuka soyuka Awaiting requested review from soyuka soyuka is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

0.8.0

Development

Successfully merging this pull request may close these issues.

[Docs] Links within markdown guides are broken

2 participants

@chr-hertel