Skip to content

Commit fab0d31

Browse files
jonathanhefnerclaude
jonathanhefner
and
claude
committed
Add API documentation with GitHub Pages deployment
This adds automated generation and deployment of versioned API documentation using TypeDoc and GitHub Pages. Documentation will be generated and published when a new release is created. Changes ------- 1. **Documentation generation script** (see `scripts/generate-gh-pages.sh`) Generates TypeDoc documentation for a specific version tag and commits it to the gh-pages branch. The script uses git worktrees to isolate the documentation generation process from the main workspace. Documentation for each release is stored in a versioned directory (e.g., `v1.2.3/`) on the gh-pages branch. The script: - Parses semantic versions from tag names, ignoring arbitrary prefixes (e.g., tags `1.2.3`, `v1.2.3`, and `release-1.2.3` all create `v1.2.3/`) - Creates the gh-pages branch as an orphan branch if it doesn't exist - Generates new doc pages while preserving existing versioned directories - Generates `_data/versions.yml` with a list of all versions for Jekyll templates to consume - Determines the latest version via semantic version sorting - For the latest version only, copies static Jekyll template files from `.github/pages/` to the gh-pages root 2. **Jekyll template files** (see `.github/pages/` directory) - `.github/pages/_config.yml` - Jekyll configuration - `.github/pages/index.html` - Landing page that redirects to the latest version based on generated `_data/versions.yml` 3. **GitHub Actions workflow** (see `.github/workflows/main.yml`) Added a `publish-gh-pages` job that runs after the `publish` job on release events. This ensures documentation is generated and published only after the npm package is successfully published. The job invokes the generation script with the release tag name and pushes the updated gh-pages branch. 4. **CI validation** (see `package.json`) Updated the `check` script to include TypeDoc validation with `--emit none`. This ensures TypeDoc can successfully parse the codebase (without generating output), catching documentation issues early in CI. 5. **Documentation link** (see `README.md`) Added a link to the published API documentation in the Documentation section of the README. TypeDoc Configuration --------------------- TypeDoc is configured via `typedoc.json`: - Uses the `src` directory as the entry point with the `expand` strategy - Explicitly excludes test files, mocks, examples, and integration tests Documentation URL ----------------- Documentation will be available at: https://modelcontextprotocol.github.io/typescript-sdk/ Versioned API documentation will be available at: - https://modelcontextprotocol.github.io/typescript-sdk/ (redirects to latest) - https://modelcontextprotocol.github.io/typescript-sdk/v1.2.3/ (specific versions) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent b9538a2 commit fab0d31

File tree

9 files changed

+418
-1
lines changed

9 files changed

+418
-1
lines changed

‎.github/pages/_config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
title: '@modelcontextprotocol/sdk'
2+
3+
# Include generated files and directories which may start with underscores
4+
include:
5+
- '_*'

‎.github/pages/index.html‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
# Empty Jekyll front matter to enable Liquid templating (see {{ ... }} below)
3+
---
4+
5+
<!doctype html>
6+
<html>
7+
<head>
8+
<meta charset="utf-8" />
9+
<title>Redirecting to latest documentation...</title>
10+
<meta http-equiv="refresh" content="0; url=v{{ site.data.versions[0] }}/" />
11+
<link rel="canonical" href="v{{ site.data.versions[0] }}/" />
12+
</head>
13+
<body>
14+
<p>Redirecting to <a href="v{{ site.data.versions[0] }}/">latest documentation</a>...</p>
15+
<script>
16+
window.location.href = 'v{{ site.data.versions[0] }}/';
17+
</script>
18+
</body>
19+
</html>

‎.github/workflows/main.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,3 +76,35 @@ jobs:
7676
- run: npm publish --provenance --access public ${{ steps.npm-tag.outputs.tag }}
7777
env:
7878
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
79+
80+
publish-gh-pages:
81+
runs-on: ubuntu-latest
82+
if: github.event_name == 'release'
83+
needs: [publish]
84+
85+
permissions:
86+
contents: write
87+
88+
steps:
89+
- uses: actions/checkout@v4
90+
with:
91+
fetch-depth: 0 # Fetch all history for all branches
92+
93+
- uses: actions/setup-node@v4
94+
with:
95+
node-version: 24
96+
cache: npm
97+
98+
- name: Install dependencies
99+
run: npm ci
100+
101+
- name: Configure Git
102+
run: |
103+
git config --global user.name "github-actions[bot]"
104+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
105+
106+
- name: Generate documentation
107+
run: ./scripts/generate-gh-pages.sh ${{ github.ref_name }}
108+
109+
- name: Push to gh-pages
110+
run: git push origin gh-pages

‎.prettierignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,6 @@ pnpm-lock.yaml
1111

1212
# Ignore generated files
1313
src/spec.types.ts
14+
15+
# Jekyll/Liquid template files with special formatting requirements
16+
docs/index.md

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1785,6 +1785,7 @@ app.listen(3000);
17851785

17861786
## Documentation
17871787

1788+
- [SDK API documentation](https://modelcontextprotocol.github.io/typescript-sdk/)
17881789
- [Model Context Protocol documentation](https://modelcontextprotocol.io)
17891790
- [MCP Specification](https://spec.modelcontextprotocol.io)
17901791
- [Example Servers](https://github.com/modelcontextprotocol/servers)

0 commit comments

Comments
 (0)