mcpGraph

# GitHub Pages Setup for Skills Distribution This document describes how to set up GitHub Pages to host mcpGraph documentation and distribute the skills package as a downloadable zip file. ## Overview We'll use GitHub Pages to create a static site that: 1. Hosts mcpGraph configuration documentation 2. Provides a download link for the Agent Skills zip file 3. Automatically updates when the skills directory changes **Note:** The `/skills` directory follows the [Agent Skills specification](https://agentskills.io/), containing skill subdirectories with `SKILL.md` files that have YAML frontmatter and markdown content. ## Repository Structure ``` mcpGraph/ ├── skills/ # Agent Skills directory (https://agentskills.io/) │ └── build-mcpgraph/ # Skill subdirectory │ └── SKILL.md # Skill file with YAML frontmatter + markdown content ├── docs/ # Existing documentation source (markdown files) │ ├── design.md │ ├── implementation.md │ ├── introspection-debugging.md │ └── github-pages-setup.md ├── site/ # Jekyll site source (all site files isolated here) │ ├── _config.yml # Jekyll configuration │ ├── _layouts/ # Layout templates │ ├── _includes/ # Partial templates │ ├── _sass/ # Stylesheets │ ├── assets/ # CSS, images, JS │ ├── pages/ # Documentation pages (copied from /docs or written here) │ ├── index.html # Landing page │ └── downloads/ # Agent Skills zip placed here by workflow │ └── skills.zip # Contains skills/ directory structure ├── .github/ │ └── workflows/ │ └── build-pages.yml # GHA to build and deploy └── package.json # Generated output (not in repo): # - Jekyll builds to site/_site/ (default, gitignored) # - GitHub Actions copies _site/ contents to gh-pages branch # - GitHub Pages serves from gh-pages branch ``` **Key Points:** - `/docs` stays as source markdown (no generated files) - `/site` contains all Jekyll source files (isolated) - Jekyll builds to `site/_site/` (default output, gitignored) - GitHub Actions copies `_site/` to `gh-pages` branch - GitHub Pages serves from `gh-pages` branch (not `/docs`) ## GitHub Pages Configuration We'll use the `gh-pages` branch for deployment: - GitHub Pages serves from `gh-pages` branch - Keeps source directories clean (no generated files in `/docs` or `/site`) - Generated site is completely separate from source - GitHub Actions builds and pushes to `gh-pages` branch automatically ## Build and Deploy Process ### Jekyll Build Process **Local Development:** ```bash cd site bundle exec jekyll build # Builds to site/_site/ bundle exec jekyll serve # Serves locally at http://localhost:4000 ``` **Production Build (via GitHub Actions):** 1. Jekyll builds from `/site` directory 2. Outputs to `site/_site/` (Jekyll default, gitignored) 3. Skills zip is created and placed in `site/downloads/` 4. Contents of `site/_site/` are copied to `gh-pages` branch 5. GitHub Pages automatically serves from `gh-pages` branch ### GitHub Actions Workflow: `build-pages.yml` **Triggers:** - Push to `main` branch when `/skills` directory changes - Push to `main` branch when `/site` directory changes - Manual workflow dispatch - Scheduled (optional: daily check) **Workflow Steps:** 1. **Checkout repository** 2. **Set up Ruby and Jekyll:** - Install Ruby - Install Bundler - Install Jekyll and dependencies 3. **Create skills zip:** - Zip entire `/skills` directory (preserving subdirectory structure) - Name it `skills.zip` - Place in `site/downloads/` (so it's included in Jekyll build) 4. **Build Jekyll site:** - Change to `/site` directory - Run `bundle exec jekyll build` - Output goes to `site/_site/` (includes skills.zip in downloads/) 5. **Deploy to gh-pages branch:** - Checkout or create `gh-pages` branch - Copy all contents from `site/_site/` to `gh-pages` branch root - Commit and push to `gh-pages` branch - GitHub Pages automatically deploys from `gh-pages` branch **Note:** GitHub Pages will automatically rebuild and serve the site when `gh-pages` branch is updated. ### Workflow Details **Path filtering for skills changes:** ```yaml on: push: branches: [main] paths: - 'skills/**' # Trigger on any changes to skills directory - '.github/workflows/build-pages.yml' ``` **Note:** This will trigger when any skill subdirectory or `SKILL.md` file changes. **Zip creation:** - Use `zip` command or Node.js script - Include all files in `/skills` directory - Preserve directory structure ## GitHub Pages Setup Steps 1. **Enable GitHub Pages:** - Go to repository Settings → Pages - Source: Deploy from a branch - Branch: `gh-pages` / folder: `/` (root) - GitHub Actions will create and maintain `gh-pages` branch 2. **Create initial Jekyll site structure:** - Set up `/site` directory with Jekyll - Create landing page with download link 3. **Set up workflow:** - Create `.github/workflows/build-pages.yml` - Configure to build and deploy on skills changes 4. **Test:** - Make a change to `/skills` directory - Push to trigger workflow - Verify site updates at `https://[username].github.io/mcpGraph/` ## Building the Jekyll Site We'll build a proper website with Jekyll that includes: - Navigation menu - Styling and graphics - Responsive design - Professional appearance ### Jekyll Setup **Why Jekyll:** - Native GitHub Pages support - Markdown to HTML conversion built-in - Theme support (can use GitHub Pages themes or custom) - Liquid templating for navigation, menus, etc. - All site files isolated in `/site` directory **Structure - Isolated in `/site` directory:** ``` mcpGraph/ ├── site/ # All Jekyll files isolated here │ ├── _config.yml # Jekyll configuration │ ├── _layouts/ │ │ ├── default.html # Base layout template │ │ └── page.html # Page layout │ ├── _includes/ │ │ ├── header.html # Site header/navigation │ │ ├── footer.html # Site footer │ │ └── sidebar.html # Optional sidebar │ ├── _sass/ # SCSS stylesheets │ │ └── main.scss │ ├── assets/ │ │ ├── css/ │ │ │ └── style.css # Compiled CSS │ │ ├── images/ # Graphics, logos, etc. │ │ └── js/ # JavaScript if needed │ ├── index.html # Landing page (front matter for Jekyll) │ ├── pages/ # Documentation source │ │ ├── configuration-guide.md │ │ ├── design.md │ │ └── ... │ └── downloads/ # Skills zip will be placed here │ └── skills.zip ├── skills/ # Agent Skills directory (Agent Skills spec) │ └── build-mcpgraph/ # Skill subdirectory │ └── SKILL.md # YAML frontmatter + markdown └── ... # Rest of repo (clean, no Jekyll clutter) ``` **Key Configuration:** - All Jekyll source files in `/site` directory - Build output goes to `site/_site/` (Jekyll default, gitignored) - GitHub Actions copies `_site/` to `gh-pages` branch - Repository root stays clean - Skills directory follows [Agent Skills specification](https://agentskills.io/) **Jekyll Configuration (`site/_config.yml`):** ```yaml title: mcpGraph description: MCP server for executing directed graphs theme: minima # Or use custom theme plugins: - jekyll-feed - jekyll-sitemap # Source (relative to site/ directory) source: . # Destination (Jekyll default is _site/, which is fine) # No need to specify - uses default _site/ output directory # Base URL for GitHub Pages baseurl: "" # Or "/mcpGraph" if using project pages url: "https://[username].github.io" # Navigation navigation: - title: Home url: / - title: Configuration Guide url: /pages/configuration-guide - title: Design url: /pages/design - title: Download Skills url: /downloads/skills.zip ``` **Build Process:** 1. Jekyll builds from `/site` directory 2. Output goes to `site/_site/` (Jekyll default, gitignored) 3. GitHub Actions workflow: - Builds Jekyll site - Creates skills zip - Copies `_site/` contents to `gh-pages` branch 4. GitHub Pages serves from `gh-pages` branch 5. Source directories (`/docs`, `/site`) remain clean - no generated files **Benefits:** - Repository root stays clean (no Jekyll clutter) - All site files isolated in `/site` - Markdown files become HTML pages automatically - Easy to add navigation, menus, search - Can use existing Jekyll themes or build custom - Clear separation between site and project files ## Site Features to Include ### Navigation Menu - Home - Documentation sections - Download Skills link - GitHub repository link - Search (if using Jekyll with search plugin) ### Landing Page - Hero section with mcpGraph description - Quick start guide - Download section (prominent skills.zip link) - Documentation overview - Examples/use cases ### Documentation Pages - Sidebar navigation - Table of contents - Code syntax highlighting - Responsive design - Print-friendly styles ### Styling - Professional color scheme - mcpGraph branding/logo - Consistent typography - Mobile-responsive - Accessible design ## Assets to Include - **Logo/Icon** - mcpGraph logo - **Graphics** - Diagrams, flowcharts, architecture diagrams - **Screenshots** - Example configurations, visualizations - **Favicon** - Site favicon - **CSS** - Custom stylesheets - **Fonts** - Web fonts if desired ## Complete GitHub Actions Workflow Example Here's a complete workflow file for building and deploying the Jekyll site: **File: `.github/workflows/build-pages.yml`** ```yaml name: Build and Deploy Site on: push: branches: [main] paths: - 'skills/**' - 'site/**' - '.github/workflows/build-pages.yml' workflow_dispatch: # Allow manual triggering jobs: build-and-deploy: runs-on: ubuntu-latest permissions: contents: write # Required to push to gh-pages branch steps: - name: Checkout repository uses: actions/checkout@v4 - name: Set up Ruby uses: ruby/setup-ruby@v1 with: ruby-version: '3.1' bundler-cache: true working-directory: ./site - name: Install Jekyll dependencies working-directory: ./site run: bundle install - name: Create skills zip run: | cd skills zip -r ../site/downloads/skills.zip . # Creates: site/downloads/skills.zip # This will be included in Jekyll build output - name: Build Jekyll site working-directory: ./site run: bundle exec jekyll build # Outputs to: site/_site/ - name: Deploy to gh-pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./site/_site # Copies everything from _site/ to gh-pages branch root # GitHub Pages automatically serves from gh-pages branch ``` **What this workflow does:** 1. Triggers on changes to `/skills` or `/site` directories 2. Sets up Ruby and Jekyll environment 3. Creates skills zip and places it in `site/downloads/` 4. Builds Jekyll site (outputs to `site/_site/`) 5. Deploys `_site/` contents to `gh-pages` branch 6. GitHub Pages automatically serves the updated site ## Site Content ### Landing Page - Hero section with title and description - Feature highlights - Quick start section - Download call-to-action - Documentation preview ### Agent Skills Zip Contents The zip file contains the `/skills` directory structure following the [Agent Skills specification](https://agentskills.io/): ``` skills/ build-mcpgraph/ SKILL.md # YAML frontmatter (name, description) + markdown content ``` Each `SKILL.md` file contains: - YAML frontmatter with skill metadata (name, description, etc.) - Markdown content with instructions for agents on how to create mcpGraph configurations ## Implementation Checklist ### Phase 1: Basic Setup - [ ] Create `/skills` directory structure - [ ] Create skill subdirectory (e.g., `build-mcpgraph/`) in `/skills` - [ ] Create `SKILL.md` file with YAML frontmatter and markdown content - [ ] Set up site structure (Jekyll config, layouts, etc.) - [ ] Set up GitHub Pages (enable in settings) ### Phase 2: Site Development - [ ] Create base layout with navigation - [ ] Design and implement styling (CSS/theme) - [ ] Create landing page (`index.html` or `index.md`) - [ ] Convert existing docs to site format - [ ] Add graphics/assets (logo, images, etc.) - [ ] Set up navigation menu - [ ] Test site locally (`bundle exec jekyll serve`) ### Phase 3: Automation - [ ] Create GitHub Actions workflow for skills zip - [ ] Configure workflow to integrate zip into site - [ ] Test workflow with a skills directory change - [ ] Verify site builds and deploys correctly - [ ] Verify site is accessible at GitHub Pages URL ### Phase 4: Polish - [ ] Add search functionality (if desired) - [ ] Optimize images and assets - [ ] Add analytics (optional) - [ ] Test responsive design - [ ] Review and refine content ## Notes - GitHub Pages is free for public repositories - Site will be available at: `https://[username].github.io/mcpGraph/` - Custom domain can be configured if needed - Workflow runs automatically on pushes (no manual steps) - Skills zip will always be up-to-date with latest changes - Jekyll sites can be tested locally with `bundle exec jekyll serve` - **Source directories stay clean** - `/docs` and `/site` contain only source files - Generated output goes to `site/_site/` (gitignored) and then to `gh-pages` branch - `gh-pages` branch contains only the generated static site (not in main branch) ## Quick Start: Jekyll Setup (Isolated in `/site`) 1. **Create site directory:** ```bash mkdir site cd site ``` 2. **Initialize Jekyll in site directory:** ```bash gem install bundler jekyll jekyll new . --force # Creates Jekyll structure in site/ ``` 3. **Configure `site/_config.yml`:** ```yaml title: mcpGraph description: MCP server for executing directed graphs theme: minima # Or use custom theme baseurl: "" # Or "/mcpGraph" if using project pages url: "https://[username].github.io" ``` - Set site title, description - Configure theme or custom styling - Set up navigation - Note: Uses default `_site/` output directory (no need to specify) 4. **Create layouts:** - Base layout with header/footer in `site/_layouts/` - Page layout for docs - Include navigation partial in `site/_includes/` 5. **Add content:** - Create `site/pages/` directory for documentation - Convert markdown docs to Jekyll format - Add front matter (YAML header) to each page - Copy existing docs to `site/pages/` or create new ones 6. **Style:** - Use existing theme or create custom CSS - Add assets (images, fonts, etc.) to `site/assets/` 7. **Test locally:** ```bash cd site bundle exec jekyll build # Builds to _site/ (default) bundle exec jekyll serve # Serves from _site/ # Visit http://localhost:4000 ``` 8. **Set up GitHub Actions:** - Create workflow to: - Build Jekyll from `/site` (outputs to `site/_site/`) - Create skills zip and place in `site/downloads/` - Copy `site/_site/*` contents to `gh-pages` branch - Commit and push `gh-pages` branch 9. **Deploy:** - Push to repository - GitHub Actions builds and pushes to `gh-pages` - GitHub Pages automatically serves from `gh-pages` branch - Source directories (`/docs`, `/site`) remain clean