documcp

# Your First Documentation Deployment This tutorial walks you through deploying your first documentation site using DocuMCP, from analysis to live GitHub Pages deployment. ## What You'll Build By the end of this tutorial, you'll have: - A live documentation site on GitHub Pages - Automated deployment workflow - Professional Diataxis-structured content - Understanding of DocuMCP's deployment process ## Prerequisites - Completed the [Getting Started](getting-started.md) tutorial - GitHub repository with your code - Write access to the repository - GitHub Pages enabled in repository settings ## Step-by-Step Deployment ### Step 1: Complete Repository Analysis If you haven't already, analyze your repository: ```bash # Prompt to DocuMCP: "analyze my repository for documentation deployment" ``` Expected output includes analysis ID (e.g., `analysis_xyz789`) that we'll use throughout the deployment. ### Step 2: Get Deployment-Optimized Recommendations Request recommendations specifically for deployment: ```bash # Prompt: "recommend the best static site generator for GitHub Pages deployment based on analysis_xyz789" ``` DocuMCP will consider: - **GitHub Pages compatibility** (native Jekyll support vs. Actions required) - **Build time** (Hugo's speed vs. Docusaurus features) - **Maintenance overhead** (MkDocs simplicity vs. Eleventy flexibility) ### Step 3: Generate Deployment Configuration Create production-ready configuration: ```bash # For example, if Docusaurus was recommended: "generate Docusaurus configuration for production deployment to GitHub Pages" ``` This creates: - **docusaurus.config.js**: Optimized for GitHub Pages - **package.json updates**: Required dependencies - **Build scripts**: Production build configuration ### Step 4: Set Up Documentation Structure Create comprehensive documentation structure: ```bash # Prompt: "set up Diataxis documentation structure for Docusaurus deployment" ``` Creates organized folders: ``` docs/ ├── tutorials/ # Learning-oriented ├── how-to-guides/ # Problem-solving ├── reference/ # Information-oriented ├── explanation/ # Understanding-oriented └── index.md # Landing page ``` ### Step 5: Populate with Initial Content Generate starter content based on your project: ```bash # Prompt: "populate the documentation structure with content based on my project analysis" ``` DocuMCP creates: - **Project-specific tutorials** based on your codebase - **API documentation** extracted from your code - **Installation guides** tailored to your tech stack - **Configuration examples** using your actual project structure ### Step 6: Deploy to GitHub Pages Set up automated deployment: ```bash # Prompt: "deploy my Docusaurus documentation to GitHub Pages with automated workflow" ``` This generates: - **.github/workflows/deploy.yml**: GitHub Actions workflow - **Optimized build process**: Cached dependencies, parallel builds - **Security configuration**: OIDC tokens, minimal permissions ### Step 7: Verify Deployment Check that everything is working: ```bash # Prompt: "verify my GitHub Pages deployment is working correctly" ``` DocuMCP checks: - **Workflow status**: Build and deployment success - **Site accessibility**: Homepage loads correctly - **Navigation**: All sections are reachable - **Asset loading**: CSS, JS, images work properly ## Example: Complete TypeScript Library Deployment Here's a real example for a TypeScript library: ### 1. Analysis Results ```json { "id": "analysis_ts_lib_001", "structure": { "totalFiles": 47, "languages": { ".ts": 32, ".md": 5, ".json": 3 }, "hasTests": true, "hasCI": true }, "recommendations": { "primaryLanguage": "typescript", "projectType": "library" } } ``` ### 2. Recommendation ```json { "recommended": "docusaurus", "confidence": 0.88, "reasoning": [ "TypeScript ecosystem alignment", "Excellent API documentation support", "React component integration for examples" ] } ``` ### 3. Generated Configuration **docusaurus.config.js**: ```javascript const config = { title: 'TypeScript Library Docs', tagline: 'Comprehensive API documentation', url: 'https://yourusername.github.io', baseUrl: '/your-repo-name/', // GitHub Pages deployment config organizationName: 'yourusername', projectName: 'your-repo-name', deploymentBranch: 'gh-pages', trailingSlash: false, presets: [ [ 'classic', { docs: { routeBasePath: '/', sidebarPath: require.resolve('./sidebars.js'), }, theme: { customCss: require.resolve('./src/css/custom.css'), }, }, ], ], }; ``` ### 4. GitHub Actions Workflow **.github/workflows/deploy.yml**: ```yaml name: Deploy Documentation on: push: branches: [main] paths: ['docs/**', 'docusaurus.config.js'] permissions: contents: read pages: write id-token: write jobs: deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' - name: Install dependencies run: npm ci - name: Build documentation run: npm run build - name: Setup Pages uses: actions/configure-pages@v4 - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: './build' - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 ``` ## Verification Checklist After deployment, verify: - [ ] **Site is live** at `https://yourusername.github.io/repository-name` - [ ] **All sections load** (Tutorials, How-to, Reference, Explanation) - [ ] **Search works** (if enabled) - [ ] **Mobile responsive** design - [ ] **Fast loading** (check Core Web Vitals) - [ ] **SEO optimized** (meta tags, sitemap) ## Common Deployment Issues ### Build Failures **Problem**: Workflow fails during build **Solution**: - Check Node.js version compatibility - Verify all dependencies are in package.json - Review build logs in Actions tab ### Page Not Found (404) **Problem**: Site shows 404 error **Solution**: - Verify `baseUrl` in config matches repository name - Check GitHub Pages source is set to GitHub Actions - Confirm deployment branch exists ### Assets Not Loading **Problem**: CSS/JS files return 404 **Solution**: - Ensure `publicPath` is configured correctly - Check trailing slash configuration - Verify asset paths are relative ## Performance Optimization ### Build Speed - **Caching**: Enable npm cache in GitHub Actions - **Parallel builds**: Use appropriate number of workers - **Incremental builds**: Only rebuild changed files ### Site Performance - **Image optimization**: Compress and use modern formats - **Code splitting**: Load only necessary JavaScript - **CDN integration**: Use GitHub's CDN for assets ## Next Steps Now that you have a deployed documentation site: 1. **[Set up development workflow](development-setup.md)** for ongoing maintenance 2. **[Configure custom domain](../how-to/custom-domains.md)** (optional) 3. **[Set up monitoring](../how-to/site-monitoring.md)** for uptime tracking 4. **[Optimize for search](../how-to/seo-optimization.md)** engines ## Summary You've successfully: ✅ Analyzed your repository for deployment ✅ Generated production-ready configuration ✅ Set up professional documentation structure ✅ Deployed to GitHub Pages with automation ✅ Verified your live documentation site Your documentation is now live and will automatically update with each commit! ## Troubleshooting If you encounter issues: 1. Check the [troubleshooting guide](../how-to/troubleshooting.md) 2. Review GitHub Actions logs 3. Verify repository permissions 4. Confirm GitHub Pages settings Need help? Open an issue on the [DocuMCP repository](https://github.com/tosin2013/documcp/issues).