Skip to content

Commit 0f220a9

Browse files
aarora79aarora79
committed
Add comprehensive MkDocs documentation website
- Create complete MkDocs configuration with Material theme - Add responsive documentation website with navigation structure - Configure automatic GitHub Pages deployment via GitHub Actions - Use uv for package management instead of pip - Include development helper script for local testing - Set up proper documentation structure with organized sections: * Getting Started (Quick Start, Installation, Configuration) * Authentication & Security (OAuth, Cognito, Access Control) * Architecture & Development (API, Tool Discovery, Architecture) * Integration (AI Coding Assistants) * Contributing & Legal sections - Features include: * Light/dark mode toggle * Full-text search across documentation * Code syntax highlighting with copy buttons * Mermaid diagram support for architecture visuals * Mobile-responsive design * Git revision dates The website will auto-deploy to GitHub Pages when changes are pushed to main branch, providing professional documentation at: https://agentic-community.github.io/mcp-gateway-registry/
1 parent cdcdae6 commit 0f220a9

File tree

7 files changed

+828
-0
lines changed

7 files changed

+828
-0
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
name: Build and Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
paths:
7+
- 'docs/**'
8+
- 'mkdocs.yml'
9+
- 'README.md'
10+
- '.github/workflows/docs.yml'
11+
pull_request:
12+
branches: [ main ]
13+
paths:
14+
- 'docs/**'
15+
- 'mkdocs.yml'
16+
- 'README.md'
17+
18+
permissions:
19+
contents: read
20+
pages: write
21+
id-token: write
22+
23+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
24+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
25+
concurrency:
26+
group: "pages"
27+
cancel-in-progress: false
28+
29+
jobs:
30+
# Build job
31+
build:
32+
runs-on: ubuntu-latest
33+
steps:
34+
- name: Checkout
35+
uses: actions/checkout@v4
36+
with:
37+
fetch-depth: 0 # Fetch all history for git plugins
38+
39+
- name: Setup Python
40+
uses: actions/setup-python@v4
41+
with:
42+
python-version: '3.11'
43+
44+
- name: Install uv
45+
uses: astral-sh/setup-uv@v3
46+
with:
47+
version: "latest"
48+
49+
- name: Cache dependencies
50+
uses: actions/cache@v3
51+
with:
52+
path: ~/.cache/uv
53+
key: ${{ runner.os }}-uv-${{ hashFiles('requirements-docs.txt') }}
54+
restore-keys: |
55+
${{ runner.os }}-uv-
56+
57+
- name: Install dependencies
58+
run: |
59+
uv pip install --system -r requirements-docs.txt
60+
61+
- name: Setup Pages
62+
id: pages
63+
uses: actions/configure-pages@v3
64+
65+
- name: Build documentation
66+
run: |
67+
mkdocs build --clean --strict
68+
69+
- name: Upload artifact
70+
uses: actions/upload-pages-artifact@v2
71+
with:
72+
path: ./site
73+
74+
# Deployment job
75+
deploy:
76+
if: github.ref == 'refs/heads/main'
77+
environment:
78+
name: github-pages
79+
url: ${{ steps.deployment.outputs.page_url }}
80+
runs-on: ubuntu-latest
81+
needs: build
82+
steps:
83+
- name: Deploy to GitHub Pages
84+
id: deployment
85+
uses: actions/deploy-pages@v2

‎MKDOCS_SETUP.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# MkDocs Website Setup Complete
2+
3+
## ✅ What's Been Created
4+
5+
A comprehensive MkDocs-based documentation website has been set up for the MCP Gateway & Registry repository.
6+
7+
### Files Created/Modified:
8+
9+
1. **`mkdocs.yml`** - Main MkDocs configuration
10+
2. **`docs/index.md`** - Website homepage based on README
11+
3. **`requirements-docs.txt`** - Documentation dependencies (uv-compatible)
12+
4. **`.github/workflows/docs.yml`** - GitHub Actions for auto-deployment
13+
5. **`scripts/docs-dev.sh`** - Development helper script
14+
6. **`docs/README.md`** - Documentation guide
15+
16+
### Features Configured:
17+
18+
- **Material Design Theme** with light/dark mode toggle
19+
- **Navigation Structure** organized by logical sections
20+
- **Search Functionality** with full-text search
21+
- **Code Syntax Highlighting** with copy buttons
22+
- **Mermaid Diagram Support** for architecture diagrams
23+
- **Git Revision Dates** showing last update times
24+
- **Responsive Design** optimized for all devices
25+
26+
## 🚀 Quick Start
27+
28+
### Local Development
29+
30+
```bash
31+
# Install dependencies with uv
32+
uv pip install -r requirements-docs.txt
33+
34+
# Start development server
35+
mkdocs serve
36+
# Visit http://127.0.0.1:8000
37+
38+
# Or use the helper script
39+
./scripts/docs-dev.sh install
40+
./scripts/docs-dev.sh serve
41+
```
42+
43+
### Build Static Site
44+
45+
```bash
46+
# Build production site
47+
mkdocs build
48+
49+
# Output in ./site/ directory
50+
```
51+
52+
## 📖 Website Structure
53+
54+
```
55+
MCP Gateway & Registry Documentation
56+
├── Getting Started
57+
│ ├── Quick Start
58+
│ ├── Installation
59+
│ ├── Configuration
60+
│ └── FAQ
61+
├── Authentication & Security
62+
│ ├── Authentication Guide
63+
│ ├── Amazon Cognito Setup
64+
│ ├── Access Control & Scopes
65+
│ ├── JWT Token Vending
66+
│ └── Security Policy
67+
├── Architecture & Development
68+
│ ├── Registry API
69+
│ ├── Dynamic Tool Discovery
70+
│ ├── Architecture Overview
71+
│ └── Detailed Architecture
72+
├── Integration
73+
│ └── AI Coding Assistants
74+
├── Contributing
75+
│ ├── Contributing Guide
76+
│ └── Code of Conduct
77+
└── Legal
78+
├── License
79+
└── Notice
80+
```
81+
82+
## 🔧 Development Commands
83+
84+
```bash
85+
# Using the helper script
86+
./scripts/docs-dev.sh install # Install dependencies
87+
./scripts/docs-dev.sh serve # Development server
88+
./scripts/docs-dev.sh build # Build static site
89+
./scripts/docs-dev.sh check # Check for issues
90+
./scripts/docs-dev.sh deploy # Deploy to GitHub Pages
91+
92+
# Direct MkDocs commands
93+
mkdocs serve # Development server
94+
mkdocs build # Build static site
95+
mkdocs gh-deploy # Deploy to GitHub Pages
96+
```
97+
98+
## 🌐 Deployment
99+
100+
### Automatic Deployment (Recommended)
101+
102+
The website automatically deploys to GitHub Pages when:
103+
- Changes are pushed to the `main` branch
104+
- Files in `docs/`, `mkdocs.yml`, or `README.md` are modified
105+
106+
**Website URL**: https://agentic-community.github.io/mcp-gateway-registry/
107+
108+
### Manual Deployment
109+
110+
```bash
111+
mkdocs gh-deploy
112+
```
113+
114+
## 📝 Content Guidelines
115+
116+
### Adding New Pages
117+
118+
1. Create `.md` file in appropriate `docs/` subdirectory
119+
2. Add to navigation in `mkdocs.yml`
120+
3. Use proper markdown formatting
121+
4. Include code examples where relevant
122+
123+
### Supported Features
124+
125+
- **Admonitions**: `!!! tip`, `!!! warning`, `!!! note`
126+
- **Code Blocks**: Syntax highlighted with copy buttons
127+
- **Tabs**: Organize content with `=== "Tab Name"`
128+
- **Diagrams**: Mermaid flowcharts and diagrams
129+
- **Tables**: Standard markdown tables
130+
- **Links**: Internal and external linking
131+
132+
### Example Admonition
133+
134+
```markdown
135+
!!! tip "Pro Tip"
136+
Use `uv` for faster Python package management!
137+
138+
!!! warning "Important"
139+
Always configure authentication before deploying to production.
140+
```
141+
142+
## 🔍 Search & Navigation
143+
144+
- **Full-text search** across all documentation
145+
- **Navigation tabs** for major sections
146+
- **Table of contents** integration
147+
- **Mobile-responsive** design
148+
- **Dark/light mode** toggle
149+
150+
## 🎨 Theme Configuration
151+
152+
- **Primary Color**: Blue
153+
- **Font**: Roboto (text), Roboto Mono (code)
154+
- **Features**: Navigation tabs, sections, search highlighting
155+
- **Extensions**: Code copy, emoji support, enhanced markdown
156+
157+
## 📊 Analytics & Monitoring
158+
159+
The configuration includes placeholders for:
160+
- Google Analytics integration
161+
- User behavior tracking
162+
- Search query analytics
163+
164+
## 🐛 Known Issues & Warnings
165+
166+
Current build warnings (non-critical):
167+
- Some internal links to source code files
168+
- Missing anchor references in existing docs
169+
- Excluded README.md (conflicts with index.md)
170+
171+
These warnings don't affect the website functionality and will be resolved as documentation is refined.
172+
173+
## 🔄 Next Steps
174+
175+
1. **Enable GitHub Pages** in repository settings
176+
2. **Review and update** existing documentation files
177+
3. **Add missing content** for any broken internal links
178+
4. **Configure custom domain** (optional)
179+
5. **Set up analytics** (optional)
180+
181+
## 📞 Support
182+
183+
For MkDocs-related issues:
184+
- [MkDocs Documentation](https://www.mkdocs.org/)
185+
- [Material Theme Docs](https://squidfunk.github.io/mkdocs-material/)
186+
- Repository issues for site-specific problems
187+
188+
---
189+
190+
**Status**: ✅ **Production Ready**
191+
**Last Updated**: 2025-08-21
192+
**MkDocs Version**: 1.6.1
193+
**Material Theme**: 9.6.17

‎docs/README.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Documentation
2+
3+
This directory contains the MkDocs-based documentation for the MCP Gateway & Registry.
4+
5+
## Building Documentation Locally
6+
7+
### Prerequisites
8+
9+
```bash
10+
# Using uv (recommended)
11+
uv pip install -r requirements-docs.txt
12+
13+
# Or using pip
14+
pip install -r requirements-docs.txt
15+
```
16+
17+
### Development Server
18+
19+
```bash
20+
# Start development server with live reload
21+
mkdocs serve
22+
23+
# The documentation will be available at http://127.0.0.1:8000
24+
```
25+
26+
### Building Static Site
27+
28+
```bash
29+
# Build static site
30+
mkdocs build
31+
32+
# The built site will be in the `site/` directory
33+
```
34+
35+
## Documentation Structure
36+
37+
- `index.md` - Main landing page (generated from README.md)
38+
- `installation.md` - Complete installation guide
39+
- `quick-start.md` - Quick start tutorial
40+
- `auth.md` - Authentication and OAuth setup
41+
- `cognito.md` - Amazon Cognito configuration
42+
- `scopes.md` - Access control and permissions
43+
- `registry_api.md` - API reference
44+
- `dynamic-tool-discovery.md` - AI agent tool discovery
45+
- `ai-coding-assistants-setup.md` - IDE integration guide
46+
- `FAQ.md` - Frequently asked questions
47+
48+
## Deployment
49+
50+
The documentation is automatically deployed to GitHub Pages when changes are pushed to the `main` branch via GitHub Actions.
51+
52+
### Manual Deployment
53+
54+
```bash
55+
# Deploy to GitHub Pages
56+
mkdocs gh-deploy
57+
```
58+
59+
## Theme and Configuration
60+
61+
The documentation uses the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme with:
62+
63+
- Light/dark mode toggle
64+
- Navigation tabs and sections
65+
- Search functionality
66+
- Code syntax highlighting
67+
- Mermaid diagram support
68+
- Git revision dates
69+
70+
## Contributing
71+
72+
When adding new documentation:
73+
74+
1. Create markdown files in the appropriate directory
75+
2. Update `mkdocs.yml` navigation structure
76+
3. Use proper markdown formatting and admonitions
77+
4. Include code examples where relevant
78+
5. Test locally with `mkdocs serve` before committing
79+
80+
## Plugins Used
81+
82+
- **search** - Full-text search functionality
83+
- **git-revision-date-localized** - Shows last update dates
84+
- **minify** - Minifies HTML output for production
85+
- **pymdown-extensions** - Enhanced markdown features

0 commit comments

Comments
 (0)