docs: fix broken documentation links in README - #171
Merged
Conversation
janhoy
approved these changes
Jul 31, 2026
The README merged in apache#151 links into docs/site/content/pages/mcp/, a tree that only exists on the unmerged apache#143 branch, so every documentation link on main 404s. Restore the linked content from the apache#143 branch into locations that exist on main today, adapted for plain GitHub rendering (Pelican frontmatter converted to headings, site-absolute links repointed): - per-client setup guides (Claude Desktop, Claude Code, VS Code/Copilot, Cursor, JetBrains, MCP Inspector) under docs/clients/ - observability guide at docs/observability.md and repoint the README links there; the Quick start link now targets the README's own section. Also fix three pre-existing broken links found by a repo-wide sweep: - docs/security/http.md and docs/security/stdio.md referenced ../specs/graalvm-native-image.md, which moved to dev-docs/ - docs/security/keycloak.md TOC listed a 'User Federation (LDAP/AD)' section that does not exist This does not preempt the apache#143 discussion about where website source should live; when that lands these files can move wherever dev@ decides. Fixes apache#168 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>
…guides Five client guides linked to https://github.com/apache/solr-mcp#running-the-server, an anchor for a README section that no longer exists (removed by the apache#151 slim-down). Absolute self-links also dodge relative-link checkers, which is how this survived the sweep. - claude-desktop.md: point the built-JAR reference at the README's Quick start section via a relative link - claude-code/cursor/vs-code/jetbrains: inline the HTTP-mode start command instead of linking (the current README has no HTTP-mode startup section to link to) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>
…ents index - jetbrains.md: the IDE Settings transport is HTTP, not SSE — AI Assistant connects via streamable HTTP, which is what this server implements (stateless streamable, POST /mcp); the legacy SSE transport is not served. Verified against the current JetBrains AI Assistant MCP documentation, and repointed the guide's doc link there (help/idea/model-context-protocol.html now 404s). - README: spec.modelcontextprotocol.io is a dead host (TLS failure; retired spec subdomain) — point the MCP link at modelcontextprotocol.io. All other external links in the PR's files verified 200. - Add docs/clients/README.md so the README's 'Client setup' directory link lands on an index instead of a bare file listing. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>
adityamparikh
force-pushed
the
fix/168-readme-doc-links
branch
from
August 1, 2026 02:09
2455943 to
1fc1c8b
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #168 — every documentation link in the README currently 404s.
Root cause: the README merged in #151 links into
docs/site/content/pages/mcp/, a tree that only exists on the unmerged #143 branch. #151 and #143 were developed together, but only the README landed.Fix — make the links resolve on main today, without preempting the #143 site-structure discussion:
/mcp/security.htmllinks repointed atdocs/security/):docs/clients/docs/observability.mddocs/security/http.md+docs/security/stdio.md→../specs/graalvm-native-image.md(the spec moved todev-docs/)docs/security/keycloak.mdTOC entry for a User Federation (LDAP/AD) section that doesn't existThese files stay wherever the dev@ discussion on #143 lands — a
git mvat that point, nothing here takes a side on project-site vs product-docs structure.Verification
./gradlew build: BUILD SUCCESSFUL (full test suite).🤖 Generated with Claude Code