Skip to content

feat: create docs-v2 structure with diataxis framework#906

Merged
felixweinberger merged 2 commits into
docs/developfrom
fweinberger/docs/restructure
Jul 3, 2025
Merged

feat: create docs-v2 structure with diataxis framework#906
felixweinberger merged 2 commits into
docs/developfrom
fweinberger/docs/restructure

Conversation

@felixweinberger

@felixweinberger felixweinberger commented Jul 3, 2025

Copy link
Copy Markdown
Contributor

Motivation and Context

New structure for v2 of our docs. The docs page itself has placeholders.

Outstanding: add the spec + versions to this current version (on me)

CleanShot 2025-07-03 at 15 36 09@2x
CleanShot 2025-07-03 at 15 36 11@2x
CleanShot 2025-07-03 at 15 36 14@2x

  • Create new docs-v2 directory with modern docs.json configuration
  • Implement 3-tab navigation: Overview, Documentation, Community
  • Structure Documentation section following diataxis framework:
    • Tutorials (learning-oriented)
    • Learn/Explanations (understanding-oriented)
    • How-to Guides (task-oriented)
    • Reference (information-oriented)
  • Add 44 stub files for team members to populate
  • Update package.json with docs-v2 scripts
  • Use modern docs.json format with proper tabs support

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

How Has This Been Tested?

npm run serve:docs-v2

Breaking Changes

None.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

@felixweinberger felixweinberger force-pushed the fweinberger/docs/restructure branch 2 times, most recently from 1c94a9a to 06a2702 Compare July 3, 2025 14:42
@felixweinberger felixweinberger requested a review from dsp-ant July 3, 2025 14:43
@jonathanhefner

jonathanhefner commented Jul 3, 2025

Copy link
Copy Markdown
Member

Instead of having a persistent tab bar, could we (1) use the logo as the link to the "Overview" page, and (2) put the "Documentation" and "Community" links in the top nav bar?

preview2-edit2

Also, I feel like the sidebar for the Documentation tab is a bit overwhelming, as in "What is all this? Where am I supposed to look?" The /documentation/index page seems like it might be used to provide an overview of all of the items in the sidebar, which I think is good. But reducing the number of immediately visible items might also be helpful (e.g. by adding more collapsed-by-default groups).

felixweinberger and others added 2 commits July 3, 2025 16:43
- Create new docs-v2 directory with modern docs.json configuration
- Implement 3-tab navigation: Overview, Documentation, Community
- Structure Documentation section following diataxis framework:
  - Tutorials (learning-oriented)
  - Learn/Explanations (understanding-oriented)
  - How-to Guides (task-oriented)
  - Reference (information-oriented)
- Add 44 stub files for team members to populate
- Update package.json with docs-v2 scripts
- Use modern docs.json format with proper tabs support

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@felixweinberger felixweinberger force-pushed the fweinberger/docs/restructure branch from 7af1855 to 3b2cef6 Compare July 3, 2025 15:43
@felixweinberger felixweinberger merged commit a8001ba into docs/develop Jul 3, 2025
4 checks passed
@felixweinberger felixweinberger deleted the fweinberger/docs/restructure branch July 3, 2025 15:49
@felixweinberger

Copy link
Copy Markdown
Contributor Author

Instead of having a persistent tab bar, could we (1) use the logo as the link to the "Overview" page, and (2) put the "Documentation" and "Community" links in the top nav bar?

preview2-edit2

Also, I feel like the sidebar for the Documentation tab is a bit overwhelming, as in "What is all this? Where am I supposed to look?" The /documentation/index page seems like it might be used to provide an overview of all of the items in the sidebar, which I think is good. But reducing the number of immediately visible items might also be helpful (e.g. by adding more collapsed-by-default groups).

Thanks! Good ideas, will check if this is possible with Mintlify.

Also this is still very much a placeholder, definitely not final. Just creating this for folks to "work into" sooner rather than later.

@felixweinberger

Copy link
Copy Markdown
Contributor Author

@jonathanhefner I had a look and unfortunately it looks like the navbar up top only supports hrefs, not relative links (see docs: https://mintlify.com/docs/settings#param-navbar):

❯ npm run serve:docs

> @modelcontextprotocol/specification@0.1.0 serve:docs
> cd docs && mintlify dev

⠋ Preparing local Mintlify instance...🚨 Invalid docs.json:
#.navbar.links[1].href: Must be a valid url
✖ Prebuild step failed

Also, with the proposal to have Specification be its own tab as seen in #909 it might get quite crowded in that area anyway?

@jonathanhefner

Copy link
Copy Markdown
Member

I had a look and unfortunately it looks like the navbar up top only supports hrefs, not relative links (see docs: https://mintlify.com/docs/settings#param-navbar):

It seems like that might a bug in the https://mintlify.com/docs.json schema. According to https://mintlify.com/docs/settings#param-href-1 (emphasis mine):

URL or path for the link destination.

Perhaps we could submit a ticket to Mintlify. (I would recommend an Anthropic employee be the one do so; the last time I submitted a ticket on Anthropic's behalf, customer support suggested incorrect solutions, and then closed the ticket when I requested escalation.)

As a workaround we could hard code the domain as https://modelcontextprotocol.io. Obviously, that would not adapt to local development though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants