Enable markdown docs#728
Conversation
Add support for markdown documentation files (`overview.md`, `doc-files/`) by configuring a JDK 23 toolchain for javadoc generation while keeping JDK 17 as the build target. - Add javadoc-toolchain profile that uses JDK 23 for markdown rendering - Update CI workflows to set up both JDK 17 and JDK 23 - Add markdown `overview.md` as the javadoc landing page - Add documentation for contributors on adding javadoc content 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Import and convert documentation from `modelcontextprotocol` repo: - `sdk-overview.md`: Features, architecture, and dependencies - `server.md`: Server implementation and transport providers - `client.md`: Client implementation, transports, and capabilities Conversions applied: - MDX `<Tabs>`/`<Tab>` elements to markdown subsections - `<Tip>`/`<Note>` callouts to blockquotes - Internal links updated for javadoc doc-files structure - Specification links to `modelcontextprotocol.io/specification/latest` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Merge Features and Architecture sections from `sdk-overview.md` into `overview.md` - Create `getting-started.md` with Dependency and BOM setup instructions - Delete `sdk-overview.md` (content redistributed) - Update links to point to `getting-started.html` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Upgrade javadoc toolchain from JDK 23 to JDK 25 to use the new `--syntax-highlight` option, which bundles highlight.js for automatic syntax highlighting of fenced code blocks in markdown documentation. - Update `javadoc.jdk.version` from 23 to 25 in `pom.xml` - Add `--syntax-highlight` option to maven-javadoc-plugin configuration - Update CI workflows to set up JDK 25 for javadoc generation - Update contributor documentation with syntax highlighting details 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
jonathanhefner
force-pushed
the
enable-markdown-docs
branch
from
87b0afc to
6f91085
Compare
|
Hey @jonathanhefner, thanks for taking the time to put this together! We've been discussing the docs structure and decided to go with a dedicated docs folder approach instead (as mentioned in modelcontextprotocol/modelcontextprotocol#2144). It's more in line with what we're seeing across the other SDKs. Furthermore it is not common in Java to add the reference docs in the javadoc. I've opened #796 to track the docs harmonization work. The reference docs are already being auto-generated and published at https://modelcontextprotocol.github.io/java-sdk/ Quick question though - when #2144 mentions adding the conformance score to the README, does that mean the project's top-level README, or should there be a separate one in the docs folder? |
That works too! Whichever is easiest for you to maintain. 👍
I don't know the answer to that, but I would guess the top-level README because that's where most users will land. Perhaps @felixweinberger can confirm? |
3 participants
Since javadoc generation has been fixed in #705, this PR adds configuration for supporting standalone markdown guides, and imports the existing markdown guides from https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/docs/sdk/java.
This PR is split into 4 commits:
modelcontextprotocol/modelcontextprotocol, convert React elements (e.g.,<Tab>) to headered subsections.--syntax-highlightoption. I've kept this as a separate commit in case we prefer to stick with JDK 23 and look into other syntax highlighting approaches. However, I recommend we use JDK 25 because it is the simplest approach, and because it comes with additional style improvements for rendered markdown.Screenshots:
McpSyncServerAPI doc