Enable markdown docs

[jonathanhefner]

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:

1. Add basic configuration to support markdown docs. Notably, this requires using JDK 23 to generate the docs; however, CI will still use JDK 17 to build the code.
2. Import the markdown docs from modelcontextprotocol/modelcontextprotocol, convert React elements (e.g., <Tab>) to headered subsections.
3. Restructure some of the information so that there is a single overview landing page and a separate "Getting Started" page that lists dependencies and BOM.
4. Upgrade from JDK 23 to JDK 25 for javadoc generation in order to use the new --syntax-highlight option. 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:

Overview doc	Server doc (truncated)	Client doc (truncated)

Getting Started doc	API docs tree	McpSyncServer API doc

[tzolov]

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?

[tzolov]

Related modelcontextprotocol/modelcontextprotocol#2259

[jonathanhefner]

The reference docs are already being auto-generated and published at https://modelcontextprotocol.github.io/java-sdk/

That works too! Whichever is easiest for you to maintain. 👍

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?

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?

[jonathanhefner]

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:

1. Add basic configuration to support markdown docs. Notably, this requires using JDK 23 to generate the docs; however, CI will still use JDK 17 to build the code.
2. Import the markdown docs from modelcontextprotocol/modelcontextprotocol, convert React elements (e.g., <Tab>) to headered subsections.
3. Restructure some of the information so that there is a single overview landing page and a separate "Getting Started" page that lists dependencies and BOM.
4. Upgrade from JDK 23 to JDK 25 for javadoc generation in order to use the new --syntax-highlight option. 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:

Overview doc	Server doc (truncated)	Client doc (truncated)

Getting Started doc	API docs tree	McpSyncServer API doc

[tzolov]

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?

[tzolov]

Related modelcontextprotocol/modelcontextprotocol#2259

[jonathanhefner]

The reference docs are already being auto-generated and published at https://modelcontextprotocol.github.io/java-sdk/

That works too! Whichever is easiest for you to maintain. 👍

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?

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?

[jonathanhefner]

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:

1. Add basic configuration to support markdown docs. Notably, this requires using JDK 23 to generate the docs; however, CI will still use JDK 17 to build the code.
2. Import the markdown docs from modelcontextprotocol/modelcontextprotocol, convert React elements (e.g., <Tab>) to headered subsections.
3. Restructure some of the information so that there is a single overview landing page and a separate "Getting Started" page that lists dependencies and BOM.
4. Upgrade from JDK 23 to JDK 25 for javadoc generation in order to use the new --syntax-highlight option. 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:

Overview doc	Server doc (truncated)	Client doc (truncated)

Getting Started doc	API docs tree	McpSyncServer API doc

[tzolov]

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?

[tzolov]

Related modelcontextprotocol/modelcontextprotocol#2259

[jonathanhefner]

The reference docs are already being auto-generated and published at https://modelcontextprotocol.github.io/java-sdk/

That works too! Whichever is easiest for you to maintain. 👍

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?

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?

[jonathanhefner]

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:

1. Add basic configuration to support markdown docs. Notably, this requires using JDK 23 to generate the docs; however, CI will still use JDK 17 to build the code.
2. Import the markdown docs from modelcontextprotocol/modelcontextprotocol, convert React elements (e.g., <Tab>) to headered subsections.
3. Restructure some of the information so that there is a single overview landing page and a separate "Getting Started" page that lists dependencies and BOM.
4. Upgrade from JDK 23 to JDK 25 for javadoc generation in order to use the new --syntax-highlight option. 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:

Overview doc	Server doc (truncated)	Client doc (truncated)

Getting Started doc	API docs tree	McpSyncServer API doc

[tzolov]

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?

[tzolov]

Related modelcontextprotocol/modelcontextprotocol#2259

[jonathanhefner]

The reference docs are already being auto-generated and published at https://modelcontextprotocol.github.io/java-sdk/

That works too! Whichever is easiest for you to maintain. 👍

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?

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?

