Cloud Docs Hub

Centralized documentation hub for cloud infrastructure, DevOps workflows, and development best practices. This repository uses MkDocs with Material theme to provide comprehensive documentation for AWS, FastAPI, FastMCP, and GitHub Copilot.

Features

• 📚 Comprehensive documentation for cloud and development technologies
• 🎨 Beautiful Material Design theme with dark/light mode
• 🔍 Full-text search functionality
• 📱 Responsive design for mobile and desktop
• 🎯 Easy navigation with top navigation tabs

Prerequisites

• Python 3.8 or higher
• pip (Python package installer)

Quick Start

1. Clone the Repository

git clone https://github.com/mcuellar/cloud-docs-hub.git
cd cloud-docs-hub

2. Set Up Virtual Environment

On macOS/Linux:

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate

On Windows:

# Create virtual environment
python -m venv .venv

# Activate virtual environment
venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Run MkDocs Locally

# Start the development server
mkdocs serve

# Optional. If auto-reload not working
mkdocs serve --livereload

The documentation site will be available at http://127.0.0.1:8000/

The development server features:

• Auto-reload when you make changes to documentation files
• Live preview of your edits
• Fast rebuild times

Building the Documentation

To build the static site for deployment:

mkdocs build

This will create a site/ directory with the static HTML files.

Project Structure

cloud-docs-hub/
├── docs/                      # Documentation source files
│   ├── index.md              # Home page
│   ├── aws/                  # AWS documentation
│   │   └── index.md
│   ├── fastapi/              # FastAPI documentation
│   │   └── index.md
│   ├── fastmcp/              # FastMCP documentation
│   │   └── index.md
│   └── github-copilot/       # GitHub Copilot documentation
│       └── index.md
├── mkdocs.yml                # MkDocs configuration file
├── requirements.txt          # Python dependencies
└── README.md                # This file

Navigation

The site includes the following top-level navigation items:

• Home: Introduction and overview
• AWS: Amazon Web Services documentation
• FastAPI: Modern Python web framework guides
• FastMCP: Fast Model Context Protocol documentation
• GitHub Copilot: AI-powered coding assistant guides

Adding New Documentation

1. Create a new Markdown file in the appropriate directory under docs/
2. Update mkdocs.yml to include the new page in the navigation
3. The changes will be reflected immediately if you're running mkdocs serve

Example:

nav:
  - Home: index.md
  - AWS:
      - Overview: aws/index.md
      - EC2 Guide: aws/ec2.md  # New page

Customization

Changing Theme Colors

Edit the theme.palette section in mkdocs.yml:

theme:
  palette:
    - scheme: default
      primary: indigo  # Change this
      accent: indigo   # Change this

Adding Extensions

MkDocs supports various Markdown extensions. Add them in mkdocs.yml:

markdown_extensions:
  - your_extension_here

Deployment

GitHub Pages

To deploy to GitHub Pages:

mkdocs gh-deploy

This command builds the documentation and pushes it to the gh-pages branch.

Other Platforms

The site/ directory generated by mkdocs build can be deployed to any static hosting service:

• Netlify
• Vercel
• AWS S3
• Azure Static Web Apps

Deactivating Virtual Environment

When you're done working:

deactivate

Troubleshooting

Port Already in Use

If port 8000 is already in use, specify a different port:

mkdocs serve -a localhost:8001

Module Not Found

Make sure you've activated the virtual environment and installed dependencies:

source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt

Changes Not Reflecting

Try force-refreshing your browser (Ctrl+F5 or Cmd+Shift+R) or clearing the browser cache.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Make your changes
4. Test locally with mkdocs serve
5. Commit your changes (git commit -am 'Add some feature')
6. Push to the branch (git push origin feature/your-feature)
7. Create a Pull Request

Additional Resources

• MkDocs Documentation
• Material for MkDocs
• Markdown Guide

License

This project is open source and available for use in documentation and educational purposes.