[Docs] Links within markdown guides are broken

[chr-hertel]

With the current config the cross-links in markdown files are broken after build with phpDocumentor.
Either it's on me to understand too little about that or we have three options here:

1. switch from MD to RST for proper menu structure - would also bring the guides to left instead of top menu
2. hardlink to html files, which would lead to broken links on github MD preview
3. switch from phpDocumentor to something else

[jonathanhefner]

Sorry I didn't notice this earlier! 🙏

It looks like the phpDocumentor markdown handler breaks fragment links in two ways:

1. Cross-page fragment links (e.g., server-builder.md#manual-capability-registration) are not split on the #, and so are not recognized by phpDocumentor as links to valid pages.
2. Same-page fragment links (e.g., table of contents links) do not work with the <base href="../"> tag that phpDocumentor injects.

I also tried .html# links (e.g., server-builder.html#manual-capability-registration), and those are also broken.

My original choice of phpDocumentor was because it seemed idiomatic. (I am not a PHP developer. 😅) If there is a different tool that you prefer, though, I can look into it. Or if you prefer using RST instead of markdown, I can dig into that instead. I would be happy to help, but I'm not sure what you as maintainers would prefer to maintain, and what the PHP community expects.

[wWzZb]

Hi! I'd like to work on this.

I reproduced phpDocumentor dropping the three cross-page fragment links in docs/mcp-elements.md. I have a local fix that points those references at the canonical published guide URLs, so the links work both in GitHub's Markdown preview and in the generated documentation. make docs passes and the generated hrefs retain the expected fragments.

I also noticed the related upstream phpDocumentor/guides#1300 work; I'm happy to adjust the approach if you'd prefer to wait for that fix instead.

[wWzZb]

Update: I closed #408 because the absolute-URL workaround would hurt the GitHub browsing experience.

The proper fix is being advanced upstream in phpDocumentor/guides#1300. I reproduced this SDKs exact mcp-elements.md → server-builder.md#... failure on the latest guides main, verified the upstream fix, refreshed it to current main, and added PHP SDK-shaped regression coverage. The clean branch-refresh PR is jonathanhefner/phpDocumentor-guides#2.

Keeping this issue open until the upstream fix is merged and available to the PHP SDK docs build.

[chr-hertel]

This could be an easy way out without waiting for the upstream patch: #414

[wWzZb]

Post-merge verification for #414:

• GitHub Pages is now Actions-based (build_type: workflow); the documentation workflow builds the combined site, uploads the Pages artifact, and deploys it with actions/deploy-pages.

• The [Docs] Render the guides with Zensical instead of phpDocumentor #414 merge run completed both build and deploy successfully, and the next main documentation run also deployed successfully.

• The live Zensical site is serving at https://php.sdk.modelcontextprotocol.io/. The old mcp-elements.md material was split into the new guides. Its affected destinations are now:

  • manual registration: https://php.sdk.modelcontextprotocol.io/servers/registration/#manual-registration
  • explicit element registration: https://php.sdk.modelcontextprotocol.io/servers/registration/#explicit-element-registration

  Both live targets return 200 and contain the matching anchor. The explicit-registration link on the page points to its anchor correctly, and the site navigation route for https://php.sdk.modelcontextprotocol.io/run/server-builder/ also returns 200.

• main no longer contains the broken server-builder.md#... references.

So #232 is resolved by the Zensical migration in #414; no absolute-link workaround is needed.