[jonathanhefner]

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:

1. Add basic configuration to support markdown docs. Notably, this requires using JDK 23 to generate the docs; however, CI will still use JDK 17 to build the code.
2. Import the markdown docs from modelcontextprotocol/modelcontextprotocol, convert React elements (e.g., <Tab>) to headered subsections.
3. Restructure some of the information so that there is a single overview landing page and a separate "Getting Started" page that lists dependencies and BOM.
4. Upgrade from JDK 23 to JDK 25 for javadoc generation in order to use the new --syntax-highlight option. 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:

Overview doc	Server doc (truncated)	Client doc (truncated)

Getting Started doc	API docs tree	McpSyncServer API doc

[tzolov]

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?

[tzolov]

Related modelcontextprotocol/modelcontextprotocol#2259

[jonathanhefner]

The reference docs are already being auto-generated and published at https://modelcontextprotocol.github.io/java-sdk/

That works too! Whichever is easiest for you to maintain. 👍

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?

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?

[jonathanhefner]

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:

1. Add basic configuration to support markdown docs. Notably, this requires using JDK 23 to generate the docs; however, CI will still use JDK 17 to build the code.
2. Import the markdown docs from modelcontextprotocol/modelcontextprotocol, convert React elements (e.g., <Tab>) to headered subsections.
3. Restructure some of the information so that there is a single overview landing page and a separate "Getting Started" page that lists dependencies and BOM.
4. Upgrade from JDK 23 to JDK 25 for javadoc generation in order to use the new --syntax-highlight option. 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:

Overview doc	Server doc (truncated)	Client doc (truncated)

Getting Started doc	API docs tree	McpSyncServer API doc

[tzolov]

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?

[tzolov]

Related modelcontextprotocol/modelcontextprotocol#2259

[jonathanhefner]

The reference docs are already being auto-generated and published at https://modelcontextprotocol.github.io/java-sdk/

That works too! Whichever is easiest for you to maintain. 👍

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?

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?

[jonathanhefner]

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:

1. Add basic configuration to support markdown docs. Notably, this requires using JDK 23 to generate the docs; however, CI will still use JDK 17 to build the code.
2. Import the markdown docs from modelcontextprotocol/modelcontextprotocol, convert React elements (e.g., <Tab>) to headered subsections.
3. Restructure some of the information so that there is a single overview landing page and a separate "Getting Started" page that lists dependencies and BOM.
4. Upgrade from JDK 23 to JDK 25 for javadoc generation in order to use the new --syntax-highlight option. 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:

Overview doc	Server doc (truncated)	Client doc (truncated)

Getting Started doc	API docs tree	McpSyncServer API doc

[tzolov]

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?

[tzolov]

Related modelcontextprotocol/modelcontextprotocol#2259

[jonathanhefner]

The reference docs are already being auto-generated and published at https://modelcontextprotocol.github.io/java-sdk/

That works too! Whichever is easiest for you to maintain. 👍

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?

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?

[jonathanhefner]

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:

1. Add basic configuration to support markdown docs. Notably, this requires using JDK 23 to generate the docs; however, CI will still use JDK 17 to build the code.
2. Import the markdown docs from modelcontextprotocol/modelcontextprotocol, convert React elements (e.g., <Tab>) to headered subsections.
3. Restructure some of the information so that there is a single overview landing page and a separate "Getting Started" page that lists dependencies and BOM.
4. Upgrade from JDK 23 to JDK 25 for javadoc generation in order to use the new --syntax-highlight option. 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:

Overview doc	Server doc (truncated)	Client doc (truncated)

Getting Started doc	API docs tree	McpSyncServer API doc

[tzolov]

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?

[tzolov]

Related modelcontextprotocol/modelcontextprotocol#2259

[jonathanhefner]

The reference docs are already being auto-generated and published at https://modelcontextprotocol.github.io/java-sdk/

That works too! Whichever is easiest for you to maintain. 👍

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?

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